byu-oit / byu-jwt-nodejs Goto Github PK

View Code? Open in Web Editor NEW

1.0 31.0 0.0 657 KB

This package provides helpful functions for validating and using BYU's JWTs.

License: Apache License 2.0

JavaScript 1.72% Shell 0.22% TypeScript 98.06%

auth fastify-jwt jwt

byu-jwt-nodejs's Introduction

Packages

This repository hosts the following Node.js packages for API development at BYU OIT:

The documentation and source code for previous versions of the byu-jwt package are found on the v3 branch in this repository.

Note Requires Node.js >= v18 OR a fetch polyfill such as node-fetch.

Contributing

This project uses Lerna with Nx to build, test, and lint the source code. Please consult their documentation when making modifications to the maintenance process of this project.

There are a few commands that most of the packages share:

build: Compile the distribution code
lint: Lint the source code
test: Test the source code with Ava

If you notice a problem, please submit an issue or create a PR with the fix!

Committing

Commit messages must adhere to the angular conventional commit standard. commitlint will enforce commit messages to follow this standard. Following a commit standard enables our distribution pipeline to publish new versions of each package automatically.

Building

This library exposes files in both CJS and ESM syntax in order to accommodate browser environments and legacy Node.js applications. CJS support may be dropped in the future but is supported for the time being.

There are two ways that we know of to support both CJS and ESM syntax:

Create a localized package.json file in each packages' cjs directory with the contents { type: 'commonjs' }. This effectively overwrites the package's own package.json which is set to module.

Node Resolution Algorithm: See ESM_FILE_FORMAT

ESM & CommonJS Module Tutorial: https://www.sensedeep.com/blog/posts/2021/how-to-create-single-source-npm-module.html
Use a tool such as unbuild which outputs files with the .cjs and .mjs extensions.

Example of Using unbuild: https://github.com/unjs/radix3/blob/main/package.json

MDN Docs: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules

This library uses the first method for two reasons:

Some tools may never support the .mjs extension
(package.json).type is more deterministic since the resolution algorithm is built into node and bundlers.

Testing

The choice to use Ava was made because it

supports TypeScript and ESM out of the box
parallelizes tests in separate environments making ava typically faster
does not mutate Node.js globals like Jest
follows a similar convention as the node test runner which we may eventually adopt

Running tests requires building the source code first, which should be handled for you by lerna.

From the root of the project you can run:

npm test

Note There is a bug in Node.js Worker threads which requires us to use the --no-worker-threads flag when running tests. Even with that flag enabled, some tests run into this bug. There isn't a bug report for the issue yet (See this discussion).

Publishing

Merging changes into the main branch will automatically update the version of each package, publish the package, and publish the changelog according to the commit messages.

Merging changes into the beta branch will trigger the same GitHub workflow but the beta prefix will be prepended to the new versions published.

The publish workflow was heavily inspired by the article "Automatic versioning in a Lerna monorepo using Github actions" by Xavier Canchal 👏.

Documentation & Linting

Writing SDKs with TypeScript and TSDocs provides consumers with the code and documentation all from their development environments. To that end, running the linter without documenting code with TSDocs style documentation (similar to JSDocs or JavaDocs), will return a non-zero exit code.

byu-jwt-nodejs's People

Contributors

Stargazers

Watchers

byu-jwt-nodejs's Issues

Include link to documentation once published

          Link, please. 🙂

Originally posted by @GaryGSC in #89 (comment)

Rename publish jobs to improve clarity / Add a job GitHub pages docs

          We should clean up some of the naming to make it obvious at first glance that this is publishing docs to GitHub Pages. It might also be worth making this a separate job that runs in parallel as part of the other publishing workflow.

The idea would be to have the following jobs:

Publish / Docs on GitHub Pages
Publish / GitHub release
Publish / GitHub package
Publish / npm package

Originally posted by @GaryGSC in #89 (comment)

Some Windows machines give error: 'Could not find openssl on your system on this path: openssl'

Looks like pem, one of the dependencies, needs openssl.

Possible solution:
https://www.npmjs.com/package/pem#setting-openssl-location

Edit: String that worked: C:\OpenSSL-Win32\bin\openssl

Instantiation prevents graceful shutdown.

When setting up a new Express server, simply instantiating the ByuJWT library prevents the server from terminating gracefully when using Ctrl+C; stopping the server has to be done forcefully. This is the code I'm using (we are using imports in our project):

import ByuJWT from 'byu-jwt'

const byuJwt = ByuJWT({ development: process.env.NODE_ENV === 'development' })

Even if I use require rather than import, the result is the same. You'll also notice I'm not registering any middleware; I'm only creating the byuJwt object.

The desired outcome is that this doesn't stop the server from shutting down gracefully. Currently, I am still investigating workarounds. I will comment again if I find one.

          I believe we can [have GitHub help us](https://docs.github.com/en/enterprise-cloud@latest/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#metadata-restrictions) enforce conventional commits nowadays.

Originally posted by @GaryGSC in #89 (comment)

authenticateUAPIMiddleware Example

(Just adding this as an issue so that students are aware of the easy fix.)

The authenticateUAPIMiddleware example doesn't work as given.

const express = require('express')
const byuJwt = require('byu-jwt')()

const app = express()

app.use(byuJwt.authenticateUAPIMiddleware)

const listener = app.listen(3000, err => {
    if (err) {
        console.error(err.stack)
    } else {
        console.log('Server listening on port ' + listener.address().port)
    }
})

Since express runs middleware functions in strict mode, this is undefined unless you do something like this to use the middleware:

app.use(byuJwt.authenticateUAPIMiddleware.bind(byuJwt))

byu-oit / byu-jwt-nodejs Goto Github PK

byu-jwt-nodejs's Introduction

Packages

Contributing

Committing

Building

Testing

Publishing

Documentation & Linting

byu-jwt-nodejs's People

Contributors

Stargazers

Watchers

byu-jwt-nodejs's Issues

Recommend Projects

Recommend Topics

Recommend Org