@ferrlabs/mcp-core 6.3.2 → 6.4.0

package/dist/auth/__tests__/oauth.test.js

@@ -1,6 +1,7 @@
 import { describe, it, expect } from 'vitest';
-import { generatePkcePair } from '../oauth.js';
+import { generatePkcePair, __testOnly } from '../oauth.js';
 import { createHash } from 'node:crypto';
+import { createServer } from 'node:http';
 describe('generatePkcePair', () => {
     it('returns a verifier between 43 and 128 chars (RFC 7636)', () => {
         const { verifier } = generatePkcePair();
@@ -24,3 +25,40 @@ describe('generatePkcePair', () => {
         expect(challenge).toMatch(/^[A-Za-z0-9_-]+$/);
     });
 });
+function closeServer(server) {
+    return new Promise((resolve) => server.close(() => resolve()));
+}
+async function freePort() {
+    const probe = createServer();
+    await new Promise((resolve) => probe.listen(0, '127.0.0.1', () => resolve()));
+    const addr = probe.address();
+    const port = typeof addr === 'object' && addr ? addr.port : 0;
+    await closeServer(probe);
+    return port;
+}
+describe('bindCallbackListener (port fallback)', () => {
+    it('rejects synchronously with EADDRINUSE when the port is already bound', async () => {
+        const port = await freePort();
+        const squatter = createServer();
+        await new Promise((resolve) => squatter.listen(port, '127.0.0.1', () => resolve()));
+        try {
+            await expect(__testOnly.bindCallbackListener(port, 'st')).rejects.toThrow(/EADDRINUSE/);
+        }
+        finally {
+            await closeServer(squatter);
+        }
+    });
+    it('resolves with the bound port when the socket is free', async () => {
+        const port = await freePort();
+        const bound = await __testOnly.bindCallbackListener(port, 'st');
+        expect(bound.port).toBe(port);
+        // Attach a catch handler *before* triggering the rejection so the
+        // unhandled-rejection guard in vitest stays quiet.
+        const callbackSettled = bound.callback.catch((err) => err);
+        const res = await fetch(`http://127.0.0.1:${port}/cb?code=x&state=wrong`);
+        expect(res.status).toBe(400);
+        const settled = await callbackSettled;
+        expect(settled).toBeInstanceOf(Error);
+        expect(settled.message).toMatch(/state mismatch/);
+    });
+});

package/dist/auth/oauth.d.ts

@@ -3,10 +3,32 @@ interface PkcePair {
     challenge: string;
 }
 export declare function generatePkcePair(): PkcePair;
+interface CallbackResult {
+    code: string;
+    state: string;
+}
+interface BoundListener {
+    port: number;
+    callback: Promise<CallbackResult>;
+}
+/**
+ * Bind a loopback HTTP listener on `port` and return a resolved promise
+ * only once the socket is actually `listening`. Rejects with the bind
+ * error (e.g. `EADDRINUSE`) before returning, so callers can synchronously
+ * fall back to a different port via `await` + `try/catch`.
+ *
+ * The returned `callback` promise lives for the duration of the OAuth
+ * flow and resolves when `/cb` is hit with a matching `state`, or rejects
+ * on CSRF mismatch / internal error.
+ */
+declare function bindCallbackListener(port: number, expectedState: string): Promise<BoundListener>;
 export interface RunLoopbackFlowResult {
     token: string;
     scope?: string;
 }
+export declare const __testOnly: {
+    bindCallbackListener: typeof bindCallbackListener;
+};
 export declare function runLoopbackOauthFlow(): Promise<RunLoopbackFlowResult>;
 export {};
 //# sourceMappingURL=oauth.d.ts.map

package/dist/auth/oauth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../../src/auth/oauth.ts"],"names":[],"mappings":"AAWA,UAAU,QAAQ;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,gBAAgB,IAAI,QAAQ,CAI3C;AA4FD,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,qBAAqB,CAAC,CA+C3E"}
+{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../../src/auth/oauth.ts"],"names":[],"mappings":"AAWA,UAAU,QAAQ;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,gBAAgB,IAAI,QAAQ,CAI3C;AAwBD,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,UAAU,aAAa;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;CACnC;AAED;;;;;;;;;GASG;AACH,iBAAS,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAwDzF;AA4BD,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,UAAU;;CAEtB,CAAC;AAEF,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,qBAAqB,CAAC,CAoD3E"}

package/dist/auth/oauth.js

@@ -32,8 +32,24 @@ function openBrowser(url) {
     });
     child.unref();
 }
-function listenForCallback(port, expectedState) {
-    return new Promise((resolve, reject) => {
+/**
+ * Bind a loopback HTTP listener on `port` and return a resolved promise
+ * only once the socket is actually `listening`. Rejects with the bind
+ * error (e.g. `EADDRINUSE`) before returning, so callers can synchronously
+ * fall back to a different port via `await` + `try/catch`.
+ *
+ * The returned `callback` promise lives for the duration of the OAuth
+ * flow and resolves when `/cb` is hit with a matching `state`, or rejects
+ * on CSRF mismatch / internal error.
+ */
+function bindCallbackListener(port, expectedState) {
+    return new Promise((resolveBound, rejectBound) => {
+        let resolveCallback;
+        let rejectCallback;
+        const callback = new Promise((res, rej) => {
+            resolveCallback = res;
+            rejectCallback = rej;
+        });
         const server = createServer((req, res) => {
             try {
                 const url = new URL(req.url ?? '/', `http://127.0.0.1:${port}`);
@@ -49,21 +65,33 @@ function listenForCallback(port, expectedState) {
                 }
                 if (state !== expectedState) {
                     res.writeHead(400).end('state mismatch');
-                    reject(new Error('OAuth callback state mismatch (CSRF protection triggered)'));
+                    rejectCallback(new Error('OAuth callback state mismatch (CSRF protection triggered)'));
                     server.close();
                     return;
                 }
                 res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', Connection: 'close' });
                 res.end("<!doctype html><html><body style='font-family:sans-serif;padding:2rem;color:#1e293b'><h1>Authorized</h1><p>You can close this tab and return to your terminal.</p></body></html>");
                 setImmediate(() => server.close());
-                resolve({ code, state });
+                resolveCallback({ code, state });
             }
             catch (err) {
                 res.writeHead(500).end('Internal error');
-                reject(err instanceof Error ? err : new Error(String(err)));
+                rejectCallback(err instanceof Error ? err : new Error(String(err)));
             }
         });
-        server.on('error', reject);
+        const onBindError = (err) => {
+            server.removeListener('listening', onListening);
+            rejectBound(err);
+        };
+        const onListening = () => {
+            server.removeListener('error', onBindError);
+            // Once bound successfully, route runtime errors into the callback
+            // promise (e.g. unexpected close after we've started serving).
+            server.on('error', (err) => rejectCallback(err));
+            resolveBound({ port, callback });
+        };
+        server.once('error', onBindError);
+        server.once('listening', onListening);
         server.listen(port, '127.0.0.1');
     });
 }
@@ -87,24 +115,32 @@ async function exchangeCodeForToken(code, codeVerifier, redirectUri) {
         throw new Error('OAuth exchange returned no token');
     return data.token;
 }
+export const __testOnly = {
+    bindCallbackListener,
+};
 export async function runLoopbackOauthFlow() {
     const pkce = generatePkcePair();
     const state = generateState();
-    let port = null;
-    let callbackPromise = null;
+    let bound = null;
+    const bindErrors = [];
     for (const candidate of REDIRECT_PORTS) {
         try {
-            callbackPromise = listenForCallback(candidate, state);
-            port = candidate;
+            // eslint-disable-next-line no-await-in-loop -- intentional: probe ports sequentially
+            bound = await bindCallbackListener(candidate, state);
             break;
         }
-        catch {
-            callbackPromise = null;
+        catch (err) {
+            bindErrors.push({
+                port: candidate,
+                error: err instanceof Error ? err.message : String(err),
+            });
         }
     }
-    if (port === null || !callbackPromise) {
-        throw new Error(`Could not bind any of the loopback ports (${REDIRECT_PORTS.join(', ')}). Close whatever is using them and retry.`);
+    if (!bound) {
+        const detail = bindErrors.map((e) => `${e.port}: ${e.error}`).join('; ');
+        throw new Error(`Could not bind any of the loopback ports (${REDIRECT_PORTS.join(', ')}). ${detail}. Close whatever is holding the ports (commonly an MCP subprocess from another Claude session stuck in OAuth), then retry.`);
     }
+    const { port, callback: callbackPromise } = bound;
     const redirectUri = `http://127.0.0.1:${port}/cb`;
     const authorizeUrl = new URL(`${AUTH_BASE}/authorize`);
     authorizeUrl.searchParams.set('client_id', CLIENT_ID);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ferrlabs/mcp-core",
-  "version": "6.3.2",
+  "version": "6.4.0",
   "description": "Shared core for FerrLabs MCP servers — auth, transports (stdio + Streamable HTTP), api-client, runner",
   "license": "MPL-2.0",
   "type": "module",