feat(web): migrate OAuth store to shared /store API (RemoteOAuthStorage parity) (closes #1548)

Migrate the web client's OAuth storage from BrowserOAuthStorage
(sessionStorage) to RemoteOAuthStorage, which POSTs through the backend's
/api/storage/oauth route to ~/.mcp-inspector/storage/oauth.json (mode 0600).
A credential obtained in the browser is now the same blob the TUI/CLI read
on the same host, giving web ⇄ TUI ⇄ CLI parity (Wave 1 of #1579).

Core (shared with TUI/CLI):
- OAuthStorageBase now drives a single async hydration (`ready()`,
  `getHydrationError()`); every post-redirect read (getClientInformation,
  getTokens, getCodeVerifier, getServerMetadata, getIdpSession) and every
  save awaits it so a late hydration merge cannot clobber a fresh write.
  getCodeVerifier/getServerMetadata become async; the store is created with
  skipHydration:true so there is no auto-hydration to race the explicit one.
- store.ts adds normalizeServerUrl so a token saved under
  https://Example.com/mcp is found when the CLI asks for
  https://example.com/mcp/; getServerState falls back to the raw key.
- remote-storage adapter POSTs with keepalive so the write survives the
  OAuth authorize redirect, surfaces swallowed persist failures, and gives
  richer read/write error messages.
- generateOAuthState throws instead of silently degrading to Math.random.
- NodeOAuthStorage honors MCP_INSPECTOR_OAUTH_STATE_PATH for isolated
  fixtures. Provider codeVerifier()/getServerMetadata() + the EMA idpOidc and
  connection-state readers await the now-async storage.

Web:
- environmentFactory + a new shared lib/remoteOAuthStorage accessor
  (memoized per {baseUrl, authToken}) wire RemoteOAuthStorage into the
  connection path, the EMA IdP hook, and the per-server "clear OAuth" action
  so all three share one in-memory view of oauth.json.

Tests: async-hydration + normalizeServerUrl suite, keepalive/error-path
coverage, and the sync→async migration across existing storage/provider/EMA
tests. Web validate + coverage gate + integration suite green; CLI/TUI/
launcher validate green.

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 18:39:17 -04:00
commit c299b6e9d8
9 changed files with 786 additions and 135 deletions

View file

@ -86,7 +86,7 @@ export async function buildOAuthConnectionState(
const preregistered = await storage.getClientInformation(serverUrl, true);
const dynamic = await storage.getClientInformation(serverUrl);
const storageScope = storage.getScope(serverUrl);
const serverMetadata = storage.getServerMetadata(serverUrl);
const serverMetadata = await storage.getServerMetadata(serverUrl);
const authorized = isAccessTokenUsable(tokens);
const grantedScope = resolveGrantedScope(tokens, storageScope);
@ -120,7 +120,9 @@ export async function buildOAuthConnectionState(
const idp = params.enterpriseManagedAuth.idp;
const issuer = normalizeIdpIssuer(idp.issuer);
const idpSession = await getEmaIdpLoginState(storage, issuer);
const idpMetadata = storage.getServerMetadata(idpOAuthStorageKey(issuer));
const idpMetadata = await storage.getServerMetadata(
idpOAuthStorageKey(issuer),
);
state.ema = {
idpIssuer: issuer,
idpClientId: idp.clientId,

View file

@ -35,7 +35,7 @@ async function resolveIdpMetadata(
fetchFn?: typeof fetch,
): Promise<OAuthMetadata> {
const storageKey = idpOAuthStorageKey(issuer);
const cached = storage.getServerMetadata(storageKey);
const cached = await storage.getServerMetadata(storageKey);
if (cached?.token_endpoint) {
return cached;
}
@ -101,7 +101,7 @@ export async function completeIdpOidcAuthorization(params: {
}> {
const issuer = normalizeIdpIssuer(params.idp.issuer);
const storageKey = idpOAuthStorageKey(issuer);
const metadata = params.storage.getServerMetadata(storageKey);
const metadata = await params.storage.getServerMetadata(storageKey);
if (!metadata) {
throw new Error("IdP OAuth metadata not found — restart EMA IdP login");
}
@ -111,7 +111,7 @@ export async function completeIdpOidcAuthorization(params: {
if (!clientInformation) {
throw new Error("IdP client information not found — restart EMA IdP login");
}
const codeVerifier = params.storage.getCodeVerifier(storageKey);
const codeVerifier = await params.storage.getCodeVerifier(storageKey);
if (!codeVerifier) {
throw new Error("IdP PKCE verifier not found — restart EMA IdP login");
}

View file

@ -10,11 +10,17 @@ import {
const DEFAULT_STATE_PATH = getStoreFilePath(getDefaultStorageDir(), "oauth");
/**
* Get path to OAuth state file.
* @param customPath - Optional custom path (full path to state file). Default: ~/.mcp-inspector/storage/oauth.json
* Get path to OAuth state file. Resolution order: explicit `customPath`, then
* the `MCP_INSPECTOR_OAUTH_STATE_PATH` environment variable (so tests and
* scripted runs can point at an isolated fixture without touching
* `~/.mcp-inspector`), then the default `~/.mcp-inspector/storage/oauth.json`.
*/
export function getStateFilePath(customPath?: string): string {
return customPath ?? DEFAULT_STATE_PATH;
return (
customPath ??
process.env.MCP_INSPECTOR_OAUTH_STATE_PATH ??
DEFAULT_STATE_PATH
);
}
const storeCache = new Map<string, ReturnType<typeof createOAuthStore>>();

View file

@ -20,18 +20,87 @@ import type {
* Concrete OAuthStorage implementation parameterized on a Zustand store.
* The store carries the storage adapter (sessionStorage, file, remote HTTP, …),
* so the same body works for browser, Node, and remote environments.
*
* With an async storage adapter (file, remote HTTP) the store is empty until
* hydration completes. Every read used on the post-OAuth-redirect callback path
* (`getCodeVerifier`, `getServerMetadata`, `getClientInformation`, `getTokens`)
* — and every save — therefore awaits {@link ready} first; saves wait so a
* late hydration merge cannot clobber a value written before it landed. The
* underlying store is created with `skipHydration: true`
* ({@link createOAuthStore}), so the constructor's `rehydrate()` is the single
* hydration and there is no auto-hydration to race it. With a synchronous
* adapter (sessionStorage) hydration resolves on the next microtask and the
* behaviour is effectively unchanged.
*/
export class OAuthStorageBase implements OAuthStorage {
private readonly store: ReturnType<typeof createOAuthStore>;
private readonly hydrated: Promise<void>;
private hydrationError?: Error;
constructor(store: ReturnType<typeof createOAuthStore>) {
this.store = store;
// The store is created with `skipHydration: true` so this is the SOLE
// hydration. Driving it explicitly (rather than relying on persist's
// auto-hydration + onFinishHydration) lets us catch a rejecting adapter —
// onFinishHydration only fires on success, so a throwing getItem would
// otherwise leave `hydrated` pending forever and hang every getter.
// A failed hydration resolves to "empty store", which is the correct
// fallback (reads return undefined; writes proceed) — but the failure is
// recorded so callers can distinguish "no token stored" from "could not
// read the store" (e.g. corrupt file, EACCES, backend 500).
const recordFailure = (err: unknown) => {
this.hydrationError =
err instanceof Error
? err
: new Error(
typeof err === "string"
? err
: "OAuth storage hydration failed (adapter getItem threw or returned invalid data)",
);
console.warn(
"[OAuthStorage] hydration failed; continuing with empty state:",
this.hydrationError,
);
};
this.hydrated = this.store.persist.hasHydrated()
? Promise.resolve()
: Promise.resolve(this.store.persist.rehydrate()).then(
() => {
// Zustand swallows getItem errors internally (routing them to
// onRehydrateStorage) and resolves rehydrate() regardless;
// hasHydrated() only flips true on success, so use it to detect a
// silently-failed hydration. The underlying error is lost in this
// path — record a generic one so getHydrationError() is non-null.
if (!this.store.persist.hasHydrated()) recordFailure(undefined);
},
(err: unknown) => recordFailure(err),
);
}
/**
* If hydration failed (adapter threw, file unreadable/corrupt, backend
* non-2xx), the captured error. Undefined when hydration succeeded or has
* not yet completed — call after `await ready()`. Lets callers report
* "oauth.json is unreadable" instead of a misleading "no token stored".
*/
getHydrationError(): Error | undefined {
return this.hydrationError;
}
/**
* Resolves once the underlying persist adapter has hydrated the store.
* Callers that need to read state outside the typed getters can await this
* directly (e.g. before reading the store via `getState()` for diagnostics).
*/
ready(): Promise<void> {
return this.hydrated;
}
async getClientInformation(
serverUrl: string,
isPreregistered?: boolean,
): Promise<OAuthClientInformation | undefined> {
await this.hydrated;
const state = this.store.getState().getServerState(serverUrl);
const clientInfo = isPreregistered
? state.preregisteredClientInformation
@ -56,6 +125,7 @@ export class OAuthStorageBase implements OAuthStorage {
clientInformation: OAuthClientInformation,
options: SaveClientInformationOptions,
): Promise<void> {
await this.hydrated;
this.store.getState().setServerState(serverUrl, {
clientInformation,
clientRegistrationKind: options.registrationKind,
@ -66,6 +136,7 @@ export class OAuthStorageBase implements OAuthStorage {
serverUrl: string,
clientInformation: OAuthClientInformation,
): Promise<void> {
await this.hydrated;
this.store.getState().setServerState(serverUrl, {
preregisteredClientInformation: clientInformation,
clientRegistrationKind: "static",
@ -86,6 +157,7 @@ export class OAuthStorageBase implements OAuthStorage {
}
async getTokens(serverUrl: string): Promise<OAuthTokens | undefined> {
await this.hydrated;
const state = this.store.getState().getServerState(serverUrl);
if (!state.tokens) {
return undefined;
@ -99,6 +171,7 @@ export class OAuthStorageBase implements OAuthStorage {
tokens: OAuthTokens,
options?: SaveTokensOptions,
): Promise<void> {
await this.hydrated;
this.store.getState().setServerState(serverUrl, {
tokens,
...(options?.enterpriseManaged === true && { enterpriseManaged: true }),
@ -109,7 +182,8 @@ export class OAuthStorageBase implements OAuthStorage {
this.store.getState().setServerState(serverUrl, { tokens: undefined });
}
getCodeVerifier(serverUrl: string): string | undefined {
async getCodeVerifier(serverUrl: string): Promise<string | undefined> {
await this.hydrated;
const state = this.store.getState().getServerState(serverUrl);
return state.codeVerifier;
}
@ -118,6 +192,7 @@ export class OAuthStorageBase implements OAuthStorage {
serverUrl: string,
codeVerifier: string,
): Promise<void> {
await this.hydrated;
this.store.getState().setServerState(serverUrl, { codeVerifier });
}
@ -127,12 +202,21 @@ export class OAuthStorageBase implements OAuthStorage {
.setServerState(serverUrl, { codeVerifier: undefined });
}
/**
* Intentionally synchronous. The only caller is
* {@link BaseOAuthClientProvider.scope}, a sync getter the SDK requires
* (it feeds the sync `clientMetadata` getter). Scope is always set via
* {@link saveScope} in the same session before it's read (during the
* pre-redirect half of the flow), so the in-memory store has the value
* regardless of async hydration.
*/
getScope(serverUrl: string): string | undefined {
const state = this.store.getState().getServerState(serverUrl);
return state.scope;
}
async saveScope(serverUrl: string, scope: string | undefined): Promise<void> {
await this.hydrated;
this.store.getState().setServerState(serverUrl, { scope });
}
@ -140,7 +224,8 @@ export class OAuthStorageBase implements OAuthStorage {
this.store.getState().setServerState(serverUrl, { scope: undefined });
}
getServerMetadata(serverUrl: string): OAuthMetadata | null {
async getServerMetadata(serverUrl: string): Promise<OAuthMetadata | null> {
await this.hydrated;
const state = this.store.getState().getServerState(serverUrl);
return state.serverMetadata || null;
}
@ -149,6 +234,7 @@ export class OAuthStorageBase implements OAuthStorage {
serverUrl: string,
metadata: OAuthMetadata,
): Promise<void> {
await this.hydrated;
this.store
.getState()
.setServerState(serverUrl, { serverMetadata: metadata });
@ -165,6 +251,7 @@ export class OAuthStorageBase implements OAuthStorage {
}
async getIdpSession(issuer: string): Promise<IdpSessionState | undefined> {
await this.hydrated;
const session = this.store.getState().getIdpSession(issuer);
if (
!session.idToken &&
@ -180,6 +267,7 @@ export class OAuthStorageBase implements OAuthStorage {
issuer: string,
session: Partial<IdpSessionState>,
): Promise<void> {
await this.hydrated;
this.store.getState().setIdpSession(issuer, session);
}

View file

@ -234,8 +234,8 @@ export class BaseOAuthClientProvider implements OAuthClientProvider {
await this.storage.saveCodeVerifier(this.serverUrl, codeVerifier);
}
codeVerifier(): string {
const verifier = this.storage.getCodeVerifier(this.serverUrl);
async codeVerifier(): Promise<string> {
const verifier = await this.storage.getCodeVerifier(this.serverUrl);
if (!verifier) {
throw new Error("No code verifier saved for session");
}
@ -246,8 +246,8 @@ export class BaseOAuthClientProvider implements OAuthClientProvider {
this.storage.clear(this.serverUrl);
}
getServerMetadata(): OAuthMetadata | null {
return this.storage.getServerMetadata(this.serverUrl);
async getServerMetadata(): Promise<OAuthMetadata | null> {
return await this.storage.getServerMetadata(this.serverUrl);
}
async saveServerMetadata(metadata: OAuthMetadata): Promise<void> {

View file

@ -21,6 +21,12 @@ export interface SaveClientInformationOptions {
}
export interface OAuthStorage {
/**
* Resolves once any async hydration of the underlying store has completed.
* With a synchronous storage adapter this resolves immediately.
*/
ready(): Promise<void>;
/**
* Get client information (preregistered or dynamically registered)
*/
@ -78,9 +84,13 @@ export interface OAuthStorage {
clearTokens(serverUrl: string): void;
/**
* Get code verifier (for PKCE)
* Get code verifier (for PKCE).
*
* Async because the backend-backed store may still be hydrating when this is
* read on the post-redirect OAuth callback path; the implementation awaits
* hydration before reading.
*/
getCodeVerifier(serverUrl: string): string | undefined;
getCodeVerifier(serverUrl: string): Promise<string | undefined>;
/**
* Save code verifier (for PKCE)
@ -108,9 +118,13 @@ export interface OAuthStorage {
clearScope(serverUrl: string): void;
/**
* Get server metadata discovered during OAuth
* Get server metadata discovered during OAuth.
*
* Async because the backend-backed store may still be hydrating when this is
* read on the post-redirect OAuth callback path; the implementation awaits
* hydration before reading.
*/
getServerMetadata(serverUrl: string): OAuthMetadata | null;
getServerMetadata(serverUrl: string): Promise<OAuthMetadata | null>;
/**
* Save server metadata discovered during OAuth

View file

@ -28,6 +28,26 @@ export interface ServerOAuthState {
enterpriseManaged?: boolean;
}
/**
* Normalize a server URL to its canonical form for use as a store key.
*
* Different callers (web deep-link parser, CLI `--server-url`, the SDK's own
* client constructor) can present the same endpoint with cosmetic differences
* — host case, a trailing slash on a bare-origin URL, default-port omission —
* that `new URL().href` collapses. Keying by the canonical form means a token
* the web inspector saved under `https://Example.com/mcp` is found when the
* CLI later asks for `https://example.com/mcp/`. Non-URL strings (e.g. a
* stdio server name) are returned trimmed so the store still works for them.
*/
export function normalizeServerUrl(serverUrl: string): string {
const trimmed = serverUrl.trim();
try {
return new URL(trimmed).href;
} catch {
return trimmed;
}
}
/**
* Zustand store state (all servers)
*/
@ -59,26 +79,34 @@ export function createOAuthStore(
servers: {},
idpSessions: {},
getServerState: (serverUrl: string) => {
return get().servers[serverUrl] || {};
const servers = get().servers;
// Look up by canonical key, falling back to the raw key so an
// already-persisted blob written before normalization existed (or by
// another writer) is still found.
return (
servers[normalizeServerUrl(serverUrl)] ?? servers[serverUrl] ?? {}
);
},
setServerState: (
serverUrl: string,
updates: Partial<ServerOAuthState>,
) => {
const key = normalizeServerUrl(serverUrl);
set((state) => ({
servers: {
...state.servers,
[serverUrl]: {
...state.servers[serverUrl],
[key]: {
...state.servers[key],
...updates,
},
},
}));
},
clearServerState: (serverUrl: string) => {
const key = normalizeServerUrl(serverUrl);
set((state) => {
const rest = { ...state.servers };
delete rest[serverUrl];
delete rest[key];
return { servers: rest };
});
},
@ -118,6 +146,11 @@ export function createOAuthStore(
{
name: "mcp-inspector-oauth",
storage,
// OAuthStorageBase drives `persist.rehydrate()` itself so it can await
// (and catch errors from) the single hydration. Auto-hydration here
// would race the explicit one and could clobber a save that landed
// between them.
skipHydration: true,
},
),
);

View file

@ -50,20 +50,17 @@ export const parseOAuthCallbackParams = (location: string): CallbackParams => {
* @returns A random state for the OAuth 2.0 flow.
*/
export const generateOAuthState = (): string => {
// Generate a random state
const array = new Uint8Array(32);
// Use crypto.getRandomValues (available in both browser and Node.js)
if (typeof crypto !== "undefined" && crypto.getRandomValues) {
crypto.getRandomValues(array);
} else {
// Fallback for environments without crypto.getRandomValues
// This should not happen in modern environments
for (let i = 0; i < array.length; i++) {
array[i] = Math.floor(Math.random() * 256);
}
// OAuth state is a CSRF token — it MUST be unpredictable. crypto.getRandomValues
// is available in every supported runtime (browsers, Node ≥15); if it's somehow
// missing, fail loudly rather than silently degrading to Math.random (whose
// output is predictable from a small amount of observed state).
if (typeof crypto === "undefined" || !crypto.getRandomValues) {
throw new Error(
"crypto.getRandomValues is not available; refusing to generate an OAuth state with a non-cryptographic RNG.",
);
}
const array = new Uint8Array(32);
crypto.getRandomValues(array);
return Array.from(array, (byte) => byte.toString(16).padStart(2, "0")).join(
"",
);

View file

@ -42,7 +42,9 @@ export function createRemoteStorageAdapter(
if (res.status === 404) {
return null;
}
throw new Error(`Failed to read store: ${res.status}`);
throw new Error(
`Failed to read store '${options.storeId}' from ${baseUrl}/api/storage/${options.storeId}: ${res.status}`,
);
}
const store = await res.json();
@ -62,16 +64,32 @@ export function createRemoteStorageAdapter(
headers["x-mcp-remote-auth"] = `Bearer ${options.authToken}`;
}
// Zustand gives us the full persisted format as a string
// Store it as-is (the API treats it as an opaque blob)
const res = await fetchFn(`${baseUrl}/api/storage/${options.storeId}`, {
method: "POST",
headers,
body: value, // Already a JSON string from Zustand
});
const url = `${baseUrl}/api/storage/${options.storeId}`;
try {
// Zustand gives us the full persisted format as a string
// Store it as-is (the API treats it as an opaque blob).
// `keepalive` lets this POST outlive an immediately-following
// full-page navigation (the OAuth authorize redirect): without it the
// browser may abort the request mid-flight and the just-saved
// codeVerifier/clientInformation never reaches disk.
const res = await fetchFn(url, {
method: "POST",
headers,
body: value, // Already a JSON string from Zustand
keepalive: true,
});
if (!res.ok) {
throw new Error(`Failed to write store: ${res.status}`);
if (!res.ok) {
throw new Error(
`Failed to write store '${options.storeId}' to ${url}: ${res.status}`,
);
}
} catch (err) {
// Zustand's persist middleware swallows setItem rejections — without
// this the user sees a green "Connected" while the token never landed
// on disk. Surface the failure so it's at least observable.
console.error("[remote-storage] persist write failed:", err);
throw err;
}
},
removeItem: async (_name: string) => {