@thuyphuocthinh/mcp-auth-proxy 0.0.0-stage → 1.0.0

package/dist/src/proxy.js

@@ -0,0 +1,126 @@
+import readline from 'node:readline';
+/**
+ * Extracts JSON-RPC message payloads from SSE (text/event-stream) response chunks.
+ * Conforms to standard Model Context Protocol (MCP) Streamable HTTP specification:
+ * event: message
+ * data: {"jsonrpc":"2.0", ...}
+ */
+export function extractJsonRpcFromSse(responseText) {
+    const results = [];
+    const lines = responseText.split('\n');
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith('data:')) {
+            const dataContent = trimmed.substring(5).trim();
+            if (dataContent) {
+                results.push(dataContent);
+            }
+        }
+    }
+    // Fallback if server returned raw non-SSE JSON
+    if (results.length === 0 && responseText.trim().startsWith('{')) {
+        results.push(responseText.trim());
+    }
+    return results;
+}
+/**
+ * Forwards a single JSON-RPC line from Stdio to the Remote HTTP MCP Server.
+ */
+export async function forwardJsonRpc(options) {
+    const { line, remoteUrl, headers, fetchFn = fetch } = options;
+    let requestId = null;
+    try {
+        const parsed = JSON.parse(line);
+        requestId = parsed.id ?? null;
+    }
+    catch {
+        // Malformed JSON input from client
+    }
+    try {
+        const response = await fetchFn(remoteUrl, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Accept': 'application/json, text/event-stream',
+                ...headers
+            },
+            body: line
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            return [
+                JSON.stringify({
+                    jsonrpc: '2.0',
+                    id: requestId,
+                    error: {
+                        code: -32603,
+                        message: `Remote MCP server returned HTTP ${response.status}: ${errorText}`
+                    }
+                })
+            ];
+        }
+        const responseText = await response.text();
+        return extractJsonRpcFromSse(responseText);
+    }
+    catch (err) {
+        return [
+            JSON.stringify({
+                jsonrpc: '2.0',
+                id: requestId,
+                error: {
+                    code: -32603,
+                    message: `Failed to connect to remote MCP server: ${err.message}`
+                }
+            })
+        ];
+    }
+}
+/**
+ * Starts Stdio bidirectional proxy loop.
+ * Reads newline-delimited JSON-RPC from stdin, attaches valid token, and writes to stdout.
+ */
+export async function startProxy(options) {
+    const { remoteUrl, getToken, extraHeaders = {}, input = process.stdin, output = process.stdout, fetchFn = fetch, logError = console.error } = options;
+    const rl = readline.createInterface({
+        input,
+        output: undefined,
+        terminal: false
+    });
+    for await (const rawLine of rl) {
+        const line = rawLine.trim();
+        if (!line)
+            continue;
+        try {
+            const token = await getToken();
+            const headers = {
+                ...extraHeaders
+            };
+            if (token) {
+                headers['Authorization'] = `Bearer ${token}`;
+            }
+            const results = await forwardJsonRpc({
+                line,
+                remoteUrl,
+                headers,
+                fetchFn
+            });
+            for (const res of results) {
+                output.write(res + '\n');
+            }
+        }
+        catch (err) {
+            logError(`[-] Proxy error: ${err.message}`);
+            let requestId = null;
+            try {
+                const parsed = JSON.parse(line);
+                requestId = parsed.id ?? null;
+            }
+            catch { }
+            output.write(JSON.stringify({
+                jsonrpc: '2.0',
+                id: requestId,
+                error: { code: -32603, message: err.message }
+            }) + '\n');
+        }
+    }
+}

package/dist/src/store/token-store.d.ts

@@ -0,0 +1,29 @@
+export interface StoredToken {
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt: number;
+    tokenType?: string;
+    scope?: string;
+}
+export declare class TokenStore {
+    private storePath;
+    constructor(customPath?: string);
+    saveToken(resource: string, token: StoredToken): void;
+    getToken(resource: string): StoredToken | null;
+    isExpiringSoon(token: StoredToken, bufferMs?: number): boolean;
+    refreshToken(options: {
+        resource: string;
+        tokenEndpoint: string;
+        clientId: string;
+        fetchFn?: typeof fetch;
+        log?: (msg: string) => void;
+    }): Promise<string | null>;
+    getOrRefreshToken(options: {
+        resource: string;
+        tokenEndpoint: string;
+        clientId: string;
+        fetchFn?: typeof fetch;
+        log?: (msg: string) => void;
+    }): Promise<string | null>;
+    private readAll;
+}

package/dist/src/store/token-store.js

@@ -0,0 +1,99 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+export class TokenStore {
+    storePath;
+    constructor(customPath) {
+        this.storePath =
+            customPath || path.join(os.homedir(), '.mcp-oauth-proxy', 'tokens.json');
+    }
+    saveToken(resource, token) {
+        const data = this.readAll();
+        data[resource] = token;
+        fs.mkdirSync(path.dirname(this.storePath), { recursive: true });
+        fs.writeFileSync(this.storePath, JSON.stringify(data, null, 2), 'utf-8');
+    }
+    getToken(resource) {
+        const data = this.readAll();
+        return data[resource] || null;
+    }
+    isExpiringSoon(token, bufferMs = 300_000) {
+        // Default buffer: 5 minutes (300,000ms)
+        return Date.now() >= token.expiresAt - bufferMs;
+    }
+    async refreshToken(options) {
+        const { resource, tokenEndpoint, clientId, fetchFn = fetch, log = console.log } = options;
+        const current = this.getToken(resource);
+        if (!current?.refreshToken) {
+            log(`[-] No refresh_token available for resource: ${resource}`);
+            return null;
+        }
+        try {
+            log(`[*] Performing silent background token refresh...`);
+            const response = await fetchFn(tokenEndpoint, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+                body: new URLSearchParams({
+                    grant_type: 'refresh_token',
+                    client_id: clientId,
+                    refresh_token: current.refreshToken
+                })
+            });
+            if (!response.ok) {
+                const errorText = await response.text();
+                log(`[-] Silent token refresh failed (HTTP ${response.status}): ${errorText}`);
+                return null;
+            }
+            const data = (await response.json());
+            const updatedToken = {
+                accessToken: data.access_token,
+                refreshToken: data.refresh_token || current.refreshToken,
+                expiresAt: Date.now() + data.expires_in * 1000,
+                tokenType: data.token_type || current.tokenType,
+                scope: data.scope || current.scope
+            };
+            this.saveToken(resource, updatedToken);
+            log(`[+] Token refreshed successfully! Valid for ${data.expires_in}s.`);
+            return updatedToken.accessToken;
+        }
+        catch (err) {
+            log(`[-] Network error during silent token refresh: ${err.message}`);
+            return null;
+        }
+    }
+    async getOrRefreshToken(options) {
+        const { resource } = options;
+        const current = this.getToken(resource);
+        if (!current) {
+            return null;
+        }
+        // Still valid for more than buffer duration
+        if (!this.isExpiringSoon(current)) {
+            return current.accessToken;
+        }
+        // Expiring soon: silently refresh if refresh_token exists
+        if (current.refreshToken) {
+            const refreshed = await this.refreshToken(options);
+            if (refreshed) {
+                return refreshed;
+            }
+        }
+        // If refresh failed but token is technically not past absolute expiration timestamp
+        if (Date.now() < current.expiresAt) {
+            return current.accessToken;
+        }
+        return null;
+    }
+    readAll() {
+        if (!fs.existsSync(this.storePath)) {
+            return {};
+        }
+        try {
+            const content = fs.readFileSync(this.storePath, 'utf-8');
+            return JSON.parse(content);
+        }
+        catch {
+            return {};
+        }
+    }
+}

package/dist/tests/cli.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/cli.test.js

@@ -0,0 +1,50 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { parseArgs } from '../src/index.js';
+describe('CLI Argument Parser', () => {
+    it('should parse positional remote URL without flags', () => {
+        const options = parseArgs(['https://mcp.200lab.io/mcp/learner']);
+        assert.strictEqual(options.remoteUrl, 'https://mcp.200lab.io/mcp/learner');
+        assert.strictEqual(options.noBrowser, false);
+        assert.strictEqual(options.loginOnly, false);
+        assert.strictEqual(options.help, false);
+        assert.strictEqual(options.version, false);
+        assert.deepStrictEqual(options.headers, {});
+    });
+    it('should parse --client-id flag', () => {
+        const options = parseArgs(['https://api.example.com', '--client-id', 'client_id_999']);
+        assert.strictEqual(options.clientId, 'client_id_999');
+    });
+    it('should parse single and multiple --header flags with key-value pairs', () => {
+        const options = parseArgs([
+            'https://api.example.com',
+            '--header',
+            'Authorization: Bearer static_token_123',
+            '--header',
+            'X-API-Key: secret_key',
+            '--header',
+            'User-Agent: CustomMCPClient/1.0'
+        ]);
+        assert.strictEqual(options.headers['Authorization'], 'Bearer static_token_123');
+        assert.strictEqual(options.headers['X-API-Key'], 'secret_key');
+        assert.strictEqual(options.headers['User-Agent'], 'CustomMCPClient/1.0');
+    });
+    it('should ignore malformed --header flags lacking colon separator', () => {
+        const options = parseArgs(['https://api.example.com', '--header', 'InvalidHeaderValueWithoutColon']);
+        assert.deepStrictEqual(options.headers, {});
+    });
+    it('should parse boolean flags accurately', () => {
+        assert.strictEqual(parseArgs(['--no-browser']).noBrowser, true);
+        assert.strictEqual(parseArgs(['--login-only']).loginOnly, true);
+        assert.strictEqual(parseArgs(['-h']).help, true);
+        assert.strictEqual(parseArgs(['--help']).help, true);
+        assert.strictEqual(parseArgs(['-v']).version, true);
+        assert.strictEqual(parseArgs(['--version']).version, true);
+    });
+    it('should handle URL placed after options', () => {
+        const options = parseArgs(['--no-browser', '--client-id', 'test_id', 'https://mcp.service.io']);
+        assert.strictEqual(options.remoteUrl, 'https://mcp.service.io');
+        assert.strictEqual(options.clientId, 'test_id');
+        assert.strictEqual(options.noBrowser, true);
+    });
+});

package/dist/tests/oauth/browser.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/oauth/browser.test.js

@@ -0,0 +1,35 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { getOpenBrowserCommand, openBrowser } from '../../src/oauth/browser.js';
+describe('OAuth Browser Opener', () => {
+    const sampleUrl = 'https://api.200lab.io/oauth/authorize?client_id=test&scope=learner#section';
+    it('should generate valid start command on Windows (win32)', () => {
+        const cmd = getOpenBrowserCommand(sampleUrl, 'win32');
+        assert.strictEqual(cmd, `start "" "${sampleUrl}"`);
+    });
+    it('should generate valid open command on macOS (darwin)', () => {
+        const cmd = getOpenBrowserCommand(sampleUrl, 'darwin');
+        assert.strictEqual(cmd, `open "${sampleUrl}"`);
+    });
+    it('should generate valid xdg-open command on Linux and other POSIX platforms', () => {
+        assert.strictEqual(getOpenBrowserCommand(sampleUrl, 'linux'), `xdg-open "${sampleUrl}"`);
+        assert.strictEqual(getOpenBrowserCommand(sampleUrl, 'freebsd'), `xdg-open "${sampleUrl}"`);
+        assert.strictEqual(getOpenBrowserCommand(sampleUrl, 'openbsd'), `xdg-open "${sampleUrl}"`);
+    });
+    it('should escape URLs with query parameters properly', () => {
+        const complexUrl = 'https://auth.example.com/oauth/authorize?response_type=code&scope=read%20write&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Fcallback';
+        const cmd = getOpenBrowserCommand(complexUrl, 'win32');
+        assert.ok(cmd.startsWith('start "" "'));
+        assert.ok(cmd.endsWith('"'));
+        assert.ok(cmd.includes('scope=read%20write'));
+    });
+    it('openBrowser should log clear operational and fallback messages to provided logger', async () => {
+        const loggedMessages = [];
+        const mockLogger = (msg) => loggedMessages.push(msg);
+        await openBrowser('https://example.com/test-oauth', mockLogger);
+        assert.ok(loggedMessages.length >= 2);
+        assert.ok(loggedMessages.some((m) => m.includes('Automatically opening default browser')));
+        assert.ok(loggedMessages.some((m) => m.includes('https://example.com/test-oauth')));
+        assert.ok(loggedMessages.some((m) => m.includes('If the browser does not open automatically')));
+    });
+});

package/dist/tests/oauth/client-registration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/oauth/client-registration.test.js

@@ -0,0 +1,72 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { registerDynamicClient, resolveClientId } from '../../src/oauth/client-registration.js';
+describe('OAuth Client Registration (RFC 7591)', () => {
+    const redirectUri = 'http://localhost:8080/callback';
+    const registrationEndpoint = 'https://api.example.com/oauth/register';
+    it('should post client metadata and return issued client_id', async () => {
+        let capturedBody;
+        let capturedHeaders;
+        const mockFetch = async (_input, init) => {
+            capturedHeaders = init?.headers;
+            capturedBody = JSON.parse(init?.body);
+            return new Response(JSON.stringify({
+                client_id: 'client_registered_777',
+                client_name: capturedBody.client_name,
+                redirect_uris: capturedBody.redirect_uris
+            }), { status: 201, headers: { 'Content-Type': 'application/json' } });
+        };
+        const clientId = await registerDynamicClient(registrationEndpoint, redirectUri, 'custom-proxy', mockFetch);
+        assert.strictEqual(clientId, 'client_registered_777');
+        assert.strictEqual(capturedBody.client_name, 'custom-proxy');
+        assert.deepStrictEqual(capturedBody.redirect_uris, [redirectUri]);
+        assert.strictEqual(capturedHeaders['Content-Type'], 'application/json');
+    });
+    it('should throw an informative error when registration server returns non-200', async () => {
+        const mockFetch = async () => {
+            return new Response('Invalid client metadata', { status: 400 });
+        };
+        await assert.rejects(async () => {
+            await registerDynamicClient(registrationEndpoint, redirectUri, 'proxy', mockFetch);
+        }, /Dynamic Client Registration failed \(HTTP 400\): Invalid client metadata/);
+    });
+    it('should throw an error when server response is missing client_id', async () => {
+        const mockFetch = async () => {
+            return new Response(JSON.stringify({ status: 'ok' }), { status: 200 });
+        };
+        await assert.rejects(async () => {
+            await registerDynamicClient(registrationEndpoint, redirectUri, 'proxy', mockFetch);
+        }, /Registration response missing client_id/);
+    });
+    it('resolveClientId should prioritize explicitClientId when provided by user', async () => {
+        const logs = [];
+        const clientId = await resolveClientId({
+            registrationEndpoint,
+            redirectUri,
+            explicitClientId: 'user_provided_fixed_id',
+            log: (msg) => logs.push(msg)
+        });
+        assert.strictEqual(clientId, 'user_provided_fixed_id');
+        assert.ok(logs.some((l) => l.includes('Using configured Client ID: user_provided_fixed_id')));
+    });
+    it('resolveClientId should dynamically register when no explicit ID provided', async () => {
+        const mockFetch = async () => {
+            return new Response(JSON.stringify({ client_id: 'auto_gen_123' }), { status: 200 });
+        };
+        const clientId = await resolveClientId({
+            registrationEndpoint,
+            redirectUri,
+            fetchFn: mockFetch,
+            log: () => { }
+        });
+        assert.strictEqual(clientId, 'auto_gen_123');
+    });
+    it('resolveClientId should throw an error if registration endpoint is unavailable and no explicit ID given', async () => {
+        await assert.rejects(async () => {
+            await resolveClientId({
+                redirectUri,
+                log: () => { }
+            });
+        }, /Server does not support Dynamic Client Registration \(RFC 7591\)\. Please provide an explicit --client-id <id>/);
+    });
+});

package/dist/tests/oauth/discovery.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/oauth/discovery.test.js

@@ -0,0 +1,94 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { extractResourceMetadataUrl, discoverOAuth } from '../../src/oauth/discovery.js';
+describe('OAuth Metadata Discovery', () => {
+    it('should extract resource_metadata URL from valid WWW-Authenticate Bearer header', () => {
+        const header = 'Bearer resource_metadata="https://mcp.200lab.io/.well-known/oauth-protected-resource/mcp/learner"';
+        const extracted = extractResourceMetadataUrl(header);
+        assert.strictEqual(extracted, 'https://mcp.200lab.io/.well-known/oauth-protected-resource/mcp/learner');
+    });
+    it('should be case-insensitive for Bearer and resource_metadata tokens', () => {
+        const header = 'bearer RESOURCE_METADATA="https://mcp.example.com/meta"';
+        const extracted = extractResourceMetadataUrl(header);
+        assert.strictEqual(extracted, 'https://mcp.example.com/meta');
+    });
+    it('should return null for headers lacking resource_metadata', () => {
+        assert.strictEqual(extractResourceMetadataUrl(null), null);
+        assert.strictEqual(extractResourceMetadataUrl(''), null);
+        assert.strictEqual(extractResourceMetadataUrl('Bearer realm="OAuth"'), null);
+        assert.strictEqual(extractResourceMetadataUrl('Basic realm="Restricted"'), null);
+    });
+    it('should execute full discovery handshake and return all resolved endpoints', async () => {
+        const mockFetch = async (input) => {
+            const url = input.toString();
+            if (url === 'https://mcp.company.com/service') {
+                return new Response('Unauthorized', {
+                    status: 401,
+                    headers: {
+                        'WWW-Authenticate': 'Bearer resource_metadata="https://mcp.company.com/.well-known/resource"'
+                    }
+                });
+            }
+            if (url === 'https://mcp.company.com/.well-known/resource') {
+                return new Response(JSON.stringify({
+                    resource: 'https://mcp.company.com/service',
+                    authorization_servers: ['https://auth.company.com/'],
+                    scopes_supported: ['read', 'write']
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } });
+            }
+            if (url === 'https://auth.company.com/.well-known/oauth-authorization-server') {
+                return new Response(JSON.stringify({
+                    issuer: 'https://auth.company.com',
+                    authorization_endpoint: 'https://auth.company.com/oauth/authorize',
+                    token_endpoint: 'https://auth.company.com/oauth/token',
+                    registration_endpoint: 'https://auth.company.com/oauth/register'
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } });
+            }
+            return new Response('Not Found', { status: 404 });
+        };
+        const metadata = await discoverOAuth('https://mcp.company.com/service', mockFetch);
+        assert.strictEqual(metadata.resource, 'https://mcp.company.com/service');
+        assert.strictEqual(metadata.authorizationEndpoint, 'https://auth.company.com/oauth/authorize');
+        assert.strictEqual(metadata.tokenEndpoint, 'https://auth.company.com/oauth/token');
+        assert.strictEqual(metadata.registrationEndpoint, 'https://auth.company.com/oauth/register');
+        assert.deepStrictEqual(metadata.scopes, ['read', 'write']);
+    });
+    it('should throw an informative error when remote server does not provide 401 WWW-Authenticate header', async () => {
+        const mockFetch = async () => new Response('OK', { status: 200 });
+        await assert.rejects(async () => {
+            await discoverOAuth('https://mcp.example.com', mockFetch);
+        }, /Missing 'WWW-Authenticate: Bearer resource_metadata="\.\.\."' header/);
+    });
+    it('should throw an error when Resource Metadata returns HTTP error', async () => {
+        const mockFetch = async (input) => {
+            const url = input.toString();
+            if (url.includes('probe')) {
+                return new Response('Unauthorized', {
+                    status: 401,
+                    headers: {
+                        'WWW-Authenticate': 'Bearer resource_metadata="https://mcp.example.com/bad-meta"'
+                    }
+                });
+            }
+            return new Response('Not Found', { status: 404 });
+        };
+        await assert.rejects(async () => {
+            await discoverOAuth('https://mcp.example.com/probe', mockFetch);
+        }, /Failed to fetch Resource Metadata/);
+    });
+    it('should throw an error when Resource Metadata lacks authorization_servers', async () => {
+        const mockFetch = async (input) => {
+            const url = input.toString();
+            if (url.includes('probe')) {
+                return new Response('Unauthorized', {
+                    status: 401,
+                    headers: { 'WWW-Authenticate': 'Bearer resource_metadata="https://mcp.example.com/meta"' }
+                });
+            }
+            return new Response(JSON.stringify({ resource: 'test' }), { status: 200 });
+        };
+        await assert.rejects(async () => {
+            await discoverOAuth('https://mcp.example.com/probe', mockFetch);
+        }, /Resource Metadata does not contain valid authorization_servers/);
+    });
+});

package/dist/tests/oauth/pkce.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/oauth/pkce.test.js

@@ -0,0 +1,40 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import crypto from 'node:crypto';
+import { generatePKCE, base64url } from '../../src/oauth/pkce.js';
+describe('PKCE Generator (RFC 7636)', () => {
+    it('should generate valid base64url strings without standard base64 padding or symbols', () => {
+        const { verifier, challenge, method } = generatePKCE();
+        assert.strictEqual(method, 'S256');
+        assert.ok(verifier.length >= 43 && verifier.length <= 128, 'Verifier length must be between 43 and 128 characters');
+        assert.match(verifier, /^[A-Za-z0-9_-]+$/, 'Verifier must only contain base64url characters');
+        assert.match(challenge, /^[A-Za-z0-9_-]+$/, 'Challenge must only contain base64url characters');
+        assert.ok(!verifier.includes('+') && !verifier.includes('/') && !verifier.includes('='));
+        assert.ok(!challenge.includes('+') && !challenge.includes('/') && !challenge.includes('='));
+    });
+    it('should compute the exact SHA-256 hash challenge corresponding to the verifier', () => {
+        const { verifier, challenge } = generatePKCE();
+        const expectedChallenge = base64url(crypto.createHash('sha256').update(verifier).digest());
+        assert.strictEqual(challenge, expectedChallenge, 'Challenge must strictly equal base64url(sha256(verifier))');
+    });
+    it('should produce high entropy unique pairs across multiple invocations', () => {
+        const verifiers = new Set();
+        const challenges = new Set();
+        const iterations = 50;
+        for (let i = 0; i < iterations; i++) {
+            const pair = generatePKCE();
+            verifiers.add(pair.verifier);
+            challenges.add(pair.challenge);
+        }
+        assert.strictEqual(verifiers.size, iterations, 'All generated verifiers must be distinct');
+        assert.strictEqual(challenges.size, iterations, 'All generated challenges must be distinct');
+    });
+    it('should correctly format known RFC 7636 test vectors', () => {
+        // RFC 7636 Appendix B test vector
+        const testVerifier = 'dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk';
+        const expectedChallenge = 'E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM';
+        const hash = crypto.createHash('sha256').update(testVerifier).digest();
+        const computedChallenge = base64url(hash);
+        assert.strictEqual(computedChallenge, expectedChallenge, 'base64url must match standard RFC 7636 test vector');
+    });
+});

package/dist/tests/oauth/server.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/oauth/server.test.js

@@ -0,0 +1,53 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import net from 'node:net';
+import { getAvailablePort, startCallbackServer } from '../../src/oauth/server.js';
+describe('OAuth Callback Server & Dynamic Port Selection', () => {
+    it('should find next available port when the initial port is busy', async () => {
+        const testPort = 19123;
+        const blockerServer = net.createServer();
+        await new Promise((resolve) => blockerServer.listen(testPort, () => resolve()));
+        const nextPort = await getAvailablePort(testPort);
+        assert.strictEqual(nextPort, testPort + 1, 'Should increment to next available port');
+        await new Promise((resolve) => blockerServer.close(() => resolve()));
+    });
+    it('should receive authorization code and serve success HTML page on valid callback', async () => {
+        const callbackServer = await startCallbackServer();
+        const expectedCode = 'auth_code_secret_xyz_987';
+        const codePromise = callbackServer.waitForCode();
+        const res = await fetch(`${callbackServer.redirectUri}?code=${expectedCode}`);
+        assert.strictEqual(res.status, 200);
+        const htmlBody = await res.text();
+        assert.ok(htmlBody.includes('Authentication Successful!'));
+        const receivedCode = await codePromise;
+        assert.strictEqual(receivedCode, expectedCode);
+        await callbackServer.close();
+    });
+    it('should handle OAuth error redirect with 400 and reject promise with error description', async () => {
+        const callbackServer = await startCallbackServer();
+        const codePromise = callbackServer.waitForCode();
+        const res = await fetch(`${callbackServer.redirectUri}?error=access_denied&error_description=User+declined+authorization`);
+        assert.strictEqual(res.status, 400);
+        const htmlBody = await res.text();
+        assert.ok(htmlBody.includes('Authentication Failed'));
+        assert.ok(htmlBody.includes('User declined authorization'));
+        await assert.rejects(codePromise, /User declined authorization/);
+        await callbackServer.close();
+    });
+    it('should reject when callback is invoked without authorization code or error parameters', async () => {
+        const callbackServer = await startCallbackServer();
+        const codePromise = callbackServer.waitForCode();
+        const res = await fetch(`${callbackServer.redirectUri}`);
+        assert.strictEqual(res.status, 400);
+        const htmlBody = await res.text();
+        assert.ok(htmlBody.includes('Authorization Code Missing'));
+        await assert.rejects(codePromise, /Missing authorization code in callback/);
+        await callbackServer.close();
+    });
+    it('should return 404 for unhandled routes', async () => {
+        const callbackServer = await startCallbackServer();
+        const res = await fetch(`http://localhost:${callbackServer.port}/non-existent-route`);
+        assert.strictEqual(res.status, 404);
+        await callbackServer.close();
+    });
+});

package/dist/tests/proxy.test.d.ts

@@ -0,0 +1 @@
+export {};