oauth-callback 2.1.0 → 2.2.0

package/src/auth/browser-auth.ts

@@ -2,18 +2,22 @@
 /* SPDX-License-Identifier: MIT */
 
 import { randomBytes } from "node:crypto";
-import type {
-  BrowserAuthOptions,
-  TokenStore,
-  OAuthStore,
-  Tokens,
-  ClientInfo,
-  OAuthSession,
+import {
+  OAuthStoreBrand,
+  type BrowserAuthOptions,
+  type TokenStore,
+  type OAuthStore,
+  type Tokens,
+  type ClientInfo,
 } from "../mcp-types";
 import { calculateExpiry } from "../utils/token";
 import { inMemoryStore } from "../storage/memory";
 import { getAuthCode } from "../index";
 import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
+import {
+  exchangeAuthorization,
+  discoverAuthorizationServerMetadata,
+} from "@modelcontextprotocol/sdk/client/auth.js";
 import type {
   OAuthClientInformation,
   OAuthClientInformationFull,
@@ -56,6 +60,7 @@ class BrowserOAuthProvider implements OAuthClientProvider {
   private readonly _hostname: string;
   private readonly _callbackPath: string;
   private readonly _authTimeout: number;
+  private readonly _redirectUrl: string;
   private readonly _launch?: (url: string) => unknown;
   private readonly _clientId?: string;
   private readonly _clientSecret?: string;
@@ -63,14 +68,13 @@ class BrowserOAuthProvider implements OAuthClientProvider {
   private readonly _successHtml?: string;
   private readonly _errorHtml?: string;
   private readonly _onRequest?: (req: Request) => void;
+  private readonly _authServerUrl?: URL;
 
   /** Mutable OAuth state. Protected by serialization locks. */
   private _clientInfo?: OAuthClientInformationFull;
   private _tokens?: OAuthTokens;
+  private _expiresAt?: number; // Absolute expiry time in ms
   private _codeVerifier?: string;
-  private _pendingAuthCode?: string;
-  private _pendingAuthState?: string;
-  private _isExchangingCode = false;
   private _tokensLoaded = false;
   private _loadingTokens?: Promise<void>;
   private _authInProgress?: Promise<void>;
@@ -82,6 +86,7 @@ class BrowserOAuthProvider implements OAuthClientProvider {
     this._hostname = options.hostname ?? "localhost";
     this._callbackPath = options.callbackPath ?? "/callback";
     this._authTimeout = options.authTimeout ?? 300000;
+    this._redirectUrl = `http://${this._hostname}:${this._port}${this._callbackPath}`;
     this._launch = options.launch;
     this._clientId = options.clientId;
     this._clientSecret = options.clientSecret;
@@ -90,6 +95,9 @@ class BrowserOAuthProvider implements OAuthClientProvider {
     this._successHtml = options.successHtml;
     this._errorHtml = options.errorHtml;
     this._onRequest = options.onRequest;
+    this._authServerUrl = options.authServerUrl
+      ? new URL(options.authServerUrl)
+      : undefined;
   }
 
   private async _ensureTokensLoaded(): Promise<void> {
@@ -107,34 +115,36 @@ class BrowserOAuthProvider implements OAuthClientProvider {
       // Load tokens
       const stored = await this._store.get(this._storeKey);
       if (stored) {
+        this._expiresAt = stored.expiresAt;
+        // SDK doesn't inspect expires_in from tokens() - we handle expiry via expiresAt
         this._tokens = {
           access_token: stored.accessToken,
           token_type: "Bearer",
           refresh_token: stored.refreshToken,
-          expires_in: stored.expiresAt
-            ? Math.floor((stored.expiresAt - Date.now()) / 1000)
-            : undefined,
           scope: stored.scope,
         };
       }
 
-      // Load client info if using extended store
       if (this._isOAuthStore(this._store)) {
-        const clientInfo = await this._store.getClient(this._storeKey);
-        if (clientInfo?.clientId) {
-          this._clientInfo = {
-            client_id: clientInfo.clientId,
-            client_secret: clientInfo.clientSecret,
-            client_id_issued_at: clientInfo.clientIdIssuedAt,
-            client_secret_expires_at: clientInfo.clientSecretExpiresAt,
-            redirect_uris: [this.redirectUrl],
-          };
+        // Load DCR client only if no static clientId is configured.
+        // Static clientId takes precedence; persisted DCR client is ignored.
+        if (!this._clientId) {
+          const clientInfo = await this._store.getClient(this._storeKey);
+          if (clientInfo?.clientId) {
+            this._clientInfo = {
+              client_id: clientInfo.clientId,
+              client_secret: clientInfo.clientSecret,
+              client_id_issued_at: clientInfo.clientIdIssuedAt,
+              client_secret_expires_at: clientInfo.clientSecretExpiresAt,
+              redirect_uris: [this.redirectUrl],
+            };
+          }
         }
 
-        // Load session state
-        const session = await this._store.getSession(this._storeKey);
-        if (session?.codeVerifier) {
-          this._codeVerifier = session.codeVerifier;
+        // Load PKCE verifier for crash recovery
+        const verifier = await this._store.getCodeVerifier(this._storeKey);
+        if (verifier) {
+          this._codeVerifier = verifier;
         }
       }
 
@@ -145,24 +155,22 @@ class BrowserOAuthProvider implements OAuthClientProvider {
     }
   }
 
-  private _isOAuthStore(store: any): store is OAuthStore {
-    return (
-      typeof store.getClient === "function" &&
-      typeof store.setClient === "function" &&
-      typeof store.getSession === "function"
-    );
+  private _isOAuthStore(store: TokenStore): store is OAuthStore {
+    return OAuthStoreBrand in store;
   }
 
   get redirectUrl(): string {
-    return `http://${this._hostname}:${this._port}${this._callbackPath}`;
+    return this._redirectUrl;
   }
 
   get clientMetadata(): OAuthClientMetadata {
+    // Auth method is fixed based on whether clientSecret was provided at construction.
+    // Don't check _clientInfo.client_secret here - metadata must be stable for DCR.
     return {
       client_name: "OAuth Callback Handler",
       client_uri: "https://github.com/kriasoft/oauth-callback",
       redirect_uris: [this.redirectUrl],
-      grant_types: ["authorization_code", "refresh_token"],
+      grant_types: ["authorization_code"],
       response_types: ["code"],
       scope: this._scope,
       token_endpoint_auth_method: this._clientSecret
@@ -218,10 +226,8 @@ class BrowserOAuthProvider implements OAuthClientProvider {
       return undefined;
     }
 
-    // Check expiry using stored expiresAt from initial token response
-    const stored = await this._store.get(this._storeKey);
-    if (stored?.expiresAt && Date.now() >= stored.expiresAt - 60000) {
-      // Token expired (with 60s buffer). Refresh not yet implemented — trigger re-auth.
+    // Return undefined when expired (with 60s buffer) to signal MCP SDK to re-authenticate
+    if (this._expiresAt && Date.now() >= this._expiresAt - 60000) {
       return undefined;
     }
 
@@ -230,28 +236,41 @@ class BrowserOAuthProvider implements OAuthClientProvider {
 
   async saveTokens(tokens: OAuthTokens): Promise<void> {
     this._tokens = tokens;
+    this._expiresAt = tokens.expires_in
+      ? calculateExpiry(tokens.expires_in)
+      : undefined;
     this._tokensLoaded = true;
 
     const storedTokens: Tokens = {
       accessToken: tokens.access_token,
       refreshToken: tokens.refresh_token,
-      expiresAt: tokens.expires_in
-        ? calculateExpiry(tokens.expires_in)
-        : undefined,
+      expiresAt: this._expiresAt,
       scope: tokens.scope,
     };
 
     await this._store.set(this._storeKey, storedTokens);
   }
 
+  /**
+   * Completes the full OAuth authorization flow synchronously.
+   *
+   * Despite the name (dictated by the MCP SDK interface), this method does more
+   * than redirect: it launches the browser, captures the callback, validates state,
+   * exchanges the authorization code for tokens, and persists them to storage.
+   *
+   * Concurrent calls are serialized: subsequent callers wait for and share the
+   * result (or error) of the in-flight attempt.
+   *
+   * @see ADR-002 for rationale on immediate token exchange
+   */
   async redirectToAuthorization(authorizationUrl: URL): Promise<void> {
-    /** Serialize concurrent auth attempts to prevent race conditions. */
+    // Concurrent callers share both success and failure of the in-flight attempt.
     if (this._authInProgress) {
       await this._authInProgress;
       return;
     }
 
-    this._authInProgress = this._doAuthorization(authorizationUrl);
+    this._authInProgress = this._completeAuthorizationFlow(authorizationUrl);
     try {
       await this._authInProgress;
     } finally {
@@ -259,7 +278,9 @@ class BrowserOAuthProvider implements OAuthClientProvider {
     }
   }
 
-  private async _doAuthorization(authorizationUrl: URL): Promise<void> {
+  private async _completeAuthorizationFlow(
+    authorizationUrl: URL,
+  ): Promise<void> {
     // Use managed mode (with launch) or headless mode based on _launch presence
     const baseOptions = {
       port: this._port,
@@ -281,29 +302,97 @@ class BrowserOAuthProvider implements OAuthClientProvider {
         : baseOptions,
     );
 
-    /** Cache auth code for SDK's separate token exchange call. */
-    this._pendingAuthCode = result.code;
-    this._pendingAuthState = result.state;
+    // getAuthCode() throws OAuthError if result.error exists; this is a defensive
+    // check for the edge case where neither code nor error is present.
+    if (!result.code) {
+      throw new Error("No authorization code received");
+    }
 
-    /** Auto-cleanup stale auth codes after timeout to prevent leaks. */
-    setTimeout(() => {
-      if (this._pendingAuthCode === result.code) {
-        this._pendingAuthCode = undefined;
-        this._pendingAuthState = undefined;
+    // Validate state from callback against the URL we were given (CSRF protection).
+    // Works regardless of whether state() was used - validates whatever is in the URL.
+    const expectedState = authorizationUrl.searchParams.get("state");
+    if (expectedState && result.state !== expectedState) {
+      throw new Error("OAuth state mismatch - possible CSRF attack");
+    }
+
+    /**
+     * Exchange auth code for tokens immediately after capture.
+     *
+     * The MCP SDK's auth() returns 'REDIRECT' after redirectToAuthorization()
+     * without re-checking for tokens. By exchanging now, subsequent auth calls
+     * will find valid tokens and return 'AUTHORIZED'.
+     *
+     * This enables synchronous browser flows for CLI/desktop apps where the
+     * callback is captured in-process rather than via page redirect.
+     */
+    await this._exchangeCodeForTokens(authorizationUrl, result.code);
+  }
+
+  /**
+   * Exchange authorization code for tokens and persist them.
+   *
+   * The MCP SDK's auth() returns 'REDIRECT' after redirectToAuthorization() without
+   * re-checking for tokens, causing the transport to throw UnauthorizedError. However,
+   * tokens are now saved, so a subsequent connect() attempt will succeed.
+   *
+   * @see ADR-002 for the recommended retry pattern with a fresh transport
+   */
+  private async _exchangeCodeForTokens(
+    authorizationUrl: URL,
+    code: string,
+  ): Promise<void> {
+    // Derive auth server URL from authorization endpoint origin.
+    // If the token endpoint is on a different origin, authServerUrl must be explicitly configured.
+    const authServerUrl =
+      this._authServerUrl ?? new URL("/", authorizationUrl.origin);
+
+    // Discover token endpoint; non-fatal if .well-known is unavailable
+    const metadata = await discoverAuthorizationServerMetadata(
+      authServerUrl,
+    ).catch(() => undefined);
+
+    const clientInfo = await this.clientInformation();
+    if (!clientInfo) {
+      throw new Error(
+        "Client information required for token exchange. " +
+          "Provide clientId in options or ensure DCR succeeded.",
+      );
+    }
+
+    if (!this._codeVerifier) {
+      throw new Error("Code verifier required for token exchange");
+    }
+
+    let tokens: OAuthTokens;
+    try {
+      tokens = await exchangeAuthorization(authServerUrl, {
+        metadata,
+        clientInformation: clientInfo,
+        authorizationCode: code,
+        codeVerifier: this._codeVerifier,
+        redirectUri: this.redirectUrl,
+      });
+    } catch (error) {
+      // Improve error message when discovery failed and authServerUrl wasn't explicitly set.
+      // This helps users diagnose cases where auth and token endpoints are on different origins.
+      if (!this._authServerUrl && !metadata) {
+        const msg = error instanceof Error ? error.message : String(error);
+        throw new Error(
+          `Token exchange failed: ${msg}. ` +
+            `If the token endpoint differs from ${authorizationUrl.origin}, set authServerUrl explicitly.`,
+        );
       }
-    }, this._authTimeout);
+      throw error;
+    }
+
+    await this.saveTokens(tokens);
   }
 
   async saveCodeVerifier(codeVerifier: string): Promise<void> {
     this._codeVerifier = codeVerifier;
 
-    // Persist session state if using extended store
     if (this._isOAuthStore(this._store)) {
-      const session: OAuthSession = {
-        codeVerifier,
-        state: this._pendingAuthState,
-      };
-      await this._store.setSession(this._storeKey, session);
+      await this._store.setCodeVerifier(this._storeKey, codeVerifier);
     }
   }
 
@@ -317,90 +406,45 @@ class BrowserOAuthProvider implements OAuthClientProvider {
   async invalidateCredentials(
     scope: "all" | "client" | "tokens" | "verifier",
   ): Promise<void> {
-    /**
-     * SDK behavioral dependency: The MCP SDK may call invalidate("all") during
-     * token exchange if the authorization server returns an error. The call
-     * sequence we protect against:
-     *
-     *   1. SDK calls getPendingAuthCode() → sets _isExchangingCode = true
-     *   2. SDK calls codeVerifier() to build token request
-     *   3. SDK sends token exchange request to authorization server
-     *   4. Server returns error → SDK calls invalidateCredentials("all")
-     *   5. SDK retries from step 2, but verifier is gone → permanent failure
-     *
-     * Without this guard, step 4 would clear the verifier needed for step 5.
-     * The flag is reset when SDK calls invalidate("client") after exchange.
-     */
-    if (scope === "all" && this._isExchangingCode) {
-      /** Only clear tokens; preserve client and verifier for ongoing exchange. */
-      this._tokens = undefined;
-      await this._store.delete(this._storeKey);
-      return;
-    }
-
-    if (this._isExchangingCode && (scope === "client" || scope === "all")) {
-      this._isExchangingCode = false;
-    }
-
     switch (scope) {
       case "all":
+        // Scoped deletion: only clear data for this storeKey, not the entire store
         this._clientInfo = undefined;
         this._tokens = undefined;
+        this._expiresAt = undefined;
         this._codeVerifier = undefined;
         this._tokensLoaded = false;
-        await this._store.clear();
+        await this._store.delete(this._storeKey);
+        if (this._isOAuthStore(this._store)) {
+          await this._store.deleteClient(this._storeKey);
+          await this._store.deleteCodeVerifier(this._storeKey);
+        }
         break;
       case "client":
         this._clientInfo = undefined;
         if (this._isOAuthStore(this._store)) {
-          // Empty clientId signals deletion (OAuthStore has no deleteClient method)
-          await this._store.setClient(this._storeKey, { clientId: "" });
+          await this._store.deleteClient(this._storeKey);
         }
         break;
       case "tokens":
         this._tokens = undefined;
+        this._expiresAt = undefined;
         await this._store.delete(this._storeKey);
         break;
       case "verifier":
         this._codeVerifier = undefined;
         if (this._isOAuthStore(this._store)) {
-          // Empty session signals deletion (OAuthStore has no deleteSession method)
-          await this._store.setSession(this._storeKey, {});
+          await this._store.deleteCodeVerifier(this._storeKey);
         }
         break;
     }
   }
 
+  /** Delegates RFC 8707 resource validation to SDK default behavior. */
   async validateResourceURL(
     _serverUrl: string | URL,
     _resource?: string,
   ): Promise<URL | undefined> {
     return undefined;
   }
-
-  /**
-   * Retrieves pending auth code from browser callback.
-   * @returns Auth code and state, or undefined if none pending
-   * @sideeffect Marks exchange in progress for invalidate() workaround
-   * @security Single-use: clears code after retrieval
-   */
-  getPendingAuthCode(): { code?: string; state?: string } | undefined {
-    if (this._pendingAuthCode) {
-      const result = {
-        code: this._pendingAuthCode,
-        state: this._pendingAuthState,
-      };
-
-      /** Protect verifier from SDK's invalidate("all") during exchange. */
-      this._isExchangingCode = true;
-
-      this._pendingAuthCode = undefined;
-      this._pendingAuthState = undefined;
-
-      return result;
-    }
-    return undefined;
-  }
-
-  /** SDK constraint: addClientAuthentication() must not exist on this class. */
 }

package/src/index.ts

@@ -10,6 +10,10 @@ import { OAuthError } from "./errors";
 import { createCallbackServer, type CallbackResult } from "./server";
 import type { GetAuthCodeOptions } from "./types";
 
+const DEFAULT_PORT = 3000;
+const DEFAULT_HOSTNAME = "localhost";
+const DEFAULT_CALLBACK_PATH = "/callback";
+
 export type { CallbackResult, CallbackServer, ServerOptions } from "./server";
 export { OAuthError, TimeoutError } from "./errors";
 export type { GetAuthCodeOptions } from "./types";
@@ -44,9 +48,9 @@ export function getRedirectUrl(
   } = {},
 ): string {
   const {
-    port = 3000,
-    hostname = "localhost",
-    callbackPath = "/callback",
+    port = DEFAULT_PORT,
+    hostname = DEFAULT_HOSTNAME,
+    callbackPath = DEFAULT_CALLBACK_PATH,
   } = options;
   return `http://${hostname}:${port}${callbackPath}`;
 }
@@ -94,10 +98,10 @@ export async function getAuthCode(
     typeof input === "string" ? await authorizationUrlToOptions(input) : input;
 
   const {
-    port = 3000,
-    hostname = "localhost",
+    port = DEFAULT_PORT,
+    hostname = DEFAULT_HOSTNAME,
     timeout = 30000,
-    callbackPath = "/callback",
+    callbackPath = DEFAULT_CALLBACK_PATH,
     successHtml,
     errorHtml,
     signal,
@@ -119,10 +123,13 @@ export async function getAuthCode(
     // Best-effort launch: fire-and-forget, swallow errors (managed mode only)
     if (
       "authorizationUrl" in options &&
-      typeof (options as any).launch === "function"
+      options.authorizationUrl &&
+      "launch" in options &&
+      typeof options.launch === "function"
     ) {
-      const { authorizationUrl, launch } = options as any;
-      void Promise.resolve(launch(authorizationUrl)).catch(() => {});
+      void Promise.resolve(options.launch(options.authorizationUrl)).catch(
+        () => {},
+      );
     }
 
     const result = await server.waitForCallback(callbackPath, timeout);

package/src/mcp-types.ts

@@ -23,36 +23,34 @@ export interface ClientInfo {
   clientSecretExpiresAt?: number;
 }
 
-/**
- * Active OAuth flow state for crash recovery.
- * Preserves PKCE verifier and state across process restarts.
- */
-export interface OAuthSession {
-  codeVerifier?: string;
-  state?: string;
-}
-
 /**
  * Minimal storage interface for OAuth tokens.
- * @invariant Implementations must be thread-safe within process.
  * @invariant Keys are scoped to avoid collisions between multiple OAuth flows.
  */
 export interface TokenStore {
   get(key: string): Promise<Tokens | null>;
   set(key: string, tokens: Tokens): Promise<void>;
   delete(key: string): Promise<void>;
-  clear(): Promise<void>;
 }
 
+/** Brand symbol for OAuthStore type detection. */
+export const OAuthStoreBrand: unique symbol = Symbol("OAuthStore");
+
 /**
- * Full OAuth state storage including client registration and session.
- * Enables recovery from crashes mid-flow and reuse of dynamic registration.
+ * Extended storage with client registration and PKCE verifier persistence.
+ * Enables crash recovery mid-flow and reuse of dynamic registration.
+ * @invariant Implementations must include `[OAuthStoreBrand]: true` property.
  */
 export interface OAuthStore extends TokenStore {
+  readonly [OAuthStoreBrand]: true;
+
   getClient(key: string): Promise<ClientInfo | null>;
   setClient(key: string, client: ClientInfo): Promise<void>;
-  getSession(key: string): Promise<OAuthSession | null>;
-  setSession(key: string, session: OAuthSession): Promise<void>;
+  deleteClient(key: string): Promise<void>;
+
+  getCodeVerifier(key: string): Promise<string | null>;
+  setCodeVerifier(key: string, verifier: string): Promise<void>;
+  deleteCodeVerifier(key: string): Promise<void>;
 }
 
 /**
@@ -61,8 +59,16 @@ export interface OAuthStore extends TokenStore {
  * @see https://datatracker.ietf.org/doc/html/rfc8252
  */
 export interface BrowserAuthOptions {
-  /** Pre-registered OAuth client credentials. Omit for dynamic registration. */
+  /**
+   * Pre-registered OAuth client ID. Omit to use dynamic client registration.
+   * When provided, takes precedence over any DCR-obtained client.
+   */
   clientId?: string;
+  /**
+   * Pre-registered client secret (for confidential clients).
+   * Determines auth method for token requests: `client_secret_post` if set, `none` otherwise.
+   * This is fixed at construction - DCR-obtained secrets don't change the auth method.
+   */
   clientSecret?: string;
 
   scope?: string;
@@ -87,4 +93,11 @@ export interface BrowserAuthOptions {
 
   /** Request inspection callback for debugging OAuth flows. */
   onRequest?: (req: Request) => void;
+
+  /**
+   * Authorization server base URL (issuer) for token endpoint discovery.
+   * Pass the origin (e.g., `https://auth.example.com`), not `/token`.
+   * Defaults to the authorization URL origin. Discovery failures are non-fatal.
+   */
+  authServerUrl?: string | URL;
 }

package/src/mcp.ts

@@ -13,11 +13,11 @@ export { browserAuth } from "./auth/browser-auth";
 export { inMemoryStore } from "./storage/memory";
 export { fileStore } from "./storage/file";
 
+export { OAuthStoreBrand } from "./mcp-types";
 export type {
   BrowserAuthOptions,
   Tokens,
   TokenStore,
   ClientInfo,
-  OAuthSession,
   OAuthStore,
 } from "./mcp-types";

package/src/storage/file.ts

@@ -8,8 +8,8 @@ import type { TokenStore, Tokens } from "../mcp-types";
 
 /**
  * Persistent file-based token storage.
+ * Not safe for concurrent access across multiple processes.
  * Default: ~/.mcp/tokens.json
- * WARNING: Not safe for concurrent access across processes.
  */
 export function fileStore(filepath?: string): TokenStore {
   const file = filepath ?? path.join(os.homedir(), ".mcp", "tokens.json");
@@ -29,8 +29,9 @@ export function fileStore(filepath?: string): TokenStore {
 
   async function writeStore(data: Record<string, Tokens>) {
     await ensureDir();
-    // TODO: Atomic write via temp file + rename
-    await fs.writeFile(file, JSON.stringify(data, null, 2), "utf-8");
+    const tmp = `${file}.tmp.${process.pid}`;
+    await fs.writeFile(tmp, JSON.stringify(data, null, 2), "utf-8");
+    await fs.rename(tmp, file);
   }
 
   return {
@@ -50,9 +51,5 @@ export function fileStore(filepath?: string): TokenStore {
       delete store[key];
       await writeStore(store);
     },
-
-    async clear(): Promise<void> {
-      await writeStore({});
-    },
   };
 }

package/src/storage/memory.ts

@@ -5,7 +5,7 @@ import type { TokenStore, Tokens } from "../mcp-types";
 
 /**
  * Ephemeral in-memory token storage.
- * Tokens lost on process restart. Safe for concurrent access within process.
+ * Tokens lost on process restart.
  */
 export function inMemoryStore(): TokenStore {
   const store = new Map<string, Tokens>();
@@ -22,9 +22,5 @@ export function inMemoryStore(): TokenStore {
     async delete(key: string): Promise<void> {
       store.delete(key);
     },
-
-    async clear(): Promise<void> {
-      store.clear();
-    },
   };
 }