feat(jwe): decrypt JWE-encrypted access tokens

[jd3vi1]

Summary

Adds decryption of JWE-encrypted access tokens. When an API is configured to encrypt access tokens, the token returned at the callback is a JWE. With accessTokenDecryptionKey set, the SDK decrypts it before writing it to the session, so req.oidc.accessToken and afterCallback always receive a plaintext JWT with no change to consuming code.

Stacked on #863 (JAR). Review after that merges; the base will retarget to master.

What's included

• accessTokenDecryptionKey — private key for decryption. Accepts PEM string, Buffer, KeyObject, JWK, or CryptoKey. Requires a code flow (implicit flow returns no access token from the token endpoint).
• accessTokenDecryptionAlg — optional pin for the key-management algorithm.
• Decryption runs at both the callback and on token refresh, so tokens stay plaintext across refreshes for apps using offline_access.
• Decryption happens before afterCallback fires, so hooks receive a usable token.
• The key-management algorithm is read from the JWE protected header (so RSA-OAEP-256, RSA-OAEP-512, etc. all work without pre-declaring), but only after jose validates it against an allowlist of strong algorithms. This avoids a hardcoded default that breaks other algorithms while preventing algorithm-confusion/downgrade (notably RSA1_5). accessTokenDecryptionAlg, when set, narrows the allowlist to that one value.
• Decryption failures surface a clear, actionable error instead of a raw crypto stack trace.

Usage

app.use(
  auth({
    authorizationParams: {
      response_type: 'code',
      audience: 'https://your-api/',
      scope: 'openid profile email offline_access',
    },
    accessTokenDecryptionKey: fs.readFileSync('./api-decryption-key.pem'),
    // accessTokenDecryptionAlg: 'RSA-OAEP-512', // optional pin
  }),
);

Tests

• Unit tests for decryptAccessToken (header auto-detect for RSA-OAEP-256/512, pin match/mismatch, non-JWE input), config validation (code-flow requirement), and end-to-end callback + refresh decryption with a clear-error case.
• Type tests in index.test-d.ts.
• Documentation in EXAMPLES.md and an example at examples/jwe.js.

[jd3vi1]

Addressed both majors in 95908d1:

1. Non-JWE tokens no longer 500. decryptAccessToken now returns the token unchanged when it is not a compact JWE (five dot-separated parts), so a plaintext JWT, an opaque token, or Token Encryption being toggled off / mid-rollout passes through instead of failing every login and refresh. Genuine JWEs still go through the allowlist-gated decrypt path.
2. Weak-alg rejection test added. New test encrypts with an off-allowlist A128KW and asserts it is rejected before the key resolver runs. Also added pass-through tests for non-JWE and opaque tokens, and reworked the clear-error test to use a genuine JWE with a non-matching key (since non-JWEs no longer error).

Minor: accessTokenDecryptionAlg is now constrained to the allowlist at the config layer (Joi.string().valid(...)) for defense in depth.

Full suite and tsd green.

[jd3vi1]

Closing this PR after a scoping review.

JWE access token decryption is a Resource Server concern in the HRI SDK requirements (it lives under "Resource Server Authorization", alongside mTLS token binding), not an Authentication Client / RP concern. express-openid-connect is an RP web-app login SDK: it holds the access token to forward to APIs, it does not inspect or validate it. Consistent with this, the peer RP SDK nextjs-auth0 does not implement access-token JWE decryption either.

The right home for this is the resource-server SDK (@auth0/auth0-api-js), and it will be tracked separately. JAR (#863) and mTLS (#865) remain in scope for express-openid-connect and continue as two independent PRs.