feat(client/auth): validate RFC 9207 iss parameter to mitigate mix-up attacks

Adds an optional `iss` argument to `finishAuth()` and validates it against
the cached authorization server metadata before exchanging the code, per
the RFC 9207 §2.4 decision table keyed on
`authorization_response_iss_parameter_supported`. Reference implementation
for SEP-2468.

Author: pcarleton

src/client/auth.ts

@@ -239,6 +239,58 @@ export class UnauthorizedError extends Error {
     }
 }
 
+/**
+ * Thrown when RFC 9207 `iss` parameter validation fails. The authorization
+ * code MUST NOT be sent to any token endpoint after this is thrown.
+ */
+export class IssuerMismatchError extends UnauthorizedError {
+    constructor(message: string) {
+        super(message);
+        this.name = 'IssuerMismatchError';
+    }
+}
+
+/**
+ * Validates the `iss` parameter from an authorization response against the
+ * authorization server's metadata, per RFC 9207 §2.4. The four cases are
+ * keyed on whether the AS advertises `authorization_response_iss_parameter_supported`:
+ *
+ * | advertised | iss present | outcome |
+ * |---|---|---|
+ * | true | yes, matches | accept |
+ * | true | yes, mismatch | reject |
+ * | true | no | reject (server promised it) |
+ * | false/undefined | yes | reject (unexpected, possible injection) |
+ * | false/undefined | no | accept (server doesn't support 9207) |
+ *
+ * Comparison is simple string comparison per RFC 3986 §6.2.1 — no
+ * normalization of case, ports, or trailing slashes.
+ */
+export function validateAuthorizationResponseIssuer(
+    receivedIss: string | undefined,
+    metadata: AuthorizationServerMetadata | undefined
+): void {
+    const supported = metadata?.authorization_response_iss_parameter_supported === true;
+    const expectedIssuer = metadata?.issuer;
+
+    if (supported) {
+        if (receivedIss === undefined) {
+            throw new IssuerMismatchError(
+                'Authorization server advertises authorization_response_iss_parameter_supported but no iss parameter was received'
+            );
+        }
+        if (receivedIss !== expectedIssuer) {
+            throw new IssuerMismatchError(
+                `Authorization response iss "${receivedIss}" does not match expected issuer "${expectedIssuer}"`
+            );
+        }
+    } else if (receivedIss !== undefined) {
+        throw new IssuerMismatchError(
+            'Authorization server does not advertise authorization_response_iss_parameter_supported but an iss parameter was received'
+        );
+    }
+}
+
 type ClientAuthMethod = 'client_secret_basic' | 'client_secret_post' | 'none';
 
 function isClientAuthMethod(method: string): method is ClientAuthMethod {
@@ -403,6 +455,13 @@ export async function auth(
     options: {
         serverUrl: string | URL;
         authorizationCode?: string;
+        /**
+         * The `iss` parameter from the authorization response redirect URI
+         * (RFC 9207). When provided alongside `authorizationCode`, it is
+         * validated against the authorization server metadata before the
+         * code is exchanged.
+         */
+        authorizationResponseIssuer?: string;
         scope?: string;
         resourceMetadataUrl?: URL;
         fetchFn?: FetchLike;
@@ -430,12 +489,14 @@ async function authInternal(
     {
         serverUrl,
         authorizationCode,
+        authorizationResponseIssuer,
         scope,
         resourceMetadataUrl,
         fetchFn
     }: {
         serverUrl: string | URL;
         authorizationCode?: string;
+        authorizationResponseIssuer?: string;
         scope?: string;
         resourceMetadataUrl?: URL;
         fetchFn?: FetchLike;
@@ -559,6 +620,9 @@ async function authInternal(
 
     // Exchange authorization code for tokens, or fetch tokens directly for non-interactive flows
     if (authorizationCode !== undefined || nonInteractiveFlow) {
+        if (authorizationCode !== undefined) {
+            validateAuthorizationResponseIssuer(authorizationResponseIssuer, metadata);
+        }
         const tokens = await fetchToken(provider, authorizationServerUrl, {
             metadata,
             resource,

src/client/sse.ts

@@ -216,15 +216,19 @@ 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 `code` parameter from the redirect URI.
+     * @param iss - The `iss` parameter from the redirect URI, if present (RFC 9207). When the authorization server advertises support, omitting this will cause auth to fail.
      */
-    async finishAuth(authorizationCode: string): Promise<void> {
+    async finishAuth(authorizationCode: string, iss?: string): Promise<void> {
         if (!this._authProvider) {
             throw new UnauthorizedError('No auth provider');
         }
 
         const result = await auth(this._authProvider, {
             serverUrl: this._url,
             authorizationCode,
+            authorizationResponseIssuer: iss,
             resourceMetadataUrl: this._resourceMetadataUrl,
             scope: this._scope,
             fetchFn: this._fetchWithInit

src/client/streamableHttp.ts

@@ -421,15 +421,19 @@ 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 `code` parameter from the redirect URI.
+     * @param iss - The `iss` parameter from the redirect URI, if present (RFC 9207). When the authorization server advertises support, omitting this will cause auth to fail.
      */
-    async finishAuth(authorizationCode: string): Promise<void> {
+    async finishAuth(authorizationCode: string, iss?: string): Promise<void> {
         if (!this._authProvider) {
             throw new UnauthorizedError('No auth provider');
         }
 
         const result = await auth(this._authProvider, {
             serverUrl: this._url,
             authorizationCode,
+            authorizationResponseIssuer: iss,
             resourceMetadataUrl: this._resourceMetadataUrl,
             scope: this._scope,
             fetchFn: this._fetchWithInit

src/shared/auth.ts

@@ -66,7 +66,8 @@ export const OAuthMetadataSchema = z.looseObject({
     introspection_endpoint_auth_methods_supported: z.array(z.string()).optional(),
     introspection_endpoint_auth_signing_alg_values_supported: z.array(z.string()).optional(),
     code_challenge_methods_supported: z.array(z.string()).optional(),
-    client_id_metadata_document_supported: z.boolean().optional()
+    client_id_metadata_document_supported: z.boolean().optional(),
+    authorization_response_iss_parameter_supported: z.boolean().optional()
 });
 
 /**
@@ -109,7 +110,8 @@ export const OpenIdProviderMetadataSchema = z.looseObject({
     require_request_uri_registration: z.boolean().optional(),
     op_policy_uri: SafeUrlSchema.optional(),
     op_tos_uri: SafeUrlSchema.optional(),
-    client_id_metadata_document_supported: z.boolean().optional()
+    client_id_metadata_document_supported: z.boolean().optional(),
+    authorization_response_iss_parameter_supported: z.boolean().optional()
 });
 
 /**

test/client/auth.test.ts

@@ -13,7 +13,9 @@ import {
     auth,
     type OAuthClientProvider,
     selectClientAuthMethod,
-    isHttpsUrl
+    isHttpsUrl,
+    validateAuthorizationResponseIssuer,
+    IssuerMismatchError
 } from '../../src/client/auth.js';
 import { createPrivateKeyJwtAuth } from '../../src/client/auth-extensions.js';
 import { InvalidClientMetadataError, ServerError } from '../../src/server/auth/errors.js';
@@ -3682,4 +3684,62 @@ describe('OAuth Authorization', () => {
             });
         });
     });
+
+    describe('validateAuthorizationResponseIssuer (RFC 9207)', () => {
+        const issuer = 'https://auth.example.com';
+        const baseMetadata: AuthorizationServerMetadata = {
+            issuer,
+            authorization_endpoint: `${issuer}/authorize`,
+            token_endpoint: `${issuer}/token`,
+            response_types_supported: ['code']
+        };
+
+        it('accepts matching iss when server advertises support', () => {
+            expect(() =>
+                validateAuthorizationResponseIssuer(issuer, {
+                    ...baseMetadata,
+                    authorization_response_iss_parameter_supported: true
+                })
+            ).not.toThrow();
+        });
+
+        it('rejects mismatched iss when server advertises support', () => {
+            expect(() =>
+                validateAuthorizationResponseIssuer('https://attacker.example.com', {
+                    ...baseMetadata,
+                    authorization_response_iss_parameter_supported: true
+                })
+            ).toThrow(IssuerMismatchError);
+        });
+
+        it('rejects absent iss when server advertises support', () => {
+            expect(() =>
+                validateAuthorizationResponseIssuer(undefined, {
+                    ...baseMetadata,
+                    authorization_response_iss_parameter_supported: true
+                })
+            ).toThrow(IssuerMismatchError);
+        });
+
+        it('rejects unexpected iss when server does not advertise support', () => {
+            expect(() => validateAuthorizationResponseIssuer(issuer, baseMetadata)).toThrow(IssuerMismatchError);
+        });
+
+        it('accepts absent iss when server does not advertise support', () => {
+            expect(() => validateAuthorizationResponseIssuer(undefined, baseMetadata)).not.toThrow();
+        });
+
+        it('accepts absent iss when metadata is undefined', () => {
+            expect(() => validateAuthorizationResponseIssuer(undefined, undefined)).not.toThrow();
+        });
+
+        it('uses simple string comparison without normalization', () => {
+            expect(() =>
+                validateAuthorizationResponseIssuer(`${issuer}/`, {
+                    ...baseMetadata,
+                    authorization_response_iss_parameter_supported: true
+                })
+            ).toThrow(IssuerMismatchError);
+        });
+    });
 });