CodeVetter · Repo Unpack · System map
auth0/node-jsonwebtoken
This is a pure library with no server, no database, and no network I/O of its own — the only runtime boundary is the Node `crypto` module and the `jws` package. `index.js` is the whole public API surface: it re-exports `decode.js`, `verify.js`, `sign.js`, and the three error classes from `lib/`. Support modules in `lib/` are all single-purpose: feature-detection booleans gated on `process.version` via `semver`, a `ms`-backed timespan parser, and the asymmetric key/algorithm compatibility matrix. Build is nonexistent (plain CommonJS, no transpile); test is `mocha`, coverage is `nyc mocha --use_strict`, lint is `eslint .`. Deployment is npm publish driven by `semantic-release` in a two-workflow release dance on `master`.
- `index.js` is the sole entrypoint and exports exactly six symbols: `decode`, `verify`, `sign`, `JsonWebTokenError`, `NotBeforeError`, `TokenExpiredError` — there is no class, no factory, no configuration object.
- All cryptography is delegated to the `jws` package (`^4.0.1`): `jws.decode` in decode.js, `jws.sign`/`jws.createSign` in sign.js, and `jws.verify` in verify.js. This repo contains no hashing, HMAC, or signature code of its own.
- The runtime dependency set is deliberately minimal and old-school: `jws`, `ms`, `semver`, and seven separately-published single-function lodash packages (`lodash.includes`, `lodash.isboolean`, `lodash.isinteger`, `lodash.isnumber`, `lodash.isplainobject`, `lodash.isstring`, `lodash.once`).
- Node version capability is resolved at require-time, not call-time, by three boolean modules that `semver.satisfies(process.version, ...)`: `lib/psSupported.js` (`^6.12.0 || >=8.0.0`), `lib/asymmetricKeyDetailsSupported.js` (`>=15.7.0`), and `lib/rsaPssKeyDetailsSupported.js` (`>=16.9.0`).
- PS256/PS384/PS512 are spliced into the algorithm allow-lists at module load only when `PS_SUPPORTED` — into `SUPPORTED_ALGS` at index 3 in sign.js, and appended to both `PUB_KEY_ALGS` and `RSA_KEY_ALGS` in verify.js.
- The error hierarchy is hand-rolled ES5 prototype inheritance, not `class extends Error`: `JsonWebTokenError` calls `Error.call(this, message)` and manually sets `this.message`, and `NotBeforeError`/`TokenExpiredError` do `Object.create(JsonWebTokenError.prototype)` and add a `date`/`expiredAt` field.
- `lib/validateAsymmetricKey.js` owns the key-type↔algorithm compatibility matrix (`allowedAlgorithmsForKeys` for `ec`/`rsa`/`rsa-pss`) and the ES-curve mapping (`allowedCurves`: ES256→prime256v1, ES384→secp384r1, ES512→secp521r1). It is the single shared gate called by both sign and verify.
- `lib/timespan.js` is the only time-arithmetic module; it converts a `ms`-parseable string or a raw number into an absolute epoch-seconds timestamp, and returns `undefined` (not an error) for unparseable input, pushing error construction onto its three callers.
- Developer commands are `npm test` (bare `mocha`), `npm run coverage` (`nyc mocha --use_strict`), `npm run lint` (`eslint .`), and `npm run update-changelog` (`conventional-changelog -p conventionalcommits -i CHANGELOG.md`). `npm run prepare` installs husky hooks.
- CI is five GitHub Actions workflows: `test.yml` (PR-triggered matrix over Node 16/18/20/22/24), `commitlint.yml` (PR-triggered conventional-commit validation), `prepare-release.yml` and `release.yml` (both on push to master, mutually exclusive via a `chore(release):` head-commit-message guard), and `sca-scan.yml` (Snyk, via a pinned reusable workflow from `auth0/devsecops-tooling`).
- Publishing is `semantic-release` configured in `.releaserc.json` on the `master` branch, with conventional-commits analysis, npm publish from repo root, a `prepareCmd` of `git diff --exit-code`, and a `verifyReleaseCmd` that runs a ReversingLabs `rl-wrapper` scan over the `npm pack` tarball before release.
- The published npm tarball is narrowed by the `files` allow-list to `lib`, `decode.js`, `sign.js`, `verify.js` — tests, `bin/`, and workflows never ship. `.npmignore` additionally excludes `opslevel.yml`.
- Repo ownership/routing is declared for Auth0 internal tooling: `CODEOWNERS` assigns everything to `@auth0/project-iam-protocols-engineer-codeowner` and `opslevel.yml` tags the repo to the `iam_protocols` owner.
- `package.json` declares `engines.node >= 12`, but the test matrix only exercises Node 16 through 24 — the 12/14 support claim is unverified by CI.