oauth-callback 1.2.5 → 2.1.0

package/README.md

@@ -31,33 +31,38 @@ A lightweight OAuth 2.0 callback handler for Node.js, Deno, and Bun with built-i
 ## Installation
 
 ```bash
-bun add oauth-callback
+bun add oauth-callback open
 ```
 
 Or with npm:
 
 ```bash
-npm install oauth-callback
+npm install oauth-callback open
 ```
 
+> **Note:** The `open` package is optional but recommended for browser launching. If using pnpm, install it explicitly: `pnpm add open`
+
 ## Quick Start
 
 ```typescript
+import open from "open";
 import { getAuthCode, OAuthError } from "oauth-callback";
 
-// Simple usage
-const result = await getAuthCode(
-  "https://example.com/oauth/authorize?client_id=xxx&redirect_uri=http://localhost:3000/callback",
-);
+// Simple usage - pass `open` to launch browser
+const result = await getAuthCode({
+  authorizationUrl:
+    "https://example.com/oauth/authorize?client_id=xxx&redirect_uri=http://localhost:3000/callback",
+  launch: open,
+});
 console.log("Authorization code:", result.code);
 
 // MCP SDK integration - use specific import
 import { browserAuth, fileStore } from "oauth-callback/mcp";
-const authProvider = browserAuth({ store: fileStore() });
+const authProvider = browserAuth({ launch: open, store: fileStore() });
 
 // Or via namespace import
 import { mcp } from "oauth-callback";
-const authProvider = mcp.browserAuth({ store: mcp.fileStore() });
+const authProvider = mcp.browserAuth({ launch: open, store: mcp.fileStore() });
 ```
 
 ## Usage Examples
@@ -65,6 +70,7 @@ const authProvider = mcp.browserAuth({ store: mcp.fileStore() });
 ### Basic OAuth Flow
 
 ```typescript
+import open from "open";
 import { getAuthCode, OAuthError } from "oauth-callback";
 
 async function authenticate() {
@@ -78,7 +84,10 @@ async function authenticate() {
     });
 
   try {
-    const result = await getAuthCode(authUrl);
+    const result = await getAuthCode({
+      authorizationUrl: authUrl,
+      launch: open,
+    });
     console.log("Authorization code:", result.code);
     console.log("State:", result.state);
 
@@ -98,10 +107,12 @@ async function authenticate() {
 ### Custom Port Configuration
 
 ```typescript
+import open from "open";
 import { getAuthCode } from "oauth-callback";
 
 const result = await getAuthCode({
   authorizationUrl: authUrl,
+  launch: open,
   port: 8080, // Use custom port (default: 3000)
   timeout: 60000, // Custom timeout in ms (default: 30000)
 });
@@ -120,6 +131,7 @@ import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/
 const authProvider = browserAuth({
   port: 3000,
   scope: "read write",
+  launch: open, // Opens browser for OAuth consent
   store: inMemoryStore(), // Or fileStore() for persistence
 });
 
@@ -144,17 +156,20 @@ import { browserAuth, inMemoryStore, fileStore } from "oauth-callback/mcp";
 
 // Ephemeral storage (tokens lost on restart)
 const ephemeralAuth = browserAuth({
+  launch: open,
   store: inMemoryStore(),
 });
 
 // Persistent file storage (default: ~/.mcp/tokens.json)
 const persistentAuth = browserAuth({
+  launch: open,
   store: fileStore(),
   storeKey: "my-app-tokens", // Namespace for multiple apps
 });
 
 // Custom file location
 const customAuth = browserAuth({
+  launch: open,
   store: fileStore("/path/to/tokens.json"),
 });
 ```
@@ -168,6 +183,7 @@ const authProvider = browserAuth({
   clientId: "your-client-id",
   clientSecret: "your-client-secret",
   scope: "read write",
+  launch: open, // Opens browser for OAuth consent
   store: fileStore(), // Persist tokens across sessions
 });
 ```
@@ -175,9 +191,12 @@ const authProvider = browserAuth({
 ### Advanced Usage
 
 ```typescript
+import open from "open";
+
 // With custom HTML templates and logging
 const result = await getAuthCode({
   authorizationUrl: authUrl,
+  launch: open,
   port: 3000,
   hostname: "127.0.0.1", // Bind to specific IP
   successHtml: "<h1>Success! You can close this window.</h1>",
@@ -209,7 +228,7 @@ try {
 
 ### `getAuthCode(input)`
 
-Starts a local HTTP server and opens the authorization URL in the user's browser.
+Starts a local HTTP server to capture OAuth callbacks. Optionally launches the authorization URL via the `launch` callback.
 
 #### Parameters
 
@@ -219,7 +238,7 @@ Starts a local HTTP server and opens the authorization URL in the user's browser
   - `hostname` (string): Hostname to bind the server to (default: "localhost")
   - `callbackPath` (string): URL path for the OAuth callback (default: "/callback")
   - `timeout` (number): Timeout in milliseconds (default: 30000)
-  - `openBrowser` (boolean): Whether to open browser automatically (default: true)
+  - `launch` (function): Optional callback to launch the authorization URL (e.g., `open`)
   - `successHtml` (string): Custom HTML to display on successful authorization
   - `errorHtml` (string): Custom HTML to display on authorization error
   - `signal` (AbortSignal): AbortSignal for cancellation support
@@ -269,6 +288,7 @@ Available from `oauth-callback/mcp`. Creates an MCP SDK-compatible OAuth provide
   - `clientSecret` (string): Pre-registered client secret (optional)
   - `store` (TokenStore): Token storage implementation (default: inMemoryStore())
   - `storeKey` (string): Storage key for tokens (default: "mcp-tokens")
+  - `launch` (function): Callback to launch auth URL (e.g., `open`)
   - `authTimeout` (number): Authorization timeout in ms (default: 300000)
   - `successHtml` (string): Custom success page HTML
   - `errorHtml` (string): Custom error page HTML
@@ -311,7 +331,7 @@ TokenStore implementation for persistent token storage.
 ```
 
 1. **Server Creation** — Spins up a temporary localhost HTTP server
-2. **Browser Launch** — Opens the authorization URL in the default browser
+2. **Browser Launch** — Opens the authorization URL (if `launch` callback provided)
 3. **User Authorization** — User grants permission on the OAuth provider's page
 4. **Callback Capture** — Provider redirects to localhost with the authorization code
 5. **Cleanup** — Server closes automatically, code is returned to your app
@@ -420,7 +440,11 @@ bun run example:notion  # Notion MCP example with Dynamic Client Registration
 If port 3000 is already in use, specify a different port:
 
 ```typescript
-const result = await getAuthCode({ authorizationUrl: authUrl, port: 8080 });
+const result = await getAuthCode({
+  authorizationUrl: authUrl,
+  launch: open,
+  port: 8080,
+});
 ```
 
 ### Firewall Warnings
@@ -433,13 +457,9 @@ If the browser doesn't open automatically, manually navigate to the authorizatio
 
 ## Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+Contributions are welcome! See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for setup instructions.
 
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add some amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
+**Maintainers wanted** — we're looking for people to help maintain this project. If interested, reach out on [Discord](https://discord.gg/bSsv7XM) or open an issue.
 
 ## License
 

package/dist/auth/browser-auth.d.ts

@@ -8,9 +8,11 @@ import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.
  *
  * @example
  * ```typescript
+ * import open from "open";
+ *
  * const transport = new StreamableHTTPClientTransport(
  *   new URL("https://mcp.notion.com/mcp"),
- *   { authProvider: browserAuth() }
+ *   { authProvider: browserAuth({ launch: open }) }
  * );
  * ```
  */

package/dist/auth/browser-auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser-auth.d.ts","sourceRoot":"","sources":["../../src/auth/browser-auth.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,kBAAkB,EAMnB,MAAM,cAAc,CAAC;AAKtB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0CAA0C,CAAC;AAQpF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CACzB,OAAO,GAAE,kBAAuB,GAC/B,mBAAmB,CAErB"}
+{"version":3,"file":"browser-auth.d.ts","sourceRoot":"","sources":["../../src/auth/browser-auth.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,kBAAkB,EAMnB,MAAM,cAAc,CAAC;AAItB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0CAA0C,CAAC;AAQpF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CACzB,OAAO,GAAE,kBAAuB,GAC/B,mBAAmB,CAErB"}

package/dist/index.d.ts

@@ -1,34 +1,58 @@
 import { 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";
 export { inMemoryStore } from "./storage/memory";
 export { fileStore } from "./storage/file";
 import * as mcp from "./mcp";
 export { mcp };
+/**
+ * Builds the redirect URI for OAuth configuration.
+ * Use this to construct the redirect_uri parameter for your authorization URL.
+ *
+ * @example
+ * ```typescript
+ * const redirectUri = getRedirectUrl({ port: 3000 });
+ * // => "http://localhost:3000/callback"
+ *
+ * const authUrl = `https://oauth.example.com/authorize?redirect_uri=${encodeURIComponent(redirectUri)}`;
+ * console.log('Open:', authUrl);
+ * await getAuthCode({ port: 3000 });
+ * ```
+ */
+export declare function getRedirectUrl(options?: {
+    port?: number;
+    hostname?: string;
+    callbackPath?: string;
+}): string;
 /**
  * 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
+ * Two modes:
+ * - **Managed**: Pass both `authorizationUrl` and `launch` — library opens browser
+ * - **Headless**: Pass neither — caller handles URL display (CI/SSH/custom UI)
+ *
+ * @param input - Auth URL string (auto-launches browser) or GetAuthCodeOptions
  * @returns Promise<CallbackResult> with code and params
  * @throws {OAuthError} Provider errors (access_denied, invalid_scope)
  * @throws {Error} Timeout, network failures, port conflicts
  *
  * @example
  * ```typescript
- * // Simple
- * const result = await getAuthCode('https://oauth.example.com/authorize?...');
- * console.log('Code:', result.code);
+ * import open from "open";
  *
- * // Custom port/timeout
+ * // Managed mode: library launches browser
  * const result = await getAuthCode({
  *   authorizationUrl: 'https://oauth.example.com/authorize?...',
- *   port: 8080,
- *   timeout: 60000,
- *   onRequest: (req) => console.log('Request:', req.url)
+ *   launch: open,
  * });
+ *
+ * // Headless mode: caller handles URL display
+ * const authUrl = 'https://oauth.example.com/authorize?...';
+ * console.log('Open this URL:', authUrl);
+ * const result = await getAuthCode({ port: 3000, timeout: 60000 });
  * ```
  */
 export declare function getAuthCode(input: GetAuthCodeOptions | string): Promise<CallbackResult>;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAUA,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,UAAU,CAAC;AACrE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAElD,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC9E,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,YAAY,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAGlD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAG3C,OAAO,KAAK,GAAG,MAAM,OAAO,CAAC;AAC7B,OAAO,EAAE,GAAG,EAAE,CAAC;AAEf;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,kBAAkB,GAAG,MAAM,GACjC,OAAO,CAAC,cAAc,CAAC,CA8DzB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,UAAU,CAAC;AACrE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAElD,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC9E,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACpD,YAAY,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAGlD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAG3C,OAAO,KAAK,GAAG,MAAM,OAAO,CAAC;AAC7B,OAAO,EAAE,GAAG,EAAE,CAAC;AAEf;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAC5B,OAAO,GAAE;IACP,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CAClB,GACL,MAAM,CAOR;AASD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,kBAAkB,GAAG,MAAM,GACjC,OAAO,CAAC,cAAc,CAAC,CAmDzB"}