CodeVetter · Repo Unpack · Extension points
auth0/node-jsonwebtoken
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.
- Release automation is itself extensible through `.releaserc.json`'s plugin array; the `@semantic-release/exec` entry is where additional pre-publish gates (currently `git diff --exit-code` and the ReversingLabs scan) would be added.