auth0/node-jsonwebtoken
github.com/auth0/node-jsonwebtoken ↗ · 84 files · 238 KB
jsonwebtoken | Build | Dependency | |-----------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------
Overview
jsonwebtoken is Auth0's reference Node implementation of RFC 7519 JSON Web Tokens, published to npm as `jsonwebtoken` v9.0.3. It is a tiny, dependency-light library (three public functions — `sign`, `verify`, `decode` — plus three error classes) that wraps `jws` for the actual JWS signing/verification and layers on claim semantics (exp/nbf/aud/iss/sub/jti/nonce/maxAge), option schema validation, and a hard-won set of key-confusion defenses. What is distinctive is how much of the code is defensive rather than functional: roughly half of sign.js and verify.js is dedicated to coercing untrusted key material into `crypto.KeyObject`s, rejecting alg/key-type mismatches (the classic RS256→HS256 confusion attack), and enforcing a 2048-bit RSA modulus floor. It targets any Node service that issues or consumes JWTs, and ships both callback-async and synchronous-throwing modes of every entrypoint.
System map
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`.
Feature catalog
The user-facing surface is three functions, each with a dual sync/async calling convention selected by whether a trailing callback is supplied. `sign` turns a payload plus key into a compact JWS, mapping option names onto registered claim names and computing time-based claims. `verify` is the security-critical path: it re-decodes, resolves a key (possibly via an async key-lookup callback for JWKS/kid workflows), enforces an algorithm allow-list, checks key/alg compatibility, verifies the signature, then runs seven independent claim checks. `decode` is the deliberately unauthenticated escape hatch. Twelve signing algorithms plus `none` are supported, and a set of explicit backwards-compatibility escape valves (`allowInsecureKeySizes`, `allowInvalidAsymmetricKeyTypes`) let callers opt out of the newer hardening.
- `jwt.sign(payload, secretOrPrivateKey, [options, callback])` supports thirteen options validated by `sign_options_schema`: `expiresIn`, `notBefore`, `audience`, `algorithm`, `header`, `encoding`, `issuer`, `subject`, `jwtid`, `noTimestamp`, `keyid`, `mutatePayload`, `allowInsecureKeySizes`, `allowInvalidAsymmetricKeyTypes` — and rejects any key not in that schema with `"<key>" is not allowed in "options"`.
- Four sign options are sugar that write registered claims, via the `options_to_payload` table: `audience`→`aud`, `issuer`→`iss`, `subject`→`sub`, `jwtid`→`jti`. Supplying both the option and the raw claim is an error (`Bad "options.<x>" option. The payload already has an "<claim>" property.`).
- Non-object payloads (strings, numbers, Buffers) are supported for signing but reject the seven object-only options listed in `options_for_objects` with `invalid <opts> option for <typeof> payload`; a Buffer payload round-trips as its string form.
- `mutatePayload: false` (the default) shallow-clones the payload with `Object.assign({}, payload)` before adding `iat`/`exp`/`nbf`, which is what makes signing a frozen or sealed payload work.
- `options.encoding` (default `utf8`) is passed through to `jws`, so `{encoding: 'binary'}` produces a differently-encoded payload segment for non-ASCII characters.
- `jwt.verify(token, secretOrPublicKey, [options, callback])` supports thirteen options: `algorithms`, `audience`, `complete`, `issuer`, `jwtid`, `ignoreExpiration`, `ignoreNotBefore`, `subject`, `clockTolerance`, `maxAge`, `clockTimestamp`, `nonce`, `allowInvalidAsymmetricKeyTypes`.
- `secretOrPublicKey` may be a key-lookup function `(header, cb)` — the JWKS/`kid` integration point — but only when a callback is also supplied; otherwise verify fails with `verify must be called asynchronous if secret or public key is provided as a callback`.
- Audience matching accepts a string, a `RegExp`, or an array of either, and matches if ANY token `aud` entry matches ANY expected audience — an any-to-any `some`/`some` cross product.
- `clockTolerance` (seconds of slack) and `clockTimestamp` (override for "now") apply to `nbf`, `exp`, and `maxAge` uniformly; `clockTimestamp` must be a number or verify fails early with `clockTimestamp must be a number`.
- `maxAge` is an independent expiry ceiling computed from `payload.iat`, requires a numeric `iat` (`iat required when maxAge is specified`), and cannot loosen `exp` — a token past `exp` still fails even with `maxAge: '1000y'`.
- `complete: true` on either `verify` or `decode` returns `{header, payload, signature}` instead of the bare payload — this is how callers reach `kid` and `alg` for key selection.
- `jwt.decode(token, options)` performs no signature verification at all, and silently swallows a `JSON.parse` failure on the payload — returning the raw string payload rather than throwing.
Data flow
There are exactly two input boundaries — the caller-supplied `(payload | jwtString, key, options)` tuple — and one output boundary, either a returned/thrown value or a `(err, result)` callback invocation. No state is owned across calls: the library is entirely stateless, with the only module-level mutable structures being the algorithm allow-list arrays built at require time. The central transform on both paths is key normalization: whatever the caller passes (string, Buffer, PEM, JWK-ish object) is funnelled through `crypto.createPrivateKey`/`createPublicKey` with a `createSecretKey` fallback into a `KeyObject`, and every downstream decision reads `key.type`, `key.asymmetricKeyType`, and `key.asymmetricKeyDetails` off that normalized object. Claim data flows one way on sign (options → payload properties → JWS) and one way on verify (JWS → decoded payload → claim assertions → returned payload).
- On sign, key material normalization is a try/catch cascade: if not already a `KeyObject`, attempt `createPrivateKey(secretOrPrivateKey)`, fall back to `createSecretKey(Buffer.from(...))` for strings, and on double failure emit `secretOrPrivateKey is not valid key material`.
- Verify mirrors that cascade with `createPublicKey` then `createSecretKey`, producing `secretOrPublicKey is not valid key material` — this is what converts a hostile object with a throwing `toString` into a clean error instead of arbitrary execution.
- The JWS header is assembled by `Object.assign` with a fixed precedence: computed `{alg, typ, kid}` first (alg defaults to `HS256`, `typ` is `'JWT'` only for object payloads, `kid` comes from `options.keyid`), then `options.header` spread last so it can override any of them including `alg`.
- A single `timestamp` value — `payload.iat || Math.floor(Date.now()/1000)` — is computed once and is the base for both `nbf` and `exp`, guaranteeing the three time claims are internally consistent within one sign call.
- On verify, the token is parsed twice: once shallowly as `jwtString.split('.')` for arity (`jwt malformed` when length !== 3) and signature-presence checks on `parts[2]`, and once fully through `decode(jwtString, {complete: true})`.
- `options` is defensively shallow-cloned on entry to verify (`Object.assign({}, options)`) specifically because the function later writes `options.algorithms` when the caller omitted it — caller-supplied objects are never mutated.
- When `options.algorithms` is absent, the allow-list is derived from the normalized key: `secret`→HS_ALGS, `rsa`/`rsa-pss`→RSA_KEY_ALGS, `ec`→EC_KEY_ALGS, everything else→PUB_KEY_ALGS. This binds the accepted alg set to the key material, not to the token.
- The token-supplied `header.alg` flows into `jws.verify(jwtString, decodedToken.header.alg, secretOrPublicKey)`, but only after passing the allow-list membership check and the key-type compatibility check — the ordering at lines 144→152→165 is the whole defense.
- The verified `payload` object returned to the caller is the same object produced by `decode`, not a copy — all seven claim checks read from it without transforming it, so callers receive attacker-influenced data verbatim (the README explicitly warns to sanitize it).
- Both functions funnel every error through a single sink — `failure(err)` in sign and `done(err, data)` in verify — which dispatches to `callback(err)` when async or `throw err` when sync, so sync and async modes are guaranteed to produce identical errors.
- `decode` normalizes the payload channel: `jws.decode` may return a string payload, which `decode` opportunistically `JSON.parse`s and keeps only if the result is a non-null object — otherwise the string passes through unchanged.
- `timespan(time, iat)` is the shared conversion from relative to absolute time on both paths: it feeds `payload.nbf`/`payload.exp` on sign and `maxAgeTimestamp` on verify, using `ms()` for strings and plain addition for numbers.
Behavior traces
Three flows matter: module load (feature detection), signing, and verification. Module load is unusual in that it bakes Node-version capability into module-scope constants, so the same code path behaves differently on Node 14 vs Node 16 without any runtime branch. Signing is a long linear gauntlet of eleven guards before any crypto happens. Verification is the inverse-ordered gauntlet, and its ordering is load-bearing: algorithm allow-listing and key-type checks must both precede `jws.verify`. Both entry functions branch at the very end into callback vs synchronous return.
- MODULE LOAD: `require('jsonwebtoken')` → index.js requires decode/verify/sign → sign.js requires `lib/psSupported` → `semver.satisfies(process.version, '^6.12.0 || >=8.0.0')` → if true, `SUPPORTED_ALGS.splice(3, 0, 'PS256','PS384','PS512')` executes at module scope. Algorithm support is therefore frozen at first require.
- SIGN step 1-2: normalize arity (`typeof options === 'function'` → shift to callback), compute `isObjectPayload` as `typeof payload === 'object' && !Buffer.isBuffer(payload)`, then build `header` via `Object.assign`.
- SIGN step 3-4: reject missing key unless `algorithm === 'none'`, then coerce to `KeyObject` via `createPrivateKey` → `createSecretKey` fallback.
- SIGN step 5: enforce symmetry — `header.alg.startsWith('HS')` requires `key.type === 'secret'`; `/^(?:RS|PS|ES)/` requires `key.type === 'private'`; and for non-ES RSA algs, `asymmetricKeyDetails.modulusLength < 2048` is rejected (guarded by an `!== undefined` check for pre-Node-15 where the field is absent).
- SIGN step 6-8: `validatePayload` (allowUnknown=true, checks only iat/exp/nbf are numbers) → clone payload unless `mutatePayload` → reject `exp`+`expiresIn` and `nbf`+`notBefore` double-specification → `validateOptions` (allowUnknown=false).
- SIGN step 9-11: `validateAsymmetricKey(header.alg, key)` unless opted out → compute `timestamp` and apply `noTimestamp`/`iat` → `timespan` for `nbf` and `exp` → copy the four `options_to_payload` claims.
- SIGN terminal branch (async): wrap callback in `once()`, then `jws.createSign({header, privateKey, payload, encoding})` with `.once('error', callback)` and `.once('done', ...)`; the done handler re-checks `signature.length < 256` as a pre-Node-15 proxy for the 2048-bit modulus rule.
- SIGN terminal branch (sync): `jws.sign({header, payload, secret, encoding})` returns the token, followed by the identical `signature.length < 256` check which `throw`s rather than calling back. Both branches carry a `TODO: Remove ... once node 15+ is the minimum supported version`.
- VERIFY step 1-4: arity normalization → clone options → build `done` (callback or throw-on-error closure) → validate `clockTimestamp`/`nonce`/`allowInvalidAsymmetricKeyTypes` shapes → compute `clockTimestamp` → reject falsy or non-string `jwtString` → split into exactly 3 parts.
- VERIFY step 5-6: `decode(jwtString, {complete: true})` inside a try/catch (returns `invalid token` if falsy), then choose `getSecret` — either the caller's key-lookup function or a trivial wrapper that immediately yields the static key. All remaining logic runs inside that callback.
- VERIFY step 7: the three-way signature/key presence matrix — signature-without-key → `secret or public key must be provided`; key-without-signature → `jwt signature is required`; neither-plus-no-algorithms → `please specify "none" in "algorithms"`.
- VERIFY step 8-10 (the security core, in this exact order): coerce key → derive default `algorithms` from key type → reject `header.alg` not in the list (`invalid algorithm`) → reject HS-alg-with-non-secret-key and RS/PS/ES-alg-with-non-public-key → `validateAsymmetricKey` → only then `jws.verify`.
Testing signals
Testing is the strongest part of the repo: ~258 `it()` blocks across 30 mocha files in `test/`, backed by chai assertions, sinon fake timers, and 17 checked-in PEM fixtures covering RSA, RSA-PSS, EC (three curves), DSA, and deliberately-invalid keys. The signature move is `test/test-utils.js`, which runs every sign/verify twice — once sync, once async — under a frozen clock and asserts the two produce byte-identical tokens or deep-equal errors; this is why the sync/async parity invariant actually holds. Coverage is configured with hard nyc thresholds, but the CI workflow runs bare `mocha`, so those thresholds and eslint are never enforced on PRs. Test naming is split between a per-claim convention (`claim-*.test.js`, `option-*.test.js`) and older topic/regression files (`*.tests.js`, `issue_*.tests.js`).
- The framework stack is mocha 5 + chai 4 + sinon 6, with `atob` used to independently decode base64url segments in encoding tests. There is no `.mocharc`, so mocha's default `./test/*.js` glob picks up every file in `test/`.
- `test/test-utils.js` exports `signJWTHelper` and `verifyJWTHelper`, both of which freeze time with `sinon.useFakeTimers({now: Date.now()})`, run the sync call in a try/catch, then run the async call and assert equality of token or error before restoring the clock.
- `expectEqualError` exists because chai does not deep-equal errors (the helper cites chaijs/chai#1009); it compares `message` and `name` explicitly plus every enumerable property, which is how `expiredAt`/`date` payloads on the error subclasses get verified.
- Option/claim validation is tested exhaustively by table-driven loops over ~15 bad values (`true, false, null, -1.1, Infinity, NaN, ' ', '', [], ['foo'], {}, {foo:'bar'}` …), applied per-claim in `claim-exp.test.js`, `header-kid.test.js`, and siblings.
- `test/claim-aud.test.js` is the largest test file at 436 lines and 36 `it()` blocks, reflecting that audience matching (string/regex/array cross-product) is the most branch-heavy claim check.
- `test/jwt.asymmetric_signing.tests.js` is parameterized: it builds an `algorithms` map of RS256/ES256 (plus PS256 when `PS_SUPPORTED`) each with `pub_key`, `priv_key`, and an `invalid_pub_key` that is deliberately not the pair of `priv_key`, then runs the same describe block per algorithm.
- Security regressions are explicitly locked in by `test/jwt.malicious.tests.js`: HMAC-with-RSA-key confusion (both KeyObject and PEM form) and the malicious-`toString` Buffer-impersonation RCE vector.
- Historical bugs are pinned by dedicated regression files: `issue_70.tests.js` (PEM headers), `issue_147.tests.js` (signing an `Object.seal`ed payload), `issue_304.tests.js`, and `rsa-public-key.tests.js`.
- `test/validateAsymmetricKey.tests.js` unit-tests the key-matrix module directly (not through sign/verify), including the no-key and no-algorithm short-circuit paths and the PS/curve branches gated on the feature-detection booleans.
- nyc is configured with `check-coverage: true` and thresholds of 95% lines, 95% statements, 100% functions, 95% branches, excluding `./test/**` — a genuinely strict bar.
- GAP: `test.yml` runs only `npm test` (bare mocha). Neither `npm run coverage` nor `npm run lint` appears in any workflow, so the nyc thresholds and the eslint ruleset are advisory only and can silently regress.
- A known-broken case is parked rather than fixed: `it.skip('should work with none algorithm where secret is falsy')` in async_sign, annotated with a link to node-jws issue #62 — the async `alg: none` path with a falsy secret is untested and known not to work.
Risk map
As a library whose entire job is security, nearly every line in verify.js is a security-sensitive path, and the ordering of its checks is the load-bearing invariant — any reordering that lets `jws.verify` run before the algorithm allow-list check reintroduces the classic JWT confusion attacks. The most concrete correctness defect is in sign.js's `options_to_payload` loop, where `return failure(...)` inside a `forEach` callback does not abort the enclosing function, so in async mode the callback can fire twice. Secondary risks cluster around Node-version-conditional code that CI does not fully exercise, deliberately silent error swallowing in `decode`, a very old eslint pinned at v4, and release workflows that handle several third-party secrets. Blast radius for any change here is unusually wide: this package sits in the dependency tree of a large fraction of Node auth stacks.
- CORRECTNESS BUG: in the `options_to_payload` loop, `return failure(...)` only returns from the `forEach` arrow — the outer sign function continues. In async mode `failure` invokes the raw callback with an error at line 221, and since `callback` is not yet wrapped by `once()` (that happens at line 230), signing proceeds and the callback is invoked a second time with a valid token.
- SECURITY-CRITICAL ORDERING: the allow-list check (`options.algorithms.indexOf(header.alg) === -1`), the key-type symmetry check, and `validateAsymmetricKey` all sit between `decode` and `jws.verify`. Any edit that moves `jws.verify` earlier, or that trusts `header.alg` before line 144, reopens the RS256→HS256 confusion class.
- `options.header` is `Object.assign`ed LAST when building the sign header, so a caller passing `{header: {alg: 'none'}}` silently overrides `options.algorithm` — and the downstream key/alg checks then run against the overridden value. This is by design but is a sharp edge for callers who build headers from user input.
- `decode` swallows all `JSON.parse` errors in an empty `catch (e) { }`, returning the raw string payload instead. Callers that assume an object back from `decode` will see a string on malformed tokens with no signal.
- The `signature.length < 256` heuristic is an acknowledged stopgap for the 2048-bit modulus rule on Node < 15, duplicated in both the sync and async branches with matching `TODO: Remove ...` comments — a two-site invariant that can drift.
- No source file uses `'use strict'`, so sloppy-mode semantics apply — e.g. `delete payload.iat` on a primitive string payload under `noTimestamp` is a silent no-op rather than a TypeError. Notably `npm run coverage` runs mocha with `--use_strict` while `npm test` does not, so the two commands exercise different semantics.
- The EC curve check dereferences `key.asymmetricKeyDetails.namedCurve` without a null guard; it is protected only by the module-load `ASYMMETRIC_KEY_DETAILS_SUPPORTED` semver boolean, and that whole block is excluded from coverage by `istanbul ignore next`.
- The verified payload returned by `verify` is the same object `decode` produced, unsanitized and fully attacker-controlled in content; the README carries an explicit warning to treat it as user input, which implies downstream misuse is a known recurring problem.
- `allowInvalidAsymmetricKeyTypes: true` disables `validateAsymmetricKey` on both sign and verify, and a test asserts it lets an ES256-labelled token be processed with an RSA key — a documented footgun kept only for backwards compatibility.
- `release.yml` handles six secrets (`PRODSEC_TOOLS_ARN`, `PRODSEC_TOOLS_USER`, `PRODSEC_TOOLS_TOKEN`, `RLSECURE_LICENSE`, `RLSECURE_SITE_KEY`, `SIGNAL_HANDLER_TOKEN`) and embeds credentials in a pip `--index-url`. Mitigations are in place — `persist-credentials: false`, `mask-aws-account-id: true`, SHA-pinned actions — but this job is the highest-value supply-chain target in the repo.
- `prepare-release.yml` parses the next version out of semantic-release's human-readable stdout with `awk '/The next release version is/{print $NF}'` — a brittle coupling to log wording that would silently produce an empty version if the message text changes.
- DEAD CODE: `bin/changelog` is a standalone conventional-changelog script with hardcoded `releaseCount: 19` and a commented-out `preset: 'jshint'`, but nothing references it — `package.json` and `prepare-release.yml` both go through the `update-changelog` npm script instead (per commit b924272).
Extension points
This library has no plugin system by design — a JWT implementation with third-party extension hooks would be a security liability. What it does have are a handful of declarative tables that are the intended edit sites for new capability, and one genuine runtime hook. The tables are the two option schemas and the `options_to_payload` map in sign.js, the four algorithm arrays in verify.js, and the `allowedAlgorithmsForKeys`/`allowedCurves` matrices in `lib/validateAsymmetricKey.js` — adding an algorithm means touching all three files coherently. The one caller-facing hook is verify's function-valued `secretOrPublicKey`, which is where JWKS clients plug in. Feature detection for new Node capabilities follows a one-file-per-boolean convention in `lib/`.
- PRIMARY RUNTIME HOOK: `secretOrPublicKey` as a `(header, secretCallback)` function is the documented integration point for JWKS/`kid`-based key resolution; internally the static-key case is normalized into the same shape so there is exactly one code path after line 101.
- Adding a new sign option means one entry in `sign_options_schema` with an `isValid` predicate and a `message` — the generic `validate(schema, allowUnknown, object, parameterName)` walker requires no other change, and unknown options are rejected because `validateOptions` passes `allowUnknown: false`.
- `registered_claims_schema` is the parallel table for payload claims and is validated with `allowUnknown: true`, so arbitrary custom claims pass through while `iat`/`exp`/`nbf` are type-enforced — this asymmetry is the extension point for application-specific claims.
- `options_to_payload` is a two-column map from option name to claim name; adding a new registered-claim shortcut is a one-line addition there, and the conflict-detection and copy logic applies automatically.
- `options_for_objects` is the companion list declaring which options are meaningless for non-object payloads; any new object-only option must be added here too or it will be silently accepted on a string payload.
- Algorithm support is defined in four arrays: `SUPPORTED_ALGS` (sign.js) and `PUB_KEY_ALGS` / `EC_KEY_ALGS` / `RSA_KEY_ALGS` / `HS_ALGS` (verify.js). A new algorithm requires edits in both files plus `allowedAlgorithmsForKeys`.
- `allowedAlgorithmsForKeys` maps `asymmetricKeyType` → permitted `alg` values and is the single authority on key/algorithm pairing; an unrecognized key type throws `Unknown key type "<type>"`, so new key types must be registered here or they are rejected outright.
- `allowedCurves` maps ES algorithms to required named curves and is the place to add a curve; it is consulted only under `ASYMMETRIC_KEY_DETAILS_SUPPORTED`.
- New Node-version feature gates follow a one-module-per-flag convention: a three-line file exporting `semver.satisfies(process.version, '<range>')`, consumed as a module-scope constant. Three such files already exist.
- New error types extend the hierarchy by the ES5 pattern in `lib/NotBeforeError.js`: call `JsonWebTokenError.call(this, message)`, set `this.name`, add the payload field, then `prototype = Object.create(JsonWebTokenError.prototype)` and restore `constructor`. New types must also be re-exported from `index.js` to be reachable.
- New verify-time claim checks slot into the linear block between `jws.verify` and the return, following the established `if (options.X) { if (payload.y !== options.X) return done(new JsonWebTokenError(...)) }` shape used by issuer/subject/jwtid/nonce.
- Test convention for new options/claims: add a `test/option-<name>.test.js` or `test/claim-<name>.test.js` file that uses `testUtils.signJWTHelper`/`verifyJWTHelper` plus `asyncCheck`, so sync/async parity is enforced for free.
Contributor handoff
Treat this as a security library first and a JavaScript project second: the check ordering in verify.js and the guard cascade in sign.js are the product, and reordering them is never a safe refactor even when it looks like cleanup. Style is intentionally conservative CommonJS ES5/ES6 with no build step, no TypeScript, no async/await, and no strict mode — match it rather than modernize it. Read the four root JS files and `lib/validateAsymmetricKey.js` before touching anything; they are under 600 lines combined. Commits must be Conventional Commits because commitlint gates PRs via husky locally and a workflow in CI, and because semantic-release derives the version from them.
- READ FIRST, in order: `index.js`, `sign.js`, `verify.js`, `decode.js`, `lib/validateAsymmetricKey.js`. That is the entire library — under 600 lines total — and everything else in `lib/` is a three-line helper.
- RUN: `npm test` for the fast loop (mocha over `test/`), `npm run coverage` before proposing a merge (nyc enforces 95/95/100/95 and will fail the command), and `npm run lint` manually since no workflow runs it.
- COMMIT FORMAT: Conventional Commits are mandatory. `.husky/commit-msg` runs `npx --no -- commitlint --edit $1` locally and `commitlint.yml` re-validates every commit in a PR range; `@commitlint/config-conventional` is the ruleset.
- STYLE: 2-space indent enforced by both `.editorconfig` and the eslint `indent` rule; no semicolon rule, no quote rule. eslint is pinned at v4 with `ecmaVersion: 6`, so avoid syntax newer than ES2015 in new code paths or the lint run will fail to parse.
- TRAP — check ordering: in verify.js, lines 144 (allow-list), 148-152 (key-type symmetry), and 154-160 (key/alg matrix) must all remain before line 165 (`jws.verify`). Moving or short-circuiting any of them is a vulnerability, not a refactor.
- TRAP — dual calling convention: every change to sign or verify must work identically in sync (throws) and async (callback) mode. `test/test-utils.js` asserts byte-equality of tokens and deep-equality of errors across the two, so a one-sided fix will fail loudly.
- TRAP — `return` inside `forEach`: the existing `options_to_payload` loop already has this bug (a `return failure(...)` that does not abort the function). Do not copy that pattern into new claim-copy logic, and be aware that fixing it changes observable async callback behavior.
- TRAP — Node-conditional code: three `semver.satisfies` booleans are evaluated at module load. Code behind `ASYMMETRIC_KEY_DETAILS_SUPPORTED` and `RSA_PSS_KEY_DETAILS_SUPPORTED` will not execute on your local Node unless it is new enough, and is excluded from coverage — verify such changes against the CI matrix (16/18/20/22/24), not just locally.
- SAFE EDIT BOUNDARY: adding a claim check, a validated option, or a test is low-risk and well-patterned. Changing key coercion (`createPrivateKey`/`createPublicKey`/`createSecretKey` cascades), the algorithm arrays, or `validateAsymmetricKey` is high-risk and touches published security behavior.
- DO NOT EDIT casually: `CHANGELOG.md` is generated by `npm run update-changelog` during the prepare-release workflow, and `package.json` `version` is bumped by `npm version --no-git-tag-version` in that same workflow. Hand-editing either will conflict with the release automation.
- RELEASE SHAPE: pushing to master triggers `prepare-release.yml`, which opens a `release/vX.Y.Z` PR titled `chore(release): X.Y.Z`; merging that PR matches the `startsWith(..., 'chore(release):')` guard and triggers `release.yml` to run `npx semantic-release`. The two workflows are mutually exclusive by that guard.
- New public API or option changes must be reflected in `README.md`, which is the only user documentation and is structured as `jwt.sign` / `jwt.verify` / `jwt.decode` / Errors & Codes / Algorithms supported.
Languages
| Language | Files | Share of source |
|---|---|---|
| JavaScript | 46 | 100% |
| YAML | 6 | docs/config |
| JSON | 5 | docs/config |
| Markdown | 2 | docs/config |
Start reading here
Probable source entrypoint: index.js — inferred from the directory tree and manifest, not the upstream docs.
Source roots
lib/ (8 files)
Source layout — lib/
| Path | Files |
|---|---|
lib/JsonWebTokenError.js | 1 |
lib/NotBeforeError.js | 1 |
lib/TokenExpiredError.js | 1 |
lib/asymmetricKeyDetailsSupported.js | 1 |
lib/psSupported.js | 1 |
lib/rsaPssKeyDetailsSupported.js | 1 |
lib/timespan.js | 1 |
lib/validateAsymmetricKey.js | 1 |
Repository structure
| Top-level path | Files |
|---|---|
test/ | 52 |
lib/ | 8 |
.github/ | 5 |
.husky/ | 1 |
bin/ | 1 |
Docs found: README.md
Package
package.json — jsonwebtoken v9.0.3, 24 declared dependencies.
@commitlint/cli@commitlint/config-conventional@semantic-release/execatobchaiconventional-changelogconventional-changelog-conventionalcommitseslinthuskyjwslodash.includeslodash.isboolean
CI & config entrypoints
README.md— Repository readme.github/workflows/release.yml— GitHub Actions workflow.github/workflows/commitlint.yml— GitHub Actions workflow.github/workflows/test.yml— GitHub Actions workflow.github/workflows/prepare-release.yml— GitHub Actions workflow.github/workflows/sca-scan.yml— GitHub Actions workflowpackage.json— npm scripts: coverage, lint, prepare, test, update-changelog
Structural health signals
Average score 8.8/10 across 45 analyzed source files; 0 hotspots surfaced.
test/claim-aud.test.js— 436 lines, score 6.7 (Deep nesting, Long function/block)test/claim-nbf.test.js— 339 lines, score 6.7 (Deep nesting, Long function/block)test/claim-exp.test.js— 343 lines, score 6.7 (Deep nesting, Long function/block)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
b924272f29192026-06-25 — ci: replace npx changelog call with npm script and fix prepare-release workflow (#1037)02688b9821322026-05-01 — ci: switch to conventionalcommits preset for semantic-release (#1020)cf33b5f59a192026-03-18 — ci: add semantic-release automation (#1015)2db36ae04eae2026-03-18 — chore: add CODEOWNERS file (#1014)ed59e76ea37a2025-12-04 — chore: bump jws to 4.0.1 (#1007)