fix(client): invalidate credentials and re-register when the authorization server changes (SEP-2352)

[mattzcarey]

Implements SEP-2352 (authorization server binding & migration) for the OAuth client. Draft because the invalidation trigger is behavioral and needs maintainer sign-off — see "Behavioral risk" below.

Spec

Draft spec, basic/authorization/client-registration.mdx, "Authorization Server Binding":

Clients that use pre-registered credentials, or persist client credentials obtained via Dynamic Client Registration, MUST associate those credentials with the specific authorization server that issued them, keyed by the authorization server's issuer identifier. When the authorization server changes (detected via updated protected resource metadata), clients MUST NOT reuse client credentials from a different authorization server and MUST re-register with the new authorization server.

Client IDs based on Client ID Metadata Documents are portable across authorization servers […] No re-registration is needed when the authorization server changes.

What changed

• authInternal (discovery block, packages/client/src/client/auth.ts): after discovery resolves the authorization server, the previously recorded AS identity (cached discoveryState.authorizationServerUrl / cached metadata issuer / provider.authorizationServerUrl?.()) is compared against the freshly resolved identity. On a mismatch, the SDK calls provider.invalidateCredentials?.('client') and ('tokens'); the existing flow then sees no client information and re-registers with the new AS.
• CIMD carve-out: when the stored client_id is an HTTPS URL (CIMD), no invalidation occurs — those client IDs are explicitly portable across ASes.
• Pre-registered providers: a provider that drops its credentials on invalidateCredentials('client') but does not implement saveClientInformation will get a thrown error ("OAuth client information must be saveable for dynamic registration") rather than silent reuse, matching the spec's SHOULD-surface-an-error guidance.
• JSDoc on OAuthClientProvider.clientInformation/saveClientInformation: implementations SHOULD persist client credentials keyed by the AS issuer.
• Storage keying itself is provider-land; the SDK's enforceable piece is detect-change → invalidate → re-register.

Canonical comparison key (flagging for maintainers)

The spec says credentials are keyed by the AS issuer identifier. The comparison uses the validated AS metadata issuer where available, falling back to the AS URL when metadata is absent — under RFC 8414 the two coincide. To avoid false-positive invalidation when they textually diverge (trailing slash, issuer-vs-discovery-URL drift), a match on either the issuer or the AS URL is treated as "same AS". Happy to tighten this to issuer-only if preferred.

Behavioral risk (flagging for a direction call)

Silently dropping credentials on AS change could surprise providers whose discoveryState is flaky — e.g. a provider that intermittently returns a stale or empty discovery state while authorizationServerUrl() still reports the old AS would trigger invalidation and a re-registration round-trip. Flagging the trigger condition for a direction call before this leaves draft.

Land order

• fix(client): accumulate scopes (union) on step-up authorization challenges (SEP-2350) #2265 (SEP-2350 scope union) is open and touches other regions of auth.ts/auth.test.ts. This branch is independent (off main, not stacked); expect trivial test-file rebases depending on merge order.
• A follow-up SEP-2468 (iss validation) PR will touch authInternal's code-exchange path and will rebase over this one.
• Intended land order: fix(client): accumulate scopes (union) on step-up authorization challenges (SEP-2350) #2265 → this → SEP-2468.

Validation

• pnpm build:all, pnpm typecheck:all, pnpm lint:all — clean
• pnpm --filter @modelcontextprotocol/client test — 370/370 pass (3 new tests in a standalone describe appended at the end of auth.test.ts: AS change → invalidate + re-register; same AS → no invalidation; CIMD client_id + AS change → no invalidation, credentials reused)
• Changeset: patch for @modelcontextprotocol/client

Downstream impact

cloudflare/agents' DurableObjectOAuthClientProvider already implements invalidateCredentials('client') so this works; its storage keys client info per server-name+client_id rather than per-issuer — fully honoring SEP-2352's keying guidance would be an optional agents-side follow-up, not a break.

Closes #2201

[changeset-bot]

🦋 Changeset detected

Latest commit: e848b15

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@modelcontextprotocol/client	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

@modelcontextprotocol/client

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/client@2271

@modelcontextprotocol/codemod

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/codemod@2271

@modelcontextprotocol/server

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/server@2271

@modelcontextprotocol/server-legacy

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/server-legacy@2271

@modelcontextprotocol/express

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/express@2271

@modelcontextprotocol/fastify

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/fastify@2271

@modelcontextprotocol/hono

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/hono@2271

@modelcontextprotocol/node

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/node@2271

commit: e848b15