authExtensions docs say custom claims override reserved JWT claims, but implementation keeps reserved claims authoritative

[shaun0927]

Summary

PrivateKeyJwtProviderOptions.claims currently documents overlapping custom claims as taking precedence over the SDK's standard JWT claims, but the implementation keeps the reserved claims authoritative.

This looks like a docs / contract mismatch rather than a runtime bug or security issue.

Current docs

packages/client/src/client/authExtensions.ts says:

These are merged with the standard claims (iss, sub, aud, exp, iat, jti), with custom claims taking precedence for any overlapping keys.

Actual behavior

createPrivateKeyJwtAuth() constructs claims from { ...baseClaims, ...options.claims }, but then immediately calls:

• .setIssuer(options.issuer)
• .setSubject(options.subject)
• .setAudience(audience)
• .setIssuedAt(now)
• .setExpirationTime(now + lifetimeSeconds)
• .setJti(jti)

Those setters overwrite overlapping values from options.claims, so the SDK's reserved claims remain authoritative.

Minimal reproduction

const addClientAuth = createPrivateKeyJwtAuth({
  issuer: 'client-id',
  subject: 'client-id',
  privateKey: 'a-string-secret-at-least-256-bits-long',
  alg: 'HS256',
  audience: 'https://aud.example.com',
  claims: {
    iss: 'override-issuer',
    sub: 'override-subject',
    aud: 'https://override.example.com',
    tenant_id: 'org-123'
  }
});

Decoding the resulting JWT shows:

• iss === 'client-id'
• sub === 'client-id'
• aud === 'https://aud.example.com'
• tenant_id === 'org-123'

So additional custom claims are included, but overlapping reserved claims are not overridden.

Why this matters

This can mislead users into thinking they can customize reserved JWT claims through claims, when in practice only non-overlapping claims are honored.

Suggested resolution

I think the smallest fix is to align the docs/tests with the current runtime behavior:

• clarify that additional custom claims are included
• clarify that reserved standard claims are still set explicitly by the SDK and are not overridden
• add a regression test showing the current behavior

If maintainers prefer the opposite behavior, that would likely deserve a separate design discussion because it changes runtime semantics.

[mcp-claude]

the JSDoc for PrivateKeyJwtProviderOptions.claims (packages/client/src/client/authExtensions.ts:239-240) says custom claims take precedence for overlapping keys, but the jose setter calls on lines 84-89 overwrite them back to SDK values. non-overlapping claims (e.g. tenant_id) work fine; only iss, sub, aud, exp, iat, jti are affected.

present on main; v1.x has the same implementation behavior but doesn't expose a claims field on PrivateKeyJwtProviderOptions, so the misleading JSDoc is main-only.

two fix paths:

1. remove the redundant setIssuer/setSubject/setAudience/setIssuedAt/setExpirationTime/setJti calls (lines 84-89) and rely solely on the merged claims object — makes implementation match docs (custom claims win)
2. update JSDoc to document that reserved claims are not overrideable — smaller change, matches current runtime behavior

repro script + output

// repro.ts (run: npx tsx repro.ts)
import { createPrivateKeyJwtAuth } from './packages/client/src/client/authExtensions.js';

const addClientAuth = createPrivateKeyJwtAuth({
  issuer: 'client-id',
  subject: 'client-id',
  privateKey: 'a-string-secret-at-least-256-bits-long-here!',
  alg: 'HS256',
  audience: 'https://aud.example.com',
  claims: {
    iss: 'override-issuer',
    sub: 'override-subject',
    aud: 'https://override.example.com',
    tenant_id: 'org-123',
  },
});

const params = new URLSearchParams();
await addClientAuth(new Headers(), params, new URL('https://token.example.com/token'), undefined);

const [, payloadB64] = params.get('client_assertion')!.split('.');
const payload = JSON.parse(Buffer.from(payloadB64, 'base64url').toString('utf8'));
console.log(JSON.stringify(payload, null, 2));

output:

{
  "iss": "client-id",
  "sub": "client-id",
  "aud": "https://aud.example.com",
  "exp": 1776354620,
  "iat": 1776354320,
  "jti": "...",
  "tenant_id": "org-123"
}

iss/sub/aud stay as SDK values despite claims overrides; tenant_id (non-overlapping) is correctly included.

suggested fix

// packages/client/src/client/authExtensions.ts
         // Sign JWT
         const assertion = await new jose.SignJWT(claims)
             .setProtectedHeader({ alg, typ: 'JWT' })
-            .setIssuer(options.issuer)
-            .setSubject(options.subject)
-            .setAudience(audience)
-            .setIssuedAt(now)
-            .setExpirationTime(now + lifetimeSeconds)
-            .setJti(jti)
             .sign(key as unknown as Uint8Array | CryptoKey);

the six reserved claims (iss, sub, aud, iat, exp, jti) are already present in the merged claims object built at line 60 — the setter calls are redundant and silently undo any user overrides. removing them makes the runtime behavior match the documented contract.

test to verify: assert that decoded.iss/sub/aud equal the override values passed in options.claims, not the issuer/subject/audience constructor options.