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: f592d55

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: f592d55

[mattzcarey]

Rebased on current main and pushed d16ebfa6.

I also found and fixed one cached-discovery edge case while reviewing the draft: when a 401 retry passes an explicit resource_metadata URL, auth() now refreshes discovery from that challenge before comparing authorization server identities. That prevents stale cached discovery state from hiding an AS migration. Added a regression for cached old discovery + fresh PRM challenge causing client/tokens invalidation and re-registration.

Verification:

• pnpm --filter @modelcontextprotocol/client test -- auth.test.ts
• pnpm run typecheck:all
• pnpm run lint:all
• pnpm run build:all
• pre-push hook (build, typecheck, lint)

[mattzcarey]

Addressed both SEP-2352 review threads in c4b94bb6.

Changes:

• AS-change invalidation now requires a validated current authorization-server issuer. If challenged PRM discovery falls back to the resource-server origin after a transient failure, the fallback URL is not treated as proof of an AS migration.
• Token invalidation now runs whenever a real AS change is detected, including CIMD clients. Only client-registration invalidation/re-registration is skipped for portable CIMD HTTPS client IDs.
• Added regressions for transient PRM fallback and CIMD token invalidation without re-registration.

Verified:

• pnpm --filter @modelcontextprotocol/client test -- auth.test.ts
• pnpm run typecheck:all
• pnpm run lint:all
• pnpm run build:all
• pre-push hook: typecheck/build/lint

[claude]

Thanks — the latest revisions address my earlier findings (token-vs-client invalidation gating, PRM-fallback false positives, trailing-slash normalization, code-exchange re-invalidation), and I found no new issues in this pass. Leaving final review to a maintainer since this changes destructive credential-invalidation behavior against a draft spec (SEP-2352) and the trigger condition is the design call you flagged in the description.

Extended reasoning...

Overview

This PR implements SEP-2352 authorization-server binding in the OAuth client (packages/client/src/client/auth.ts): after discovery, the previously recorded AS identity is compared against the freshly resolved one, and on a genuine change the SDK invalidates tokens (always) and the client registration (unless the client_id is a portable CIMD HTTPS URL or an authorization code is being exchanged), forcing re-registration with the new AS. It also adds an authorizationServerSource discriminator to discovery results, refreshes cached discovery on explicit 401 challenges, adds identity normalization, JSDoc guidance, a changeset, and ~770 lines of new tests.

Security risks

The change sits squarely in security-sensitive territory: it deliberately destroys persisted OAuth client registrations and tokens based on discovery results, and it reduces cross-AS credential reuse (a real protection). The risk surface is false-positive invalidation (credential loss / lockout on ASes without open DCR) and false negatives (stale credentials reused against a new AS). Several rounds of review iterated on exactly these edge cases — transient PRM failures, fallback-origin identities, CIMD token handling, cache clobbering, trailing-slash issuer drift, and re-invalidation during code exchange — and the current revision addresses all of them with corresponding regression tests. No injection or data-exposure concerns; the remaining risk is behavioral.

Level of scrutiny

High. This is production-critical client auth logic with destructive side effects, implementing a draft spec section, and the author explicitly flags the invalidation trigger as needing a maintainer direction call before leaving draft. That is a design decision, not something a bot approval should short-circuit. The discovery branching in authInternal has also grown noticeably more complex through the review iterations, which itself deserves a maintainer's judgment on whether the complexity is warranted in the SDK versus provider-land.

Other factors

The bug-hunting pass on the current revision found no new issues, the new test suite covers the previously identified failure modes (AS change, same AS, CIMD, transient PRM fallback, code exchange after migration, trailing-slash identities), and the changeset wording was updated to match the shipped CIMD/token behavior. The author reports clean build/typecheck/lint/test runs. None of that changes the conclusion that a human maintainer should make the final call on the invalidation-trigger semantics and overall approach.