oauth-callback 1.2.0 → 1.2.2

package/README.md

@@ -4,6 +4,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/oauth-callback.svg)](https://npmjs.com/package/oauth-callback)
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/kriasoft/oauth-callback/blob/main/LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+[![Run on Replit](https://img.shields.io/badge/Run%20on-Replit-orange.svg)](https://replit.com/@kriasoft/oauth-callback)
 
 A lightweight OAuth 2.0 callback handler for Node.js, Deno, and Bun with built-in browser flow and MCP SDK integration. Perfect for CLI tools, desktop applications, and development environments that need to capture OAuth authorization codes.
 
@@ -16,7 +17,7 @@ A lightweight OAuth 2.0 callback handler for Node.js, Deno, and Bun with built-i
 - 🚀 **Multi-runtime support** - Works with Node.js 18+, Deno, and Bun
 - 🔒 **Secure localhost-only server** for OAuth callbacks
 - 🤖 **MCP SDK integration** - Built-in OAuth provider for Model Context Protocol
-- ⚡ **Minimal dependencies** - Only requires `open` package
+- ⚡ **Single dependency** - Only requires `open` for browser launching
 - 🎯 **TypeScript support** out of the box
 - 🛡️ **Comprehensive OAuth error handling** with detailed error classes
 - 🔄 **Automatic server cleanup** after callback
@@ -106,34 +107,6 @@ const result = await getAuthCode({
 });
 ```
 
-### Handling Different OAuth Providers
-
-```typescript
-// Google OAuth
-const googleAuth = await getAuthCode(
-  "https://accounts.google.com/o/oauth2/v2/auth?" +
-    new URLSearchParams({
-      client_id: process.env.GOOGLE_CLIENT_ID,
-      redirect_uri: "http://localhost:3000/callback",
-      response_type: "code",
-      scope: "openid email profile",
-      access_type: "offline",
-    }),
-);
-
-// Microsoft OAuth
-const microsoftAuth = await getAuthCode(
-  "https://login.microsoftonline.com/common/oauth2/v2.0/authorize?" +
-    new URLSearchParams({
-      client_id: process.env.MICROSOFT_CLIENT_ID,
-      redirect_uri: "http://localhost:3000/callback",
-      response_type: "code",
-      scope: "user.read",
-      response_mode: "query",
-    }),
-);
-```
-
 ### MCP SDK Integration
 
 The `browserAuth()` function provides a drop-in OAuth provider for the Model Context Protocol SDK:
@@ -327,18 +300,30 @@ TokenStore implementation for persistent token storage.
 
 ## How It Works
 
-1. **Server Creation**: Creates a temporary HTTP server on the specified port
-2. **Browser Launch**: Opens the authorization URL in the user's default browser
-3. **Callback Handling**: Waits for the OAuth provider to redirect back with the authorization code
-4. **Cleanup**: Automatically closes the server after receiving the callback
-5. **Result**: Returns the authorization code and any additional parameters
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│  Your App   │────▶│Local Server │────▶│   Browser   │────▶│OAuth Server │
+│             │     │ :3000       │     │             │     │             │
+│ getAuthCode │     │             │◀────│  Callback   │◀────│  Redirect   │
+│     ▼       │◀────│ Returns     │     │ /callback   │     │  with code  │
+│   {code}    │     │ auth code   │     │             │     │             │
+└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
+```
+
+1. **Server Creation** — Spins up a temporary localhost HTTP server
+2. **Browser Launch** — Opens the authorization URL in the default browser
+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
 
 ## Security Considerations
 
-- The server only accepts connections from localhost
-- Server is closed immediately after receiving the callback
-- No data is stored persistently
-- State parameter validation should be implemented by the application
+- **Localhost-only binding** — Server rejects non-local connections
+- **Ephemeral server** — Shuts down immediately after receiving the callback
+- **No credential logging** — Tokens and codes are never written to logs
+- **State parameter support** — Pass and validate state to prevent CSRF attacks
+- **Configurable timeouts** — Server auto-terminates if callback isn't received
+- **PKCE compatible** — Works with authorization servers that require PKCE
 
 ## Running the Examples
 
@@ -413,6 +398,9 @@ bun test
 # Build
 bun run build
 
+# Run documentation locally
+bun run docs:dev        # Start VitePress dev server at http://localhost:5173
+
 # Run examples
 bun run example:demo    # Interactive demo
 bun run example:github  # GitHub OAuth example

package/dist/error.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=error.test.d.ts.map

package/dist/error.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.test.d.ts","sourceRoot":"","sources":["../src/error.test.ts"],"names":[],"mappings":""}