fix(auth): make clear* hydration-safe, migrate raw-key blobs, doc keepalive/memo caveats

Address round-1 @claude review of #1592:

- OAuthStorageBase.clear* no longer mutate the pre-hydration (empty) store —
  a clear issued before hydration is deferred until it lands, so it merges
  onto the real persisted state instead of (a) being resurrected by the late
  rehydrate merge or (b) persisting a near-empty blob that clobbers every
  other server's on-disk credential. Already-hydrated clears stay synchronous.
- store.setServerState migrates a pre-normalization raw-key blob onto the
  canonical key on first partial write (was: shadowed it with a fresh
  canonical entry, orphaning the raw blob's other fields). clearServerState
  now also drops the raw-key orphan.
- Document the keepalive 64KB combined-body ceiling on the remote-storage
  write, the getRemoteOAuthStorage memo key intentionally omitting fetchFn,
  and the real ordering invariant behind the sync getScope.
- Tests for the clear-before-hydration and raw-key-migration paths.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S3fTN8H3R8YV4yUGvZjYnX
This commit is contained in:
cliffhall 2026-07-01 19:20:49 -04:00
commit 8c10b8eb8e
5 changed files with 197 additions and 26 deletions

View file

@ -30,7 +30,18 @@ export function getWebOAuthBaseUrl(): string {
export const webOAuthFetch: typeof fetch = (...args) => export const webOAuthFetch: typeof fetch = (...args) =>
globalThis.fetch(...args); globalThis.fetch(...args);
/** Memoized `RemoteOAuthStorage` for the given backend + auth token. */ /**
* Memoized `RemoteOAuthStorage` for the given backend + auth token.
*
* The cache key is intentionally `{baseUrl, authToken}` only — `fetchFn` is NOT
* part of it. Whichever call constructs an instance first wins, so a later
* caller's `fetchFn` is ignored. This is safe today because every call site
* either omits `fetchFn` (defaulting to {@link webOAuthFetch}) or passes an
* `environmentFactory` wrapper that is functionally identical (`globalThis.fetch`),
* so the shared-instance goal (one whole-blob writer per backend) matters more
* than which wrapper is used. A future caller needing a genuinely different
* transport must key on it (or bypass the cache).
*/
export function getRemoteOAuthStorage( export function getRemoteOAuthStorage(
baseUrl: string, baseUrl: string,
authToken: string | undefined, authToken: string | undefined,

View file

@ -141,6 +141,48 @@ describe("OAuthStorageBase — async hydration", () => {
expect(await storage.getCodeVerifier(SERVER)).toBe("new"); expect(await storage.getCodeVerifier(SERVER)).toBe("new");
}); });
it("clear() before hydration is not resurrected by the late merge", async () => {
// A clear issued while hydration is still gated must survive the pending
// rehydrate() that would otherwise merge the persisted (un-cleared) blob
// back on top and silently restore the credential.
const { storage, release } = makeAsyncBackedStorage({
[SERVER]: { tokens: { access_token: "t", token_type: "Bearer" } },
});
storage.clear(SERVER);
release();
await storage.ready();
// Give the deferred re-apply (scheduled off `hydrated`) a microtask to run.
await Promise.resolve();
expect(await storage.getTokens(SERVER)).toBeUndefined();
});
it("clearTokens before hydration clears only tokens and survives the merge", async () => {
const { storage, release } = makeAsyncBackedStorage({
[SERVER]: {
tokens: { access_token: "t", token_type: "Bearer" },
codeVerifier: "keep-me",
},
});
storage.clearTokens(SERVER);
release();
await storage.ready();
await Promise.resolve();
// Tokens cleared, but the sibling field from the persisted blob remains.
expect(await storage.getTokens(SERVER)).toBeUndefined();
expect(await storage.getCodeVerifier(SERVER)).toBe("keep-me");
});
it("clear() after hydration does not schedule a deferred re-apply", async () => {
const { storage, release } = makeAsyncBackedStorage({
[SERVER]: { tokens: { access_token: "t", token_type: "Bearer" } },
});
release();
await storage.ready();
// Hydration already settled → synchronous clear, immediately observable.
storage.clear(SERVER);
expect(await storage.getTokens(SERVER)).toBeUndefined();
});
it("normalizeServerUrl canonicalizes host case, bare-origin trailing slash, default port, and whitespace", () => { it("normalizeServerUrl canonicalizes host case, bare-origin trailing slash, default port, and whitespace", () => {
expect(normalizeServerUrl("https://Example.COM/mcp")).toBe( expect(normalizeServerUrl("https://Example.COM/mcp")).toBe(
"https://example.com/mcp", "https://example.com/mcp",
@ -175,6 +217,47 @@ describe("OAuthStorageBase — async hydration", () => {
}); });
}); });
it("a partial write migrates a pre-normalization raw-key blob onto the canonical key (no orphaned fields)", async () => {
// Persisted under the bare-origin raw key (no trailing slash), the form a
// pre-normalization writer used; canonical form is `https://api.partner.dev/`.
// The caller consistently addresses the endpoint with that same raw string
// (matching getServerState's raw-key fallback).
const RAW = "https://api.partner.dev";
const { storage, release } = makeAsyncBackedStorage({
[RAW]: { tokens: { access_token: "existing", token_type: "Bearer" } },
});
release();
await storage.ready();
// A partial write must MERGE onto the existing blob, not shadow it with a
// fresh canonical entry — the pre-existing token must remain reachable.
await storage.saveCodeVerifier(RAW, "v");
expect(await storage.getCodeVerifier(RAW)).toBe("v");
expect(await storage.getTokens(RAW)).toEqual({
access_token: "existing",
token_type: "Bearer",
});
// The blob now lives under the canonical key, so the canonical form finds it
// too and the raw-key orphan no longer shadows anything.
expect(await storage.getTokens("https://api.partner.dev/")).toEqual({
access_token: "existing",
token_type: "Bearer",
});
});
it("clear() removes a pre-normalization raw-key blob, not just the canonical key", async () => {
const RAW = "https://api.partner.dev";
const { storage, release } = makeAsyncBackedStorage({
[RAW]: { tokens: { access_token: "existing", token_type: "Bearer" } },
});
release();
await storage.ready();
storage.clear(RAW);
// Both the canonical and raw keys must be gone — no orphan resurfacing via
// getServerState's raw-key fallback.
expect(await storage.getTokens(RAW)).toBeUndefined();
expect(await storage.getTokens("https://api.partner.dev/")).toBeUndefined();
});
it("getServerState falls back to a pre-normalization persisted key", async () => { it("getServerState falls back to a pre-normalization persisted key", async () => {
// A blob persisted before normalization existed may carry a raw key that // A blob persisted before normalization existed may carry a raw key that
// the canonical form differs from (here: bare-origin without slash). // the canonical form differs from (here: bare-origin without slash).

View file

@ -96,6 +96,34 @@ export class OAuthStorageBase implements OAuthStorage {
return this.hydrated; return this.hydrated;
} }
/**
* Run a `clear*` mutation against a hydrated store: synchronously if
* hydration has already landed, otherwise deferred until it does.
*
* `clear*` are declared synchronous in {@link OAuthStorage} (some feed sync
* SDK getters), so unlike the `save*` family they cannot `await this.hydrated`
* up front. But a clear applied to the still-empty pre-hydration store is
* doubly wrong: (a) the pending `rehydrate()` would merge the persisted
* (un-cleared) blob back over it, resurrecting the credential; and worse,
* (b) applying it triggers a persist write of the near-empty store, which for
* a whole-blob adapter (file / remote HTTP) can clobber the on-disk blob —
* every other server's tokens included — before hydration ever reads it.
* Deferring the mutation until after hydration avoids both: it merges onto
* the real persisted state. The common case (hydration already settled) stays
* synchronous and immediately observable. A failed hydration still resolves
* {@link hydrated} (see constructor), so a deferred clear runs harmlessly
* against the empty store. The effect of a pre-hydration clear is therefore
* asynchronous, which is safe: the only callers are fire-and-forget
* invalidations that never synchronously read the value straight back.
*/
private clearAfterHydration(mutate: () => void): void {
if (this.store.persist.hasHydrated()) {
mutate();
} else {
void this.hydrated.then(mutate);
}
}
async getClientInformation( async getClientInformation(
serverUrl: string, serverUrl: string,
isPreregistered?: boolean, isPreregistered?: boolean,
@ -179,7 +207,9 @@ export class OAuthStorageBase implements OAuthStorage {
} }
clearTokens(serverUrl: string): void { clearTokens(serverUrl: string): void {
this.store.getState().setServerState(serverUrl, { tokens: undefined }); this.clearAfterHydration(() =>
this.store.getState().setServerState(serverUrl, { tokens: undefined }),
);
} }
async getCodeVerifier(serverUrl: string): Promise<string | undefined> { async getCodeVerifier(serverUrl: string): Promise<string | undefined> {
@ -197,18 +227,28 @@ export class OAuthStorageBase implements OAuthStorage {
} }
clearCodeVerifier(serverUrl: string): void { clearCodeVerifier(serverUrl: string): void {
this.store this.clearAfterHydration(() =>
.getState() this.store
.setServerState(serverUrl, { codeVerifier: undefined }); .getState()
.setServerState(serverUrl, { codeVerifier: undefined }),
);
} }
/** /**
* Intentionally synchronous. The only caller is * Intentionally synchronous. The only caller is
* {@link BaseOAuthClientProvider.scope}, a sync getter the SDK requires * {@link BaseOAuthClientProvider.scope}, a sync getter the SDK requires
* (it feeds the sync `clientMetadata` getter). Scope is always set via * (it feeds the sync `clientMetadata` getter). It is safe without awaiting
* {@link saveScope} in the same session before it's read (during the * hydration because of an ordering invariant the callers uphold: some
* pre-redirect half of the flow), so the in-memory store has the value * awaited read always precedes it, flushing hydration first.
* regardless of async hydration. * - Pre-redirect half of the flow: `saveScope` (which awaits hydration)
* writes the value in the same session, so the in-memory store has it.
* - Post-redirect callback path: the in-memory store is reset, so the
* value comes from hydration — but `buildOAuthConnectionState`
* (`connection-state.ts`) awaits `getClientInformation`/
* `getServerMetadata` (both of which await hydration) before it reads
* `getScope`, so hydration has already landed by then.
* A future refactor that reads `getScope` without a preceding awaited
* storage read would break this invariant.
*/ */
getScope(serverUrl: string): string | undefined { getScope(serverUrl: string): string | undefined {
const state = this.store.getState().getServerState(serverUrl); const state = this.store.getState().getServerState(serverUrl);
@ -221,7 +261,9 @@ export class OAuthStorageBase implements OAuthStorage {
} }
clearScope(serverUrl: string): void { clearScope(serverUrl: string): void {
this.store.getState().setServerState(serverUrl, { scope: undefined }); this.clearAfterHydration(() =>
this.store.getState().setServerState(serverUrl, { scope: undefined }),
);
} }
async getServerMetadata(serverUrl: string): Promise<OAuthMetadata | null> { async getServerMetadata(serverUrl: string): Promise<OAuthMetadata | null> {
@ -241,13 +283,17 @@ export class OAuthStorageBase implements OAuthStorage {
} }
clearServerMetadata(serverUrl: string): void { clearServerMetadata(serverUrl: string): void {
this.store this.clearAfterHydration(() =>
.getState() this.store
.setServerState(serverUrl, { serverMetadata: undefined }); .getState()
.setServerState(serverUrl, { serverMetadata: undefined }),
);
} }
clear(serverUrl: string): void { clear(serverUrl: string): void {
this.store.getState().clearServerState(serverUrl); this.clearAfterHydration(() =>
this.store.getState().clearServerState(serverUrl),
);
} }
async getIdpSession(issuer: string): Promise<IdpSessionState | undefined> { async getIdpSession(issuer: string): Promise<IdpSessionState | undefined> {
@ -272,10 +318,14 @@ export class OAuthStorageBase implements OAuthStorage {
} }
clearIdpSession(issuer: string): void { clearIdpSession(issuer: string): void {
this.store.getState().clearIdpSession(issuer); this.clearAfterHydration(() =>
this.store.getState().clearIdpSession(issuer),
);
} }
clearEnterpriseManagedResourceServers(): void { clearEnterpriseManagedResourceServers(): void {
this.store.getState().clearEnterpriseManagedResourceServers(); this.clearAfterHydration(() =>
this.store.getState().clearEnterpriseManagedResourceServers(),
);
} }
} }

View file

@ -10,7 +10,10 @@ import type {
OAuthTokens, OAuthTokens,
OAuthMetadata, OAuthMetadata,
} from "@modelcontextprotocol/sdk/shared/auth.js"; } from "@modelcontextprotocol/sdk/shared/auth.js";
import type { IdpSessionState, OAuthClientRegistrationKind } from "./storage.js"; import type {
IdpSessionState,
OAuthClientRegistrationKind,
} from "./storage.js";
/** /**
* OAuth state for a single server * OAuth state for a single server
@ -92,21 +95,36 @@ export function createOAuthStore(
updates: Partial<ServerOAuthState>, updates: Partial<ServerOAuthState>,
) => { ) => {
const key = normalizeServerUrl(serverUrl); const key = normalizeServerUrl(serverUrl);
set((state) => ({ set((state) => {
servers: { const servers = { ...state.servers };
...state.servers, // Mirror getServerState's canonical→raw fallback for writes: if no
[key]: { // canonical entry exists yet but a pre-normalization blob lives
...state.servers[key], // under the raw key, migrate it onto the canonical key so this
...updates, // partial write MERGES onto the existing credential instead of
}, // shadowing it with a fresh canonical entry (which would orphan the
}, // raw-key blob's other fields — e.g. a token — behind the new
})); // canonical one that getServerState now prefers).
let base = servers[key];
if (base === undefined && servers[serverUrl] !== undefined) {
// Reaching here implies `serverUrl !== key`: if they were equal,
// `servers[serverUrl]` would equal the `servers[key]` we just
// found undefined, so the guard above could not have passed.
base = servers[serverUrl];
delete servers[serverUrl];
}
servers[key] = { ...base, ...updates };
return { servers };
});
}, },
clearServerState: (serverUrl: string) => { clearServerState: (serverUrl: string) => {
const key = normalizeServerUrl(serverUrl); const key = normalizeServerUrl(serverUrl);
set((state) => { set((state) => {
const rest = { ...state.servers }; const rest = { ...state.servers };
delete rest[key]; delete rest[key];
// Also drop a pre-normalization blob under the raw key so a clear
// fully removes the credential rather than leaving an orphan that
// getServerState's raw-key fallback would keep surfacing.
if (serverUrl !== key) delete rest[serverUrl];
return { servers: rest }; return { servers: rest };
}); });
}, },

View file

@ -72,6 +72,15 @@ export function createRemoteStorageAdapter(
// full-page navigation (the OAuth authorize redirect): without it the // full-page navigation (the OAuth authorize redirect): without it the
// browser may abort the request mid-flight and the just-saved // browser may abort the request mid-flight and the just-saved
// codeVerifier/clientInformation never reaches disk. // codeVerifier/clientInformation never reaches disk.
//
// Caveat: the fetch spec caps the *combined* body size of all in-flight
// keepalive requests at 64 KB. `value` here is the whole store blob
// (every server's tokens + metadata), so a user with a very large
// number of authorized servers could in theory exceed that and have the
// browser reject this write. That ceiling is well above realistic
// inspector usage; if it ever bites, the fix is per-server stores rather
// than dropping `keepalive` (which would reintroduce the redirect-abort
// bug this guards against). The catch below surfaces such a rejection.
const res = await fetchFn(url, { const res = await fetchFn(url, {
method: "POST", method: "POST",
headers, headers,