oauth-callback 1.2.5 → 2.0.0

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,4CAA4C;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mHAAmH;IACnH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,oFAAoF;IACpF,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,mDAAmD;IACnD,KAAK,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,iEAAiE;IACjE,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACxE,4CAA4C;IAC5C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AA8RD;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,cAAc,CAKrD"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,4CAA4C;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mHAAmH;IACnH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,oFAAoF;IACpF,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,mDAAmD;IACnD,KAAK,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,iEAAiE;IACjE,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACxE,4CAA4C;IAC5C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAsRD;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,cAAc,CAKrD"}

package/dist/types.d.ts

@@ -27,16 +27,25 @@ export interface GetAuthCodeOptions {
     callbackPath?: string;
     /**
      * Timeout in milliseconds to wait for OAuth callback.
-     * If no callback is received within this time, the operation will fail.
+     * Starts when the callback server is ready; launch timing does not delay it.
      * @default 30000
      */
     timeout?: number;
     /**
-     * Whether to automatically open the authorization URL in the user's default browser.
-     * Set to false for testing or when you want to handle browser opening manually.
-     * @default true
+     * Optional callback to launch the authorization URL.
+     * Called after the callback server starts, best-effort (errors are swallowed).
+     * If omitted, the library does nothing — caller is responsible for opening the URL.
+     *
+     * Returns `unknown` (not `void`) to accept any launcher without casting—e.g.,
+     * the `open` package returns `Promise<ChildProcess>`. Return value is ignored.
+     *
+     * @example
+     * ```typescript
+     * import open from "open";
+     * await getAuthCode({ authorizationUrl: url, launch: open });
+     * ```
      */
-    openBrowser?: boolean;
+    launch?: (url: string) => unknown;
     /**
      * Custom HTML content to display when authorization is successful.
      * If not provided, a default success page with auto-close functionality is used.

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,gBAAgB,EAAE,MAAM,CAAC;IAEzB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IAErB;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;CACpC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,gBAAgB,EAAE,MAAM,CAAC;IAEzB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IAElC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IAErB;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;CACpC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oauth-callback",
-  "version": "1.2.5",
+  "version": "2.0.0",
   "description": "Lightweight OAuth 2.0 callback handler for Node.js, Deno, and Bun with built-in browser flow and MCP SDK integration",
   "keywords": [
     "oauth",
@@ -52,6 +52,10 @@
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -63,9 +67,6 @@
     },
     "./package.json": "./package.json"
   },
-  "dependencies": {
-    "open": "^11.0.0"
-  },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": ">=1.17.0 <2",
     "typescript": ">=5 <6"
@@ -79,17 +80,18 @@
     }
   },
   "devDependencies": {
-    "@modelcontextprotocol/sdk": "^1.25.2",
+    "@modelcontextprotocol/sdk": "^1.25.3",
+    "open": "^11.0.0",
     "@types/bun": "^1.3.6",
     "@types/deno": "^2.5.0",
-    "@types/node": "^24.10.9",
-    "@types/open": "^6.2.1",
+    "@types/node": "^25.0.10",
     "bun-types": "^1.2.20",
     "mermaid": "^11.12.2",
-    "prettier": "^3.8.0",
-    "publint": "^0.3.16",
+    "prettier": "^3.8.1",
+    "publint": "^0.3.17",
+    "srcpack": "^0.1.13",
     "typescript": "^5.9.3",
-    "vitepress": "^1.6.4",
+    "vitepress": "^2.0.0-alpha.15",
     "vitepress-plugin-mermaid": "^2.0.17"
   },
   "prettier": {
@@ -118,6 +120,6 @@
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
     "docs:preview": "vitepress preview docs",
-    "docs:publish": "bunx gh-pages -d docs/.vitepress/dist"
+    "docs:deploy": "bunx gh-pages -d docs/.vitepress/dist"
   }
 }

package/src/auth/browser-auth.ts

@@ -13,7 +13,6 @@ import type {
 import { calculateExpiry } from "../utils/token";
 import { inMemoryStore } from "../storage/memory";
 import { getAuthCode } from "../index";
-import { OAuthError } from "../errors";
 import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
 import type {
   OAuthClientInformation,
@@ -30,9 +29,11 @@ import type {
  *
  * @example
  * ```typescript
+ * import open from "open";
+ *
  * const transport = new StreamableHTTPClientTransport(
  *   new URL("https://mcp.notion.com/mcp"),
- *   { authProvider: browserAuth() }
+ *   { authProvider: browserAuth({ launch: open }) }
  * );
  * ```
  */
@@ -44,6 +45,7 @@ export function browserAuth(
 
 /**
  * Browser-based OAuth provider for MCP SDK.
+ * @invariant PKCE is always enabled (SDK calls saveCodeVerifier/codeVerifier).
  * @invariant addClientAuthentication() must remain undefined (SDK constraint).
  * @invariant Concurrent auth/refresh attempts are serialized.
  */
@@ -54,8 +56,7 @@ class BrowserOAuthProvider implements OAuthClientProvider {
   private readonly _hostname: string;
   private readonly _callbackPath: string;
   private readonly _authTimeout: number;
-  private readonly _usePKCE: boolean;
-  private readonly _openBrowser: boolean | string;
+  private readonly _launch?: (url: string) => unknown;
   private readonly _clientId?: string;
   private readonly _clientSecret?: string;
   private readonly _scope?: string;
@@ -73,7 +74,6 @@ class BrowserOAuthProvider implements OAuthClientProvider {
   private _tokensLoaded = false;
   private _loadingTokens?: Promise<void>;
   private _authInProgress?: Promise<void>;
-  private _refreshInProgress?: Promise<void>;
 
   constructor(options: BrowserAuthOptions = {}) {
     this._store = options.store ?? inMemoryStore();
@@ -82,9 +82,7 @@ class BrowserOAuthProvider implements OAuthClientProvider {
     this._hostname = options.hostname ?? "localhost";
     this._callbackPath = options.callbackPath ?? "/callback";
     this._authTimeout = options.authTimeout ?? 300000;
-    this._usePKCE = options.usePKCE ?? true;
-    this._openBrowser = options.openBrowser ?? true;
-
+    this._launch = options.launch;
     this._clientId = options.clientId;
     this._clientSecret = options.clientSecret;
     this._scope = options.scope;
@@ -123,7 +121,7 @@ class BrowserOAuthProvider implements OAuthClientProvider {
       // Load client info if using extended store
       if (this._isOAuthStore(this._store)) {
         const clientInfo = await this._store.getClient(this._storeKey);
-        if (clientInfo) {
+        if (clientInfo?.clientId) {
           this._clientInfo = {
             client_id: clientInfo.clientId,
             client_secret: clientInfo.clientSecret,
@@ -135,20 +133,24 @@ class BrowserOAuthProvider implements OAuthClientProvider {
 
         // Load session state
         const session = await this._store.getSession(this._storeKey);
-        if (session) {
+        if (session?.codeVerifier) {
           this._codeVerifier = session.codeVerifier;
         }
       }
 
       this._tokensLoaded = true;
-    } catch (error) {
-      console.warn("Failed to load stored data:", error);
+    } catch {
+      // Ignore store errors; fallback to fresh auth
       this._tokensLoaded = true;
     }
   }
 
   private _isOAuthStore(store: any): store is OAuthStore {
-    return typeof store.getClient === "function";
+    return (
+      typeof store.getClient === "function" &&
+      typeof store.setClient === "function" &&
+      typeof store.getSession === "function"
+    );
   }
 
   get redirectUrl(): string {
@@ -218,20 +220,9 @@ class BrowserOAuthProvider implements OAuthClientProvider {
 
     // Check expiry using stored expiresAt from initial token response
     const stored = await this._store.get(this._storeKey);
-    if (stored?.expiresAt) {
-      if (Date.now() >= stored.expiresAt - 60000) {
-        // Expired with 60s buffer
-        if (this._tokens.refresh_token) {
-          try {
-            await this._refreshTokens();
-            return this._tokens;
-          } catch (error) {
-            console.warn("Token refresh failed:", error);
-            return undefined;
-          }
-        }
-        return undefined;
-      }
+    if (stored?.expiresAt && Date.now() >= stored.expiresAt - 60000) {
+      // Token expired (with 60s buffer). Refresh not yet implemented — trigger re-auth.
+      return undefined;
     }
 
     return this._tokens;
@@ -269,59 +260,29 @@ class BrowserOAuthProvider implements OAuthClientProvider {
   }
 
   private async _doAuthorization(authorizationUrl: URL): Promise<void> {
-    let lastError: Error | undefined;
-    const maxRetries = 2;
-
-    for (let attempt = 0; attempt <= maxRetries; attempt++) {
-      try {
-        const result = await getAuthCode({
-          authorizationUrl: authorizationUrl.href,
-          port: this._port,
-          hostname: this._hostname,
-          callbackPath: this._callbackPath,
-          timeout: this._authTimeout,
-          openBrowser:
-            typeof this._openBrowser === "boolean" ? this._openBrowser : true,
-          successHtml: this._successHtml,
-          errorHtml: this._errorHtml,
-          onRequest: this._onRequest,
-        });
-
-        /** Cache auth code for SDK's separate token exchange call. */
-        this._pendingAuthCode = result.code;
-        this._pendingAuthState = result.state;
-
-        /** Auto-cleanup stale auth codes after timeout to prevent leaks. */
-        setTimeout(() => {
-          if (this._pendingAuthCode === result.code) {
-            this._pendingAuthCode = undefined;
-            this._pendingAuthState = undefined;
-          }
-        }, this._authTimeout);
-
-        return;
-      } catch (error) {
-        lastError = error instanceof Error ? error : new Error(String(error));
-
-        if (error instanceof OAuthError) {
-          throw error; // OAuth errors are user-actionable, don't retry
-        }
-
-        if (attempt < maxRetries) {
-          console.warn(
-            `Auth attempt ${attempt + 1} failed, retrying...`,
-            error,
-          );
-          await new Promise((resolve) =>
-            setTimeout(resolve, 1000 * (attempt + 1)),
-          );
-        }
+    const result = await getAuthCode({
+      authorizationUrl: authorizationUrl.href,
+      port: this._port,
+      hostname: this._hostname,
+      callbackPath: this._callbackPath,
+      timeout: this._authTimeout,
+      launch: this._launch,
+      successHtml: this._successHtml,
+      errorHtml: this._errorHtml,
+      onRequest: this._onRequest,
+    });
+
+    /** Cache auth code for SDK's separate token exchange call. */
+    this._pendingAuthCode = result.code;
+    this._pendingAuthState = result.state;
+
+    /** Auto-cleanup stale auth codes after timeout to prevent leaks. */
+    setTimeout(() => {
+      if (this._pendingAuthCode === result.code) {
+        this._pendingAuthCode = undefined;
+        this._pendingAuthState = undefined;
       }
-    }
-
-    throw new Error(
-      `OAuth authorization failed after ${maxRetries + 1} attempts: ${lastError?.message}`,
-    );
+    }, this._authTimeout);
   }
 
   async saveCodeVerifier(codeVerifier: string): Promise<void> {
@@ -348,8 +309,18 @@ class BrowserOAuthProvider implements OAuthClientProvider {
     scope: "all" | "client" | "tokens" | "verifier",
   ): Promise<void> {
     /**
-     * WORKAROUND: SDK calls invalidate("all") during token exchange.
-     * Must preserve client info and verifier until exchange completes.
+     * 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. */
@@ -373,9 +344,8 @@ class BrowserOAuthProvider implements OAuthClientProvider {
       case "client":
         this._clientInfo = undefined;
         if (this._isOAuthStore(this._store)) {
-          await this._store.setClient(this._storeKey, {
-            clientId: "",
-          });
+          // Empty clientId signals deletion (OAuthStore has no deleteClient method)
+          await this._store.setClient(this._storeKey, { clientId: "" });
         }
         break;
       case "tokens":
@@ -385,6 +355,7 @@ class BrowserOAuthProvider implements OAuthClientProvider {
       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, {});
         }
         break;
@@ -411,7 +382,7 @@ class BrowserOAuthProvider implements OAuthClientProvider {
         state: this._pendingAuthState,
       };
 
-      /** Signal token exchange to protect state in invalidateCredentials(). */
+      /** Protect verifier from SDK's invalidate("all") during exchange. */
       this._isExchangingCode = true;
 
       this._pendingAuthCode = undefined;
@@ -422,36 +393,5 @@ class BrowserOAuthProvider implements OAuthClientProvider {
     return undefined;
   }
 
-  private async _refreshTokens(): Promise<void> {
-    /** Serialize refresh attempts to prevent token corruption. */
-    if (this._refreshInProgress) {
-      await this._refreshInProgress;
-      return;
-    }
-
-    this._refreshInProgress = this._doRefreshTokens();
-    try {
-      await this._refreshInProgress;
-    } finally {
-      this._refreshInProgress = undefined;
-    }
-  }
-
-  private async _doRefreshTokens(): Promise<void> {
-    if (!this._tokens?.refresh_token) {
-      throw new Error("No refresh token available");
-    }
-
-    const clientInfo = await this.clientInformation();
-    if (!clientInfo?.client_id) {
-      throw new Error("No client information available for refresh");
-    }
-
-    /** TODO: Implement refresh when token endpoint URL is available from server metadata. */
-    throw new Error(
-      "Token refresh not yet implemented - requires token endpoint URL",
-    );
-  }
-
   /** SDK constraint: addClientAuthentication() must not exist on this class. */
 }

package/src/index.ts

@@ -6,13 +6,12 @@
  * Creates a temporary localhost server to capture OAuth callbacks for CLI/desktop apps.
  */
 
-import open from "open";
 import { OAuthError } from "./errors";
 import { createCallbackServer, type CallbackResult } from "./server";
 import type { GetAuthCodeOptions } from "./types";
 
 export type { CallbackResult, CallbackServer, ServerOptions } from "./server";
-export { OAuthError } from "./errors";
+export { OAuthError, TimeoutError } from "./errors";
 export type { GetAuthCodeOptions } from "./types";
 
 // Storage implementations (backward compatibility)
@@ -25,7 +24,7 @@ export { mcp };
 
 /**
  * Captures OAuth authorization code via localhost callback.
- * Opens browser to auth URL, waits for provider redirect to localhost.
+ * Starts a temporary server, optionally launches auth URL, waits for redirect.
  *
  * @param input - Auth URL string or GetAuthCodeOptions with config
  * @returns Promise<CallbackResult> with code and params
@@ -34,17 +33,18 @@ export { mcp };
  *
  * @example
  * ```typescript
- * // Simple
- * const result = await getAuthCode('https://oauth.example.com/authorize?...');
- * console.log('Code:', result.code);
+ * import open from "open";
  *
- * // Custom port/timeout
+ * // With browser launch
  * const result = await getAuthCode({
  *   authorizationUrl: 'https://oauth.example.com/authorize?...',
- *   port: 8080,
- *   timeout: 60000,
- *   onRequest: (req) => console.log('Request:', req.url)
+ *   launch: open,
  * });
+ *
+ * // Headless (print URL, let user open manually)
+ * const url = 'https://oauth.example.com/authorize?...';
+ * console.log('Open:', url);
+ * const result = await getAuthCode({ authorizationUrl: url });
  * ```
  */
 export async function getAuthCode(
@@ -57,13 +57,13 @@ export async function getAuthCode(
     authorizationUrl,
     port = 3000,
     hostname = "localhost",
-    openBrowser = true,
     timeout = 30000,
     callbackPath = "/callback",
     successHtml,
     errorHtml,
     signal,
     onRequest,
+    launch,
   } = options;
 
   const server = createCallbackServer();
@@ -78,23 +78,8 @@ export async function getAuthCode(
       onRequest,
     });
 
-    if (openBrowser) {
-      await open(authorizationUrl);
-    } else {
-      // Test mode: trigger mock provider redirect without browser
-      fetch(authorizationUrl)
-        .then(async (response) => {
-          if (response.status === 302 || response.status === 301) {
-            const location = response.headers.get("Location");
-            if (location) {
-              await fetch(location);
-            }
-          }
-        })
-        .catch(() => {
-          // Ignore - tests may lack mock provider
-        });
-    }
+    // Best-effort launch: fire-and-forget, swallow errors
+    if (launch) void Promise.resolve(launch(authorizationUrl)).catch(() => {});
 
     const result = await server.waitForCallback(callbackPath, timeout);
 

package/src/mcp-types.ts

@@ -73,14 +73,14 @@ export interface BrowserAuthOptions {
   callbackPath?: string; // Default: "/callback"
 
   store?: TokenStore; // Default: in-memory (lost on restart). Use OAuthStore for persistence.
-  storeKey?: string; // Storage key prefix. Default: "mcp-tokens"
+  storeKey?: string; // Storage key for token isolation. Default: "mcp-tokens"
 
-  openBrowser?: boolean | string; // Default: true. Set false for headless/CI environments.
+  /** Callback to launch the authorization URL. Omit for headless mode.
+   * Returns `unknown` to accept any launcher (e.g., `open` → `Promise<ChildProcess>`). */
+  launch?: (url: string) => unknown;
 
   authTimeout?: number; // Max wait for user authorization. Default: 300000ms (5 min)
 
-  usePKCE?: boolean; // Enable PKCE (RFC 7636). Default: true. Required for public clients.
-
   /** Custom HTML templates for callback pages. Supports {{placeholders}}. */
   successHtml?: string;
   errorHtml?: string;

package/src/server.ts

@@ -7,6 +7,7 @@
 
 import type { Server as HttpServer } from "node:http";
 import type { IncomingMessage } from "node:http";
+import { TimeoutError } from "./errors";
 import { successTemplate, renderError } from "./templates";
 
 /**
@@ -161,36 +162,36 @@ abstract class BaseCallbackServer implements CallbackServer {
     path: string,
     timeout: number,
   ): Promise<CallbackResult> {
-    if (this.callbackListeners.has(path))
+    if (!path) throw new Error("Callback path is required");
+    const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+
+    if (this.callbackListeners.has(normalizedPath))
       return Promise.reject(
-        new Error(`A listener for the path "${path}" is already active.`),
+        new Error(
+          `A listener for the path "${normalizedPath}" is already active.`,
+        ),
       );
 
     let timeoutId: ReturnType<typeof setTimeout> | undefined;
 
     try {
-      // Race a promise that waits for the callback against a promise that rejects on timeout.
       return await Promise.race([
-        // This promise is resolved or rejected by the handleRequest method.
         new Promise<CallbackResult>((resolve, reject) => {
-          this.callbackListeners.set(path, { resolve, reject });
+          this.callbackListeners.set(normalizedPath, { resolve, reject });
         }),
-        // This promise rejects after the specified timeout.
         new Promise<CallbackResult>((_, reject) => {
           timeoutId = setTimeout(() => {
             reject(
-              new Error(
-                `OAuth callback timeout after ${timeout}ms waiting for ${path}`,
+              new TimeoutError(
+                `OAuth callback timeout after ${timeout}ms waiting for ${normalizedPath}`,
               ),
             );
           }, timeout);
         }),
       ]);
     } finally {
-      // CRITICAL: Always clean up the listener and timeout to prevent memory leaks
-      // and allow the process to exit cleanly.
       if (timeoutId) clearTimeout(timeoutId);
-      this.callbackListeners.delete(path);
+      this.callbackListeners.delete(normalizedPath);
     }
   }
 
@@ -250,11 +251,6 @@ class DenoCallbackServer extends BaseCallbackServer {
     const { port, hostname = "localhost" } = options;
     this.abortController = new AbortController();
 
-    // The user's signal will abort our internal controller.
-    options.signal?.addEventListener("abort", () =>
-      this.abortController?.abort(),
-    );
-
     Deno.serve(
       { port, hostname, signal: this.abortController.signal },
       (request: Request) => this.handleRequest(request),
@@ -285,22 +281,20 @@ class NodeCallbackServer extends BaseCallbackServer {
           const request = this.nodeToWebRequest(req, port, hostname);
           const response = this.handleRequest(request);
 
+          res.shouldKeepAlive = false;
+
           res.writeHead(
             response.status,
             Object.fromEntries(response.headers.entries()),
           );
           const body = await response.text();
           res.end(body);
-        } catch (error) {
+        } catch {
           res.writeHead(500);
           res.end("Internal Server Error");
         }
       });
 
-      // Tie server closing to the abort signal if provided.
-      if (options.signal)
-        options.signal.addEventListener("abort", () => this.server?.close());
-
       this.server.listen(port, hostname, () => resolve());
       this.server.on("error", reject);
     });
@@ -308,7 +302,6 @@ class NodeCallbackServer extends BaseCallbackServer {
 
   protected async stopServer(): Promise<void> {
     if (!this.server) return;
-    this.server.closeAllConnections();
     return new Promise((resolve) => {
       this.server?.close(() => {
         this.server = undefined;

package/src/types.ts

@@ -34,17 +34,26 @@ export interface GetAuthCodeOptions {
 
   /**
    * Timeout in milliseconds to wait for OAuth callback.
-   * If no callback is received within this time, the operation will fail.
+   * Starts when the callback server is ready; launch timing does not delay it.
    * @default 30000
    */
   timeout?: number;
 
   /**
-   * Whether to automatically open the authorization URL in the user's default browser.
-   * Set to false for testing or when you want to handle browser opening manually.
-   * @default true
+   * Optional callback to launch the authorization URL.
+   * Called after the callback server starts, best-effort (errors are swallowed).
+   * If omitted, the library does nothing — caller is responsible for opening the URL.
+   *
+   * Returns `unknown` (not `void`) to accept any launcher without casting—e.g.,
+   * the `open` package returns `Promise<ChildProcess>`. Return value is ignored.
+   *
+   * @example
+   * ```typescript
+   * import open from "open";
+   * await getAuthCode({ authorizationUrl: url, launch: open });
+   * ```
    */
-  openBrowser?: boolean;
+  launch?: (url: string) => unknown;
 
   /**
    * Custom HTML content to display when authorization is successful.