Align custom-claim docs with actual JWT behavior

The client auth helpers advertise overlapping custom claims as taking precedence over reserved JWT claims, but the implementation re-applies the reserved claims through SignJWT setters. This change narrows the scope to documentation and a focused regression test so the published contract matches shipped behavior without expanding API surface or changing runtime semantics.

Constraint: Upstream review guidance prefers small, spec-aware fixes backed by concrete evidence
Rejected: Change runtime behavior so custom claims override reserved claims | would alter shipped semantics and widen scope beyond a docs fix
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep reserved JWT claims authoritative unless maintainers explicitly decide to change runtime behavior in a separate design discussion
Tested: packages/client/authExtensions test suite; client package typecheck; client package lint/prettier
Not-tested: full monorepo test matrix

Author: shaun0927

packages/client/src/client/authExtensions.ts

@@ -236,8 +236,9 @@ export interface PrivateKeyJwtProviderOptions {
 
     /**
      * Optional custom claims to include in the JWT assertion.
-     * These are merged with the standard claims (`iss`, `sub`, `aud`, `exp`, `iat`, `jti`),
-     * with custom claims taking precedence for any overlapping keys.
+     * These are merged with the standard claims (`iss`, `sub`, `aud`, `exp`, `iat`, `jti`).
+     * Additional custom claims are included, but overlapping standard claims are
+     * still set explicitly by the SDK and therefore are not overridden.
      *
      * Useful for including additional claims that help scope the access token
      * with finer granularity than what scopes alone allow.

packages/client/test/client/authExtensions.test.ts

@@ -448,6 +448,35 @@ describe('createPrivateKeyJwtAuth', () => {
         expect(decoded.sub).toBe('client-id');
     });
 
+    it('does not allow custom claims to override standard JWT claims', async () => {
+        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'
+            }
+        });
+
+        const params = new URLSearchParams();
+        await addClientAuth(new Headers(), params, 'https://auth.example.com/token', undefined);
+
+        const assertion = params.get('client_assertion');
+        expect(assertion).toBeTruthy();
+
+        const jose = await import('jose');
+        const decoded = jose.decodeJwt(assertion!);
+        expect(decoded.iss).toBe('client-id');
+        expect(decoded.sub).toBe('client-id');
+        expect(decoded.aud).toBe('https://aud.example.com');
+        expect(decoded.tenant_id).toBe('org-123');
+    });
+
     it('passes custom claims through PrivateKeyJwtProvider', async () => {
         const provider = new PrivateKeyJwtProvider({
             clientId: 'client-id',