feat(client,core): RFC 9207 iss parameter validation on authorization responses (SEP-2468)

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

@@ -0,0 +1,15 @@
+---
+'@modelcontextprotocol/client': minor
+---
+
+Add RFC 9207 `iss` parameter validation for authorization responses (SEP-2468). 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 RFC 9207 response validation, so existing `finishAuth(code)` callers that never see the authorization response are unaffected.
+
+Discovery also now validates authorization-server metadata issuer values per RFC 8414 Section 3.3. Metadata discovered for a PRM-provided authorization server URL is rejected when its `issuer` does not match that URL, and the public `discoverAuthorizationServerMetadata()` helper
+throws on mismatches or invalid issuer identifiers unless called with `{ validateIssuer: false }` for intentional alias discovery. Cached discovery state is also validated; stale legacy no-PRM fallback state that saved the MCP server origin before learning a distinct metadata
+issuer is ignored and refreshed. For legacy servers without protected resource metadata, metadata is still discovered at the MCP server origin; when that metadata names a distinct issuer, the SDK now treats the metadata `issuer` as the authorization server URL for persisted
+discovery state and fallback endpoint construction.
+
+Cross-App Access IdP discovery (`discoverAndRequestJwtAuthGrant()` / `CrossAppAccessProvider`) intentionally skips the RFC 8414 issuer-echo check, so configured IdP alias URLs whose metadata names a canonical issuer keep working.

docs/clients/machine-auth.md

@@ -86,6 +86,7 @@ const transport = new StreamableHTTPClientTransport(new URL('https://api.example
 ```
 
 The SDK discovers the MCP server's authorization server and resource URL (RFC 9728) before it calls `assertion`, then hands them in on `ctx` together with the negotiated `scope` and the transport's `fetchFn`. Pass them through so the IdP issues a grant bound to the right audience and resource.
+For the enterprise IdP leg, `discoverAndRequestJwtAuthGrant()` intentionally accepts configured IdP alias URLs whose metadata names a canonical issuer; it skips the RFC 8414 issuer-echo check before using the discovered token endpoint.
 
 ## Drop to the token-exchange utilities
 

docs/clients/oauth.md

@@ -1,6 +1,7 @@
 ---
 shape: how-to
 ---
+
 # Authenticate a user with OAuth
 
 Protecting a server you run → [Require authorization](../serving/authorization.md). Signing a user in from a client → this page. No user present → [Authenticate without a user](./machine-auth.md).
@@ -117,7 +118,7 @@ await client.connect(new StreamableHTTPClientTransport(url, { authProvider: prov
 `finishAuth(params)` extracts `code`, validates the RFC 9207 `iss` parameter, exchanges the code at the authorization server discovery resolved before the redirect, and saves the tokens through your provider. The second `connect()` finds those tokens and completes without another redirect.
 
 ::: tip
-`finishAuth` also takes a positional form, `finishAuth(code, iss)`. Pass the `URLSearchParams` instead: the SDK reads both values from it, and a positional call that drops `iss` is rejected when the authorization server advertises RFC 9207 support.
+`finishAuth` also takes a positional form, `finishAuth(code, iss)`. Pass the `URLSearchParams` when you have the callback URL: the SDK reads both `code` and `iss` from it, and a missing `iss` is treated as an inspected absence. A positional `finishAuth(code)` call omits callback parameters entirely and skips RFC 9207 authorization-response validation for backwards compatibility.
 :::
 
 ## Handle issuer mismatch

docs/migration/upgrade-to-v2.md

@@ -64,8 +64,8 @@ The codemod ([`@modelcontextprotocol/codemod`](https://github.com/modelcontextpr
 mechanically applies every rename whose mapping is fixed. The mappings are the
 **source of truth** — they live in the codemod package and are not reproduced here:
 
-| Mapping                                                                                   | Source file                                                                                                       |
-| ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| Mapping                                                                                   | Source file                                                                                                                                                                  |
+| ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `@modelcontextprotocol/sdk/...` import paths → v2 packages                                | [`mappings/importMap.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/codemod/src/migrations/v1-to-v2/mappings/importMap.ts)                   |
 | Symbol renames (`McpError` → `ProtocolError`, `JSONRPCError` → `JSONRPCErrorResponse`, …) | [`mappings/symbolMap.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/codemod/src/migrations/v1-to-v2/mappings/symbolMap.ts)                   |
 | `setRequestHandler(Schema, …)` → `setRequestHandler('method/string', …)`                  | [`mappings/schemaToMethodMap.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/codemod/src/migrations/v1-to-v2/mappings/schemaToMethodMap.ts)   |
@@ -1150,8 +1150,9 @@ with or without a pin) the connect-time 401 currently surfaces wrapped as
 #### `auth()` options are now `AuthOptions`
 
 The inline options object on `auth()` is now the named `AuthOptions` type. New fields:
-`iss?: string` (the form-urldecoded `iss` from the authorization callback — pass it
-alongside `authorizationCode` for RFC 9207 validation), `skipIssuerMetadataValidation?:
+`iss?: string | null` (the form-urldecoded `iss` from the authorization callback — pass it
+alongside `authorizationCode` for RFC 9207 validation, or pass `null` when the callback was
+inspected and had no `iss`), `skipIssuerMetadataValidation?:
 boolean` (security-weakening opt-out of the RFC 8414 §3.3 issuer-echo check), and
 `forceReauthorization?: boolean` (skip the refresh-token branch — set by the transport's
 step-up path; hosts driving step-up themselves set it under the same condition).
@@ -1160,9 +1161,11 @@ step-up path; hosts driving step-up themselves set it under the same condition).
 
 `transport.finishAuth()` and `auth()` now validate `iss` from the authorization callback
 against the issuer recorded from validated AS metadata. A mismatched `iss` throws
-`IssuerMismatchError` before the code is exchanged regardless of advertised support; a
-**missing** `iss` throws only when the AS advertised
-`authorization_response_iss_parameter_supported: true`.
+`IssuerMismatchError` before the code is exchanged regardless of advertised support. An
+inspected missing `iss` (`URLSearchParams` without `iss`, or `iss: null`) throws only when
+the AS advertised `authorization_response_iss_parameter_supported: true`; omitting `iss`
+entirely preserves legacy `finishAuth(code)` / `auth({ authorizationCode })` behavior and
+skips RFC 9207 authorization-response validation.
 
 Pass the callback URL's `URLSearchParams` so the SDK can read `iss` alongside `code`.
 The SDK does **not** validate `state`; compare it yourself before calling `finishAuth`: