fix(client): gate RFC 9207 fail-closed iss rejection behind explicit caller signal

The advertised-but-missing rejection (AS metadata sets
authorization_response_iss_parameter_supported: true but no iss was
supplied) previously fired whenever iss was omitted from auth()/
finishAuth(). The SDK never sees the authorization response itself, so
it cannot distinguish 'the response had no iss' from 'the caller did
not plumb response parameters through' — and every existing
finishAuth(code) caller falls in the second bucket. This broke the
client-conformance auth/pre-registration scenario (the fixture AS
advertises RFC 9207 support; the harness never passes iss).

iss is now tri-state on validateAuthorizationResponseIssuer(), auth(),
and both transports' finishAuth():
- string: exact-match validation against the recorded issuer (unchanged)
- null: caller asserts it inspected the response and it had no iss ->
  RFC 9207 fail-closed rejection applies when support is advertised
- undefined: caller had no access to response parameters -> validation
  is skipped entirely

Conformance: client suite back to baseline-green (auth/pre-registration
15/15). Client tests: 386 passed.

Author: mattzcarey

.changeset/sep-2468-iss-validation.md

@@ -3,4 +3,8 @@
 '@modelcontextprotocol/client': minor
 ---
 
-Add RFC 9207 `iss` parameter validation for authorization responses (SEP-2468). `OAuthMetadataSchema` and `OpenIdProviderMetadataSchema` now recognize `authorization_response_iss_parameter_supported`. The client exports a new `validateAuthorizationResponseIssuer()` helper, `auth()` accepts an optional `iss`, and `StreamableHTTPClientTransport.finishAuth()` / `SSEClientTransport.finishAuth()` accept an optional `{ iss }` second argument. When provided, the `iss` from the authorization response is validated against the issuer recorded in the authorization server metadata before the authorization code is sent to any token endpoint; on mismatch the response is rejected without processing any other response parameters. All additions are backwards-compatible.
+Add RFC 9207 `iss` parameter validation for authorization responses (SEP-2468). `OAuthMetadataSchema` and `OpenIdProviderMetadataSchema` now recognize `authorization_response_iss_parameter_supported`. The client exports a new `validateAuthorizationResponseIssuer()` helper,
+`auth()` accepts an optional `iss`, and `StreamableHTTPClientTransport.finishAuth()` / `SSEClientTransport.finishAuth()` accept an optional `{ iss }` second argument. The `iss` option is tri-state: a string is validated by exact comparison against the issuer recorded in the
+authorization server metadata before the authorization code is sent to any token endpoint (mismatch rejects the response without processing any other response parameters); `null` asserts the caller inspected the authorization response and it carried no `iss`, enabling the RFC
+9207 fail-closed rejection when the AS advertises `authorization_response_iss_parameter_supported: true`; `undefined` (omitted) skips validation, so existing `finishAuth(code)` callers that never see the authorization response are unaffected. All additions are
+backwards-compatible.

packages/client/src/client/auth.ts

@@ -536,9 +536,20 @@ export async function parseErrorResponse(input: Response | string): Promise<OAut
  * recorded from the authorization server's validated metadata, per RFC 9207
  * (OAuth 2.0 Authorization Server Issuer Identification) Section 2.4.
  *
- * Decision table:
+ * The `iss` argument is tri-state, because the SDK does not see the authorization
+ * response itself — the caller does:
+ * - `string`: the `iss` parameter received in the authorization response. Validated.
+ * - `null`: the caller inspected the authorization response and it contained no `iss`.
+ *   The RFC 9207 fail-closed rule applies: if the AS metadata advertises
+ *   `authorization_response_iss_parameter_supported: true`, the response is rejected.
+ * - `undefined`: the caller did not supply authorization-response parameters at all
+ *   (e.g. legacy `finishAuth(code)` callers that only plumb the code). Validation is
+ *   skipped — the SDK cannot distinguish "the response had no iss" from "the caller
+ *   did not look", so it does not fail closed on the caller's behalf.
+ *
+ * Decision table (for callers that did inspect the response, i.e. `iss` is a string or `null`):
  * 1. The AS metadata advertises `authorization_response_iss_parameter_supported: true`
- *    but the response carries no `iss` → reject.
+ *    but the response carries no `iss` (`null`) → reject.
  * 2. The response carries an `iss` (whether or not support was advertised) → it must be
  *    an exact, character-by-character match of the recorded issuer (no normalization) —
  *    mismatch → reject.
@@ -547,14 +558,21 @@ export async function parseErrorResponse(input: Response | string): Promise<OAut
  *    (including any `error`/`error_description` parameters).
  *
  * @param metadata - The authorization server metadata recorded before the redirect, if available
- * @param iss - The `iss` parameter received in the authorization response, if any
+ * @param iss - The `iss` parameter from the authorization response (`null` = response had no
+ * `iss`; `undefined` = caller did not provide response parameters, skip validation)
  * @throws Error if the response must be rejected per RFC 9207
  */
 export function validateAuthorizationResponseIssuer(
     metadata: { issuer: string; authorization_response_iss_parameter_supported?: boolean } | undefined,
-    iss: string | undefined
+    iss: string | null | undefined
 ): void {
     if (iss === undefined) {
+        // The caller did not provide authorization-response parameters; there is
+        // nothing to validate and no signal that an advertised iss was dropped.
+        return;
+    }
+
+    if (iss === null) {
         if (metadata?.authorization_response_iss_parameter_supported === true) {
             throw new Error(
                 'Authorization server metadata advertises authorization_response_iss_parameter_supported, but the authorization response did not include an iss parameter (RFC 9207)'
@@ -593,8 +611,16 @@ export async function auth(
          * The `iss` parameter received alongside the authorization code in the
          * authorization response, validated per RFC 9207 against the issuer recorded
          * in the authorization server metadata before the code is exchanged.
+         *
+         * Pass the string value when the authorization response contained an `iss`
+         * parameter. Pass `null` to assert that you inspected the authorization
+         * response and it contained no `iss` — this enables the RFC 9207 fail-closed
+         * rejection when the AS advertises
+         * `authorization_response_iss_parameter_supported: true`. Leave `undefined`
+         * when the response parameters were not available to you; validation is then
+         * skipped entirely.
          */
-        iss?: string;
+        iss?: string | null;
         scope?: string;
         resourceMetadataUrl?: URL;
         fetchFn?: FetchLike;
@@ -663,7 +689,7 @@ async function authInternal(
     }: {
         serverUrl: string | URL;
         authorizationCode?: string;
-        iss?: string;
+        iss?: string | null;
         scope?: string;
         resourceMetadataUrl?: URL;
         fetchFn?: FetchLike;
@@ -804,7 +830,8 @@ async function authInternal(
     if (authorizationCode !== undefined || nonInteractiveFlow) {
         if (authorizationCode !== undefined) {
             // RFC 9207: validate the authorization response issuer against the recorded
-            // AS metadata BEFORE the code is sent to any token endpoint.
+            // AS metadata BEFORE the code is sent to any token endpoint. Skipped when the
+            // caller did not provide authorization-response parameters (iss === undefined).
             validateAuthorizationResponseIssuer(metadata, iss);
         }
 

packages/client/src/client/sse.ts

@@ -230,11 +230,15 @@ export class SSEClientTransport implements Transport {
      * Call this method after the user has finished authorizing via their user agent and is redirected back to the MCP client application. This will exchange the authorization code for an access token, enabling the next connection attempt to successfully auth.
      *
      * @param authorizationCode - The authorization code from the authorization response
-     * @param options.iss - The `iss` parameter from the authorization response, if present.
-     * Validated against the issuer recorded in the authorization server metadata per RFC 9207
+     * @param options.iss - The `iss` parameter from the authorization response. Pass the string
+     * value when present; pass `null` to assert the authorization response was inspected and
+     * contained no `iss` (this enables the RFC 9207 fail-closed rejection when the AS advertises
+     * `authorization_response_iss_parameter_supported: true`). Leave `undefined` when the response
+     * parameters were not available — validation is then skipped. When provided, the value is
+     * validated against the issuer recorded in the authorization server metadata per RFC 9207
      * before the code is exchanged.
      */
-    async finishAuth(authorizationCode: string, options?: { iss?: string }): Promise<void> {
+    async finishAuth(authorizationCode: string, options?: { iss?: string | null }): Promise<void> {
         if (!this._oauthProvider) {
             throw new UnauthorizedError('finishAuth requires an OAuthClientProvider');
         }

packages/client/src/client/streamableHttp.ts

@@ -491,11 +491,15 @@ export class StreamableHTTPClientTransport implements Transport {
      * Call this method after the user has finished authorizing via their user agent and is redirected back to the MCP client application. This will exchange the authorization code for an access token, enabling the next connection attempt to successfully auth.
      *
      * @param authorizationCode - The authorization code from the authorization response
-     * @param options.iss - The `iss` parameter from the authorization response, if present.
-     * Validated against the issuer recorded in the authorization server metadata per RFC 9207
+     * @param options.iss - The `iss` parameter from the authorization response. Pass the string
+     * value when present; pass `null` to assert the authorization response was inspected and
+     * contained no `iss` (this enables the RFC 9207 fail-closed rejection when the AS advertises
+     * `authorization_response_iss_parameter_supported: true`). Leave `undefined` when the response
+     * parameters were not available — validation is then skipped. When provided, the value is
+     * validated against the issuer recorded in the authorization server metadata per RFC 9207
      * before the code is exchanged.
      */
-    async finishAuth(authorizationCode: string, options?: { iss?: string }): Promise<void> {
+    async finishAuth(authorizationCode: string, options?: { iss?: string | null }): Promise<void> {
         if (!this._oauthProvider) {
             throw new UnauthorizedError('finishAuth requires an OAuthClientProvider');
         }

packages/client/test/client/auth.test.ts

@@ -4137,13 +4137,24 @@ describe('SEP-2468: RFC 9207 authorization response iss validation', () => {
     const issuer = 'https://auth.example.com';
 
     describe('validateAuthorizationResponseIssuer', () => {
-        // RFC 9207 Section 2.4, row 1: advertised but absent -> reject
-        it('rejects when the AS advertises iss support but the response lacks iss', () => {
+        // RFC 9207 Section 2.4, row 1: advertised but absent -> reject. The caller signals
+        // "I inspected the authorization response and it had no iss" by passing null.
+        it('rejects when the AS advertises iss support but the inspected response lacks iss (null)', () => {
             expect(() =>
-                validateAuthorizationResponseIssuer({ issuer, authorization_response_iss_parameter_supported: true }, undefined)
+                validateAuthorizationResponseIssuer({ issuer, authorization_response_iss_parameter_supported: true }, null)
             ).toThrow(/did not include an iss parameter/);
         });
 
+        // undefined means the caller never had access to the authorization response
+        // parameters, so the SDK cannot fail closed on the caller's behalf.
+        it('skips validation entirely when the caller provides no response parameters (undefined)', () => {
+            expect(() =>
+                validateAuthorizationResponseIssuer({ issuer, authorization_response_iss_parameter_supported: true }, undefined)
+            ).not.toThrow();
+            expect(() => validateAuthorizationResponseIssuer({ issuer }, undefined)).not.toThrow();
+            expect(() => validateAuthorizationResponseIssuer(undefined, undefined)).not.toThrow();
+        });
+
         // RFC 9207 Section 2.4, row 2: present (advertised) -> exact match required
         it('accepts an exactly matching iss when support is advertised', () => {
             expect(() =>
@@ -4177,15 +4188,15 @@ describe('SEP-2468: RFC 9207 authorization response iss validation', () => {
         });
 
         // RFC 9207 Section 2.4, row 3: neither advertised nor present -> proceed
-        it('proceeds when iss support is not advertised and no iss is present', () => {
-            expect(() => validateAuthorizationResponseIssuer({ issuer }, undefined)).not.toThrow();
+        it('proceeds when iss support is not advertised and the inspected response has no iss', () => {
+            expect(() => validateAuthorizationResponseIssuer({ issuer }, null)).not.toThrow();
             expect(() =>
-                validateAuthorizationResponseIssuer({ issuer, authorization_response_iss_parameter_supported: false }, undefined)
+                validateAuthorizationResponseIssuer({ issuer, authorization_response_iss_parameter_supported: false }, null)
             ).not.toThrow();
         });
 
-        it('proceeds when no metadata is recorded and no iss is present', () => {
-            expect(() => validateAuthorizationResponseIssuer(undefined, undefined)).not.toThrow();
+        it('proceeds when no metadata is recorded and the inspected response has no iss', () => {
+            expect(() => validateAuthorizationResponseIssuer(undefined, null)).not.toThrow();
         });
 
         it('rejects when an iss is present but no metadata was recorded to validate against', () => {
@@ -4289,19 +4300,34 @@ describe('SEP-2468: RFC 9207 authorization response iss validation', () => {
             expect(provider.saveTokens).not.toHaveBeenCalled();
         });
 
-        it('rejects when the AS advertises iss support but no iss is provided', async () => {
+        it('rejects when the AS advertises iss support and the caller reports a response without iss (null)', async () => {
             const provider = createMockProvider();
 
             await expect(
                 auth(provider, {
                     serverUrl: 'https://resource.example.com',
-                    authorizationCode: 'code123'
+                    authorizationCode: 'code123',
+                    iss: null
                 })
             ).rejects.toThrow(/did not include an iss parameter/);
 
             expect(tokenEndpointCalls()).toHaveLength(0);
         });
 
+        it('proceeds when iss is omitted entirely, even when the AS advertises support', async () => {
+            // Callers that never had access to the authorization response (legacy
+            // finishAuth(code) plumbing) must not be failed closed on their behalf.
+            const provider = createMockProvider();
+
+            const result = await auth(provider, {
+                serverUrl: 'https://resource.example.com',
+                authorizationCode: 'code123'
+            });
+
+            expect(result).toBe('AUTHORIZED');
+            expect(tokenEndpointCalls()).toHaveLength(1);
+        });
+
         it('proceeds without an iss when the AS does not advertise support', async () => {
             const provider = createMockProvider({
                 ...authServerMetadata,

packages/client/test/client/streamableHttp.test.ts

@@ -1690,18 +1690,36 @@ describe('StreamableHTTPClientTransport', () => {
             expect(mockAuthProvider.saveTokens).not.toHaveBeenCalled();
         });
 
-        it('rejects when the AS advertises iss support but finishAuth receives no iss', async () => {
+        it('rejects when the AS advertises iss support and the caller reports a response without iss (iss: null)', async () => {
             const customFetch = createOAuthFetchMock();
             transport = new StreamableHTTPClientTransport(new URL('http://localhost:1234/mcp'), {
                 authProvider: mockAuthProvider,
                 fetch: customFetch
             });
 
-            await expect(transport.finishAuth('test-auth-code')).rejects.toThrow(/did not include an iss parameter/);
+            await expect(transport.finishAuth('test-auth-code', { iss: null })).rejects.toThrow(/did not include an iss parameter/);
 
             const tokenCalls = customFetch.mock.calls.filter(([url]) => url.toString().includes('/token'));
             expect(tokenCalls).toHaveLength(0);
         });
+
+        it('completes the exchange when finishAuth receives no iss at all, even though the AS advertises support', async () => {
+            // Legacy finishAuth(code) callers cannot see the authorization response;
+            // the SDK must not fail closed on their behalf.
+            const customFetch = createOAuthFetchMock();
+            transport = new StreamableHTTPClientTransport(new URL('http://localhost:1234/mcp'), {
+                authProvider: mockAuthProvider,
+                fetch: customFetch
+            });
+
+            await transport.finishAuth('test-auth-code');
+
+            const tokenCalls = customFetch.mock.calls.filter(
+                ([url, options]) => url.toString().includes('/token') && options?.method === 'POST'
+            );
+            expect(tokenCalls).toHaveLength(1);
+            expect(mockAuthProvider.saveTokens).toHaveBeenCalled();
+        });
     });
 
     describe('SSE retry field handling', () => {