oauth-callback 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present Konstantin Tarkus, Kriasoft
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,231 @@
+# OAuth Callback Server
+
+A lightweight local HTTP server for handling OAuth 2.0 authorization callbacks in Node.js/Bun applications. Perfect for CLI tools, desktop applications, and development environments that need to capture OAuth authorization codes.
+
+## Features
+
+- 🚀 Simple async/await API
+- 🔒 Secure local server for OAuth callbacks
+- ⚡ Zero dependencies (when using Bun)
+- 🎯 TypeScript support out of the box
+- 🛡️ Built-in error handling for OAuth errors
+- 🔄 Automatic server cleanup after callback
+- 📱 Cross-platform support (Windows, macOS, Linux)
+
+## Installation
+
+```bash
+bun add oauth-callback
+```
+
+Or with npm:
+
+```bash
+npm install oauth-callback
+```
+
+## Quick Start
+
+```typescript
+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",
+);
+console.log("Authorization code:", result.code);
+```
+
+## Usage Examples
+
+### Basic OAuth Flow
+
+```typescript
+import { getAuthCode, OAuthError } from "oauth-callback";
+
+async function authenticate() {
+  const authUrl =
+    "https://github.com/login/oauth/authorize?" +
+    new URLSearchParams({
+      client_id: "your_client_id",
+      redirect_uri: "http://localhost:3000/callback",
+      scope: "user:email",
+      state: "random_state_string",
+    });
+
+  try {
+    const result = await getAuthCode(authUrl);
+    console.log("Authorization code:", result.code);
+    console.log("State:", result.state);
+
+    // Exchange code for access token
+    // ... your token exchange logic here
+  } catch (error) {
+    if (error instanceof OAuthError) {
+      console.error("OAuth error:", error.error);
+      console.error("Description:", error.error_description);
+    } else {
+      console.error("Unexpected error:", error);
+    }
+  }
+}
+```
+
+### Custom Port Configuration
+
+```typescript
+import { getAuthCode } from "oauth-callback";
+
+const result = await getAuthCode(authUrl, {
+  port: 8080, // Use custom port (default: 3000)
+  timeout: 60000, // Custom timeout in ms (default: 30000)
+});
+```
+
+### 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",
+    }),
+);
+```
+
+## API Reference
+
+### `getAuthCode(authUrl, options?)`
+
+Starts a local HTTP server and opens the authorization URL in the user's browser.
+
+#### Parameters
+
+- `authUrl` (string): The OAuth authorization URL
+- `options` (object, optional):
+  - `port` (number): Port for the local server (default: 3000)
+  - `timeout` (number): Timeout in milliseconds (default: 30000)
+  - `callbackPath` (string): Callback path (default: "/callback")
+  - `successMessage` (string): Message shown on successful authorization
+  - `errorMessage` (string): Message shown on authorization error
+
+#### Returns
+
+Promise that resolves to:
+
+```typescript
+{
+  code: string;        // Authorization code
+  state?: string;      // State parameter (if provided)
+  [key: string]: any;  // Additional query parameters
+}
+```
+
+#### Throws
+
+- `OAuthError`: When the OAuth provider returns an error
+- `TimeoutError`: When the authorization times out
+- `Error`: For other unexpected errors
+
+### `OAuthError`
+
+Custom error class for OAuth-specific errors.
+
+```typescript
+class OAuthError extends Error {
+  error: string; // OAuth error code
+  error_description?: string; // Human-readable error description
+  error_uri?: string; // URI with error information
+}
+```
+
+## 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
+
+## Security Considerations
+
+- The server only accepts connections from localhost
+- Automatically validates the state parameter if provided
+- Server is closed immediately after receiving the callback
+- Supports PKCE (Proof Key for Code Exchange) flow
+- No data is stored persistently
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Run tests
+bun test
+
+# Build
+bun build ./src/index.ts --outdir ./dist
+
+# Run example
+bun run example.ts
+```
+
+## Requirements
+
+- Node.js 14+ or Bun 1.0+
+- A registered OAuth application with a provider
+- Redirect URI configured as `http://localhost:[port]/callback`
+
+## Common Issues
+
+### Port Already in Use
+
+If port 3000 is already in use, specify a different port:
+
+```typescript
+const result = await getAuthCode(authUrl, { port: 8080 });
+```
+
+### Firewall Warnings
+
+On first run, your OS may show a firewall warning. Allow the connection for localhost only.
+
+### Browser Doesn't Open
+
+If the browser doesn't open automatically, manually navigate to the authorization URL.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+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
+
+## License
+
+This project is released under the MIT License. Feel free to use it in your projects, modify it to suit your needs, and share it with others. We believe in open source and hope this tool makes OAuth integration easier for everyone!
+
+## Support
+
+Found a bug or have a question? Please open an issue on the [GitHub issue tracker](https://github.com/koistya/oauth-callback/issues) and we'll be happy to help. If this project saves you time and you'd like to support its continued development, consider [becoming a sponsor](https://github.com/sponsors/koistya). Every bit of support helps maintain and improve this tool for the community. Thank you!

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Get the OAuth authorization code from the authorization URL.
+ *
+ * @param input Authorization URL or authorization options.
+ */
+export declare function getAuthCode(input: {
+    /** OAuth authorization URL */
+    authorizeUrl: string;
+    /** @default 3000 */
+    port?: number;
+    /** @default true  */
+    throwOnError?: boolean;
+    /** @default true */
+    openBrowser?: boolean;
+} | string): Promise<void>;

package/dist/index.js

@@ -0,0 +1,13 @@
+// index.ts
+async function getAuthCode(input) {
+  const {
+    authorizeUrl,
+    port = 3000,
+    throwOnError = true,
+    openBrowser = true
+  } = typeof input === "string" ? { authorizeUrl: input } : input;
+  throw new Error("Not implemented");
+}
+export {
+  getAuthCode
+};

package/index.ts

@@ -0,0 +1,30 @@
+import { createServer } from "node:http";
+
+/**
+ * Get the OAuth authorization code from the authorization URL.
+ *
+ * @param input Authorization URL or authorization options.
+ */
+export async function getAuthCode(
+  input:
+    | {
+        /** OAuth authorization URL */
+        authorizeUrl: string;
+        /** @default 3000 */
+        port?: number;
+        /** @default true  */
+        throwOnError?: boolean;
+        /** @default true */
+        openBrowser?: boolean;
+      }
+    | string,
+) {
+  const {
+    authorizeUrl,
+    port = 3000,
+    throwOnError = true,
+    openBrowser = true,
+  } = typeof input === "string" ? { authorizeUrl: input } : input;
+
+  throw new Error("Not implemented");
+}

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "oauth-callback",
+  "version": "0.0.1",
+  "description": "Lightweight OAuth 2.0 and OpenID Connect callback handler for Node.js, Deno and Bun applications with RFC 6749 and RFC 7591 compliance",
+  "keywords": [
+    "oauth",
+    "callback",
+    "authentication",
+    "auth",
+    "bun",
+    "oauth2",
+    "login",
+    "authorization",
+    "web",
+    "handler",
+    "security",
+    "redirect",
+    "token",
+    "javascript",
+    "typescript",
+    "rfc6749",
+    "rfc7591",
+    "openid",
+    "oidc",
+    "client",
+    "server",
+    "middleware",
+    "express",
+    "fastify",
+    "session",
+    "jwt",
+    "bearer",
+    "access-token",
+    "refresh-token"
+  ],
+  "author": "Konstantin Tarkus <koistya@kriasoft.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kriasoft/oauth-callback.git"
+  },
+  "homepage": "https://github.com/kriasoft/oauth-callback",
+  "bugs": {
+    "url": "https://github.com/kriasoft/oauth-callback/issues"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/koistya"
+  },
+  "files": [
+    "dist",
+    "index.ts",
+    "LICENSE",
+    "README.md"
+  ],
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "bun": "./index.ts",
+      "deno": "./index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.9.2",
+    "prettier": "^3.6.2"
+  },
+  "prettier": {
+    "printWidth": 80,
+    "tabWidth": 2,
+    "useTabs": false,
+    "singleQuote": false,
+    "trailingComma": "all"
+  },
+  "scripts": {
+    "build": "bun build ./index.ts --outdir=./dist --target=node && tsc --declaration --emitDeclarationOnly --outDir ./dist",
+    "prepublishOnly": "bun run build",
+    "test": "bun test"
+  }
+}