security: coordinated JWT issuer/audience hardening across AuthGuard, betterauth.ts, and mcp.handler.ts

[coderabbitai]

Context

Currently, jwtVerify(token, JWKS) in both protocol/src/guards/auth.guard.ts (Line 30) and protocol/src/controllers/mcp.handler.ts (Lines 88–100) validates signature and expiration only — it does not validate the iss (issuer) or aud (audience) claims.

Better Auth's JWT plugin (protocol/src/lib/betterauth/betterauth.ts) currently embeds issuer: BASE_URL when issuing tokens but does not embed an aud claim. This means:

• Any cryptographically valid JWT from the same JWKS with a string id or sub claim can authenticate to any endpoint, regardless of intended scope.
• Adding audience validation unilaterally would immediately reject all existing tokens (since no aud is embedded today).

Required coordinated change

This fix must be done atomically across three files to avoid breaking existing tokens:

1. protocol/src/lib/betterauth/betterauth.ts — Add an audience claim (e.g., BASE_URL or a service-specific string) to the JWT plugin's definePayload or JWT config.
2. protocol/src/guards/auth.guard.ts — Update jwtVerify(token, JWKS) to jwtVerify(token, JWKS, { issuer: BASE_URL, audience: '<agreed_value>' }).
3. protocol/src/controllers/mcp.handler.ts — Same update to the jwtVerify call in authResolver.resolveUserId.

References

• PR introducing mcp.handler.ts: feat: MCP server and plugin skill rewrite #622 (comment: feat: MCP server and plugin skill rewrite #622 (comment))
• Requested by: @yanekyuk

[fusuyfusuy]

Verified implemented and shipped — closing. Evidence from git history and the current tree:

Fix landed 2026-05-14 as one coordinated batch (plan IND-257):

• 8486002f4 docs(plans): JWT issuer/audience hardening implementation plan (IND-257)
• b02d497a0 docs(specs): JWT issuer/audience hardening design spec (IND-257)
• 25db7cd08 test(auth): jwtVerify issuer/audience claim validation contract tests
• 17476f4c3 feat(auth): export JWT_AUDIENCE, set audience claim on jwt() plugin issuance
• a73b44a0a feat(auth): validate issuer and audience in AuthGuard jwtVerify
• cc92811c2 feat(auth): validate issuer and audience in MCP controller jwtVerify
• 2830f10b3 feat(limiter): identifier resolution also validates issuer/audience (bonus surface)

Current tree (repo restructured protocol/ → services/api/ in #1041):

• services/api/src/lib/betterauth/betterauth.ts:13 — export const JWT_AUDIENCE = API_URL, emitted at line 166
• services/api/src/guards/auth.guard.ts:56 — jwtVerify(token, JWKS, { issuer: API_URL, audience: JWT_AUDIENCE })
• services/api/src/controllers/mcp.controller.ts:465 — same in authResolver.resolveIdentity
• services/api/src/lib/limiter/identifier.ts:104 — same in the rate-limiter identifier

Tests: services/api/tests/auth.jwt-claims.spec.ts — 5 contract tests (accepts correct iss/aud; rejects missing aud, wrong aud, wrong iss, missing both). All pass locally: 5 pass / 0 fail. The atomicity requirement (audience must be embedded at issuance before verification enforces it) is satisfied — no token breakage window.

[fusuyfusuy]

Verified implemented and shipped — closing. Evidence from git history and the current tree:

Fix landed 2026-05-14 as one coordinated batch (plan IND-257):

• 8486002f4 docs(plans): JWT issuer/audience hardening implementation plan (IND-257)
• b02d497a0 docs(specs): JWT issuer/audience hardening design spec (IND-257)
• 25db7cd08 test(auth): jwtVerify issuer/audience claim validation contract tests
• 17476f4c3 feat(auth): export JWT_AUDIENCE, set audience claim on jwt() plugin issuance
• a73b44a0a feat(auth): validate issuer and audience in AuthGuard jwtVerify
• cc92811c2 feat(auth): validate issuer and audience in MCP controller jwtVerify
• 2830f10b3 feat(limiter): identifier resolution also validates issuer/audience (bonus surface)

Current tree (repo restructured protocol/ → services/api/ in #1041):

• services/api/src/lib/betterauth/betterauth.ts:13 — export const JWT_AUDIENCE = API_URL, emitted at line 166
• services/api/src/guards/auth.guard.ts:56 — jwtVerify(token, JWKS, { issuer: API_URL, audience: JWT_AUDIENCE })
• services/api/src/controllers/mcp.controller.ts:465 — same in authResolver.resolveIdentity
• services/api/src/lib/limiter/identifier.ts:104 — same in the rate-limiter identifier

Tests: services/api/tests/auth.jwt-claims.spec.ts — 5 contract tests (accepts correct iss/aud; rejects missing aud, wrong aud, wrong iss, missing both). All pass locally: 5 pass / 0 fail. The atomicity requirement (audience must be embedded at issuance before verification enforces it) is satisfied — no token breakage window.