feat(client): SEP-2352 per-authorization-server credential isolation (issuer-stamped)

auth() now stamps an `issuer` field onto every value it passes to
saveTokens()/saveClientInformation() and threads {issuer} as the ctx
argument to tokens()/clientInformation(). On read, a stored value whose
stamp names a different authorization server is treated as undefined via
discardIfIssuerMismatch(), so a client_id or refresh_token issued by one
AS is never sent to another — the flow re-registers/re-authorizes
exactly as if nothing were stored.

This replaces the previous detection-and-throw approach with structural
keying: providers that round-trip stored values verbatim are protected
with no code change; multi-AS providers key storage on ctx.issuer.

- New discardIfIssuerMismatch() helper (exported).
- AuthorizationServerMismatchError moved to authErrors.ts; thrown only
  on the callback-leg gate (discoveryState issuer \!= resolved issuer).
- console.warn on the callback leg when the provider lacks
  saveDiscoveryState().
- saveAuthorizationServerUrl()/authorizationServerUrl() deprecated:
  still written for back-compat (Cross-App Access), never read.
- ClientCredentialsProvider/PrivateKeyJwtProvider/
  StaticPrivateKeyJwtProvider/CrossAppAccessProvider gain expectedIssuer
  and no longer define saveClientInformation().
- examples/oauth: single-slot blob storage + discoveryState.
- Conformance: provider implements discoveryState/invalidateCredentials;
  handle401 clears discovery on 401 so AS migration is re-probed;
  runAuthClient uses versionNegotiation:auto so the
  auth/authorization-server-migration scenario (and the 2026-leg
  scope-step-up/scope-retry-limit) speak the modern lifecycle.
- ~6 focused unit tests + 5 e2e as-migration:* rows asserting structural
  behaviour (no token POST to wrong AS because the stamp read returned
  undefined).

Claude-Session: https://claude.ai/code/session_01XBib5gRe8AMPPJhySCz3EJ

Author: felixweinberger

.changeset/auth-sep-2352-credential-isolation.md

@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/client': minor
+---
+
+Per-authorization-server credential isolation (SEP-2352). `auth()` now stamps an `issuer` field onto every value it passes to `saveTokens()` / `saveClientInformation()` and threads `{ issuer }` to `tokens()` / `clientInformation()`; on read, a stored credential whose stamp names a different authorization server is treated as `undefined`, so a `client_id` / `refresh_token` issued by one AS is never sent to another. Providers that round-trip stored values verbatim are protected with no code change; multi-AS providers may key storage on `ctx.issuer`. New `discardIfIssuerMismatch()` helper and `AuthorizationServerMismatchError` (callback-leg gate). `OAuthClientProvider.saveAuthorizationServerUrl()` / `authorizationServerUrl()` are deprecated (still written, never read). `ClientCredentialsProvider`, `PrivateKeyJwtProvider`, `StaticPrivateKeyJwtProvider`, and `CrossAppAccessProvider` gain `expectedIssuer` and no longer define `saveClientInformation()`.

docs/migration-SKILL.md

@@ -223,6 +223,7 @@ The OAuth client flow additionally throws dedicated classes from `@modelcontextp
 | `exchangeAuthorization()` / `refreshAuthorization()` / `fetchToken()` / `requestJwtAuthorizationGrant()` / `exchangeJwtAuthGrant()` non-https token endpoint | `InsecureTokenEndpointError` (`tokenEndpoint`)                      |
 | RFC 9207 `iss` mismatch / RFC 8414 §3.3 issuer-echo mismatch                                                   | `IssuerMismatchError` (`kind`, `expected`, `received`)              |
 | Transport 403 `insufficient_scope` with `onInsufficientScope: 'throw'`, or default mode without an `OAuthClientProvider` | `InsufficientScopeError` (`requiredScope`, `resourceMetadataUrl`, `errorDescription`) |
+| `auth()` callback leg: discovery resolves a different AS than the recorded redirect target                     | `AuthorizationServerMismatchError` (`recordedIssuer`, `currentIssuer`) |
 
 Update OAuth error handling:
 
@@ -598,6 +599,8 @@ OAuth callback handling: pass the callback URL's `URLSearchParams` to `transport
 
 Token-exchange / refresh now refuse to send credentials to a non-`https:` token endpoint (loopback `localhost` / `127.0.0.1` / `::1` exempt), throwing `InsecureTokenEndpointError` with no opt-out. `auth()` surfaces this on every path including refresh — switch any plain-`http:` AS on a non-loopback host to TLS.
 
+`auth()` stamps an `issuer` field onto every value it passes to `saveTokens()` / `saveClientInformation()` and threads `{ issuer }` as the `ctx` argument to those methods plus `tokens()` / `clientInformation()` (SEP-2352). On read, a stored value whose `issuer` names a different AS is treated as `undefined` and the flow re-registers / re-authorizes. Round-trip the stored object verbatim and you're protected; multi-AS providers key storage on `ctx.issuer`. `OAuthClientProvider.saveAuthorizationServerUrl()` / `authorizationServerUrl()` are `@deprecated` (still written for back-compat, never read by the SDK). `ClientCredentialsProvider` / `PrivateKeyJwtProvider` / `StaticPrivateKeyJwtProvider` / `CrossAppAccessProvider` gain `expectedIssuer?: string` and no longer define `saveClientInformation()`.
+
 No code changes required; wire-behavior note: on a 2026-07-28 Streamable HTTP connection, aborting an in-flight client request (caller `signal` / timeout) closes that request's SSE response stream as the spec cancellation signal — `notifications/cancelled` is no longer POSTed
 there. 2025-era connections and stdio at any era still send `notifications/cancelled`. Custom `Transport` implementations that open one underlying request per outbound message and honor `TransportSendOptions.requestSignal` may declare `readonly hasPerRequestStream = true` to opt
 into the same routing.

docs/migration.md

@@ -1633,10 +1633,28 @@ Step-up retries are now hard-capped per send (`maxStepUpRetries`, default 1) reg
 
 The GET listen-stream open path now applies the same step-up handling as the POST send path.
 
+### Credentials are bound to the issuing authorization server (SEP-2352)
+
+`auth()` now stamps an `issuer` field onto every value it passes to `saveTokens()` and `saveClientInformation()`, and passes `{ issuer }` as the second (`ctx`) argument to `tokens()` / `saveTokens()` / `clientInformation()` / `saveClientInformation()`. On read, a stored value whose `issuer` stamp names a different authorization server is treated as `undefined` — the flow re-registers / re-authorizes exactly as if nothing were stored. A `client_id` or `refresh_token` issued by one authorization server is therefore never sent to another.
+
+**Round-trip the stored object unchanged and you're protected** — single-slot storage works. To hold credentials for several authorization servers at once, key your storage on `ctx.issuer` instead (and treat **`ctx === undefined` as "return the most-recently-saved token set"** — the transport's per-request `Authorization: Bearer` read (`adaptOAuthProvider().token()`) calls `tokens()` with no `ctx`).
+
+Implement `discoveryState()` / `saveDiscoveryState()` so the callback leg can verify it is exchanging the authorization code at the same AS the redirect targeted; without it the SDK `console.warn`s once per callback. **`discoveryState` must persist with the same durability as `codeVerifier`** — it has to survive the redirect round-trip (page navigation, app restart). A provider that implements `saveDiscoveryState()` but cannot return it on the callback leg fails closed with `AuthorizationServerMismatchError`. Hosts that drive 401 handling themselves (custom middleware / `withOAuthRetry`) should call `provider.invalidateCredentials?.('discovery')` on a fresh 401 so a changed `authorization_servers` list is picked up on re-discovery. The built-in `StreamableHTTPClientTransport` / `SSEClientTransport` 401 path does not currently invalidate discovery state.
+
+`OAuthClientProvider.saveAuthorizationServerUrl()` / `authorizationServerUrl()` are **deprecated** — `auth()` still calls `saveAuthorizationServerUrl()` for back-compat with providers that read it internally (Cross-App Access), but the SDK never reads `authorizationServerUrl()`. The call timing changed in v2: it was post-discovery, it is now post-`saveTokens` (after a successful token exchange). Read the `issuer` stamp on stored tokens, or `ctx.issuer`, instead.
+
+The bundled `ClientCredentialsProvider`, `PrivateKeyJwtProvider`, `StaticPrivateKeyJwtProvider`, and `CrossAppAccessProvider` gain an `expectedIssuer` option that stamps the constructor-supplied credential; when set, `auth()` against any other authorization server fails before the credential leaves the process. These providers no longer define `saveClientInformation()`.
+
 ### Conformance obligations for `OAuthClientProvider` implementers
 
 <!-- Filled in as the SEP-2352/2350/837/2207 behavior PRs land. -->
 
+#### SEP-2352 — per-authorization-server credential isolation
+
+**No code change required for the common case.** If your `saveTokens()` / `saveClientInformation()` persist the value passed to them verbatim and your `tokens()` / `clientInformation()` return it verbatim, the SDK-stamped `issuer` round-trips and the binding holds.
+
+If you serialise to a custom format, persist the `issuer` field alongside the rest of the value. If you key storage by `ctx.issuer`, return `undefined` for an issuer you have no entry for, and treat **`ctx === undefined` as "return the most-recently-saved token set"** — the transport's per-request `Authorization: Bearer` read (`adaptOAuthProvider().token()`) calls `tokens()` with no `ctx`.
+
 ## Using an LLM to migrate your code
 
 An LLM-optimized version of this guide is available at [`docs/migration-SKILL.md`](migration-SKILL.md). It contains dense mapping tables designed for tools like Claude Code to mechanically apply all the changes described above. You can paste it into your LLM context or load it as

examples/oauth/simpleOAuthClientProvider.ts

@@ -1,14 +1,28 @@
-import type { OAuthClientInformationMixed, OAuthClientMetadata, OAuthClientProvider, OAuthTokens } from '@modelcontextprotocol/client';
+import type {
+    OAuthClientInformationMixed,
+    OAuthClientMetadata,
+    OAuthClientProvider,
+    OAuthDiscoveryState,
+    OAuthTokens
+} from '@modelcontextprotocol/client';
 import { validateClientMetadataUrl } from '@modelcontextprotocol/client';
 
 /**
- * In-memory OAuth client provider for demonstration purposes
- * In production, you should persist tokens securely
+ * In-memory OAuth client provider for demonstration purposes.
+ * In production, you should persist tokens and client credentials securely.
+ *
+ * Tokens and client credentials are stored as single-slot blobs. The SDK stamps an
+ * `issuer` field onto every value it saves; round-tripping the blob unchanged means
+ * a credential issued by one authorization server is never reused at another (the
+ * SDK reads the stamp back as a key-not-found and re-registers / re-authorizes).
+ * To hold credentials for several authorization servers at once, key your storage
+ * on the `ctx.issuer` argument instead.
  */
 export class InMemoryOAuthClientProvider implements OAuthClientProvider {
     private _clientInformation?: OAuthClientInformationMixed;
     private _tokens?: OAuthTokens;
     private _codeVerifier?: string;
+    private _discoveryState?: OAuthDiscoveryState;
 
     constructor(
         private readonly _redirectUrl: string | URL,
@@ -66,4 +80,19 @@ export class InMemoryOAuthClientProvider implements OAuthClientProvider {
         }
         return this._codeVerifier;
     }
+
+    saveDiscoveryState(state: OAuthDiscoveryState): void {
+        this._discoveryState = state;
+    }
+
+    discoveryState(): OAuthDiscoveryState | undefined {
+        return this._discoveryState;
+    }
+
+    invalidateCredentials(scope: 'all' | 'client' | 'tokens' | 'verifier' | 'discovery'): void {
+        if (scope === 'all' || scope === 'client') this._clientInformation = undefined;
+        if (scope === 'all' || scope === 'tokens') this._tokens = undefined;
+        if (scope === 'all' || scope === 'verifier') this._codeVerifier = undefined;
+        if (scope === 'all' || scope === 'discovery') this._discoveryState = undefined;
+    }
 }