@pharaoh-so/mcp 0.3.21 → 0.3.23

package/dist/proxy.d.ts

@@ -1,18 +1,25 @@
 /**
- * Stdio ↔ SSE proxy — bridges a local MCP stdio connection to a remote Pharaoh SSE server.
- * Uses SDK transports on both ends: StdioServerTransport (local) and SSEClientTransport (remote).
+ * Stdio ↔ SSE proxy entry point. Legacy export surface kept for the
+ * in-flight handoff between Sessions B and C: index.ts (Session C's scope)
+ * still imports `startProxy`, `TokenExpiredError`, and `TenantSuspendedError`
+ * from here. Session C will rewrite index.ts to use ProxyServer/Backend
+ * directly and `startProxy` will disappear at that point.
  *
- * RECONNECTION DESIGN:
- * The MCP SDK's SSEClientTransport wraps an EventSource, which has built-in auto-reconnect
- * (every 3 seconds by default). This auto-reconnect is problematic because:
- *   1. Each reconnect creates a NEW server-side session (new auth, new session ID)
+ * Typed error classes and SSE classification live here because both the
+ * legacy startProxy wrapper and the new SseProxyBackend (in backend.ts) need
+ * to produce the same typed errors so downstream consumers don't care which
+ * path surfaced them.
+ *
+ * RECONNECTION DESIGN (inherited by SseProxyBackend):
+ * The MCP SDK's SSEClientTransport wraps an EventSource, which has built-in
+ * auto-reconnect (every 3s by default). This is problematic because:
+ *   1. Each reconnect creates a NEW server-side session (new auth, new ID)
  *   2. The proxy's reconnect loop doesn't know about the internal reconnect
  *   3. Tool calls get lost between the stale and new sessions
  *
- * Solution: On any non-fatal SSE error, we explicitly close() the transport to kill
- * the EventSource and its auto-reconnect timer, then let the proxy's own backoff loop
- * create a fresh SSEClientTransport for the next attempt. This ensures one session
- * at a time and clean reconnection semantics.
+ * Solution: on any non-fatal SSE error, explicitly close() the transport to
+ * kill the EventSource, then let the proxy's own backoff loop create a fresh
+ * transport for the next attempt. See backend.ts SseProxyBackend.waitForClose.
  */
 /** Thrown when the remote server returns 401 — token is expired or revoked. */
 export declare class TokenExpiredError extends Error {
@@ -24,21 +31,16 @@ export declare class TenantSuspendedError extends Error {
 }
 /**
  * Classify an SSE error — detect 401/403 and throw typed errors.
- * Exported for testability; used internally by the reconnect loop.
+ * Exported for testability; used internally by the reconnect loop in
+ * backend.ts.
  */
 export declare function classifySSEError(err: Error): void;
 /**
- * Start the stdio ↔ SSE proxy. Blocks until the connection is permanently closed.
- *
- * Message flow:
- *   Claude Code → stdin → StdioServerTransport.onmessage → SSEClientTransport.send → POST /message
- *   Pharaoh → SSE stream → SSEClientTransport.onmessage → StdioServerTransport.send → stdout
- *
- * CRITICAL ordering: SSE must be connected BEFORE stdio starts reading stdin.
- * Otherwise the MCP `initialize` message arrives before the remote transport is ready,
- * gets permanently lost ("send error — Not connected"), and the client times out.
+ * Legacy thin wrapper that starts the new ProxyServer in SSE mode and blocks
+ * until the underlying SSE backend exits. Preserved so index.ts (Session C)
+ * keeps compiling until the wiring PR; the return/throw contract matches the
+ * original (resolves on clean exit, throws TokenExpiredError / TenantSuspendedError).
  *
- * On SSE disconnect, attempts reconnect with exponential backoff (5 retries, ~62s total).
- * Throws TokenExpiredError on 401, TenantSuspendedError on 403.
+ * @deprecated Session C will call ProxyServer / startInSseMode directly.
  */
 export declare function startProxy(sseUrl: string, token: string): Promise<void>;

package/dist/proxy.js

@@ -1,21 +1,26 @@
 /**
- * Stdio ↔ SSE proxy — bridges a local MCP stdio connection to a remote Pharaoh SSE server.
- * Uses SDK transports on both ends: StdioServerTransport (local) and SSEClientTransport (remote).
+ * Stdio ↔ SSE proxy entry point. Legacy export surface kept for the
+ * in-flight handoff between Sessions B and C: index.ts (Session C's scope)
+ * still imports `startProxy`, `TokenExpiredError`, and `TenantSuspendedError`
+ * from here. Session C will rewrite index.ts to use ProxyServer/Backend
+ * directly and `startProxy` will disappear at that point.
  *
- * RECONNECTION DESIGN:
- * The MCP SDK's SSEClientTransport wraps an EventSource, which has built-in auto-reconnect
- * (every 3 seconds by default). This auto-reconnect is problematic because:
- *   1. Each reconnect creates a NEW server-side session (new auth, new session ID)
+ * Typed error classes and SSE classification live here because both the
+ * legacy startProxy wrapper and the new SseProxyBackend (in backend.ts) need
+ * to produce the same typed errors so downstream consumers don't care which
+ * path surfaced them.
+ *
+ * RECONNECTION DESIGN (inherited by SseProxyBackend):
+ * The MCP SDK's SSEClientTransport wraps an EventSource, which has built-in
+ * auto-reconnect (every 3s by default). This is problematic because:
+ *   1. Each reconnect creates a NEW server-side session (new auth, new ID)
  *   2. The proxy's reconnect loop doesn't know about the internal reconnect
  *   3. Tool calls get lost between the stale and new sessions
  *
- * Solution: On any non-fatal SSE error, we explicitly close() the transport to kill
- * the EventSource and its auto-reconnect timer, then let the proxy's own backoff loop
- * create a fresh SSEClientTransport for the next attempt. This ensures one session
- * at a time and clean reconnection semantics.
+ * Solution: on any non-fatal SSE error, explicitly close() the transport to
+ * kill the EventSource, then let the proxy's own backoff loop create a fresh
+ * transport for the next attempt. See backend.ts SseProxyBackend.waitForClose.
  */
-import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 /** Thrown when the remote server returns 401 — token is expired or revoked. */
 export class TokenExpiredError extends Error {
     constructor() {
@@ -30,11 +35,10 @@ export class TenantSuspendedError extends Error {
         this.name = "TenantSuspendedError";
     }
 }
-/** Backoff schedule for reconnect attempts (milliseconds). */
-const BACKOFF_MS = [2000, 4000, 8000, 16000, 32000];
 /**
  * Classify an SSE error — detect 401/403 and throw typed errors.
- * Exported for testability; used internally by the reconnect loop.
+ * Exported for testability; used internally by the reconnect loop in
+ * backend.ts.
  */
 export function classifySSEError(err) {
     const msg = err.message ?? "";
@@ -53,120 +57,28 @@ export function classifySSEError(err) {
         throw new TenantSuspendedError(msg || "Tenant suspended");
 }
 /**
- * Create an SSEClientTransport with Bearer token auth.
- * Injects the Authorization header into both the SSE connection (via custom fetch)
- * and POST requests (via requestInit).
- */
-function createSSETransport(sseUrl, token) {
-    const authHeader = `Bearer ${token}`;
-    return new SSEClientTransport(new URL(sseUrl), {
-        eventSourceInit: {
-            fetch: (url, init) => {
-                const h = new Headers(init.headers);
-                h.set("Authorization", authHeader);
-                return fetch(url, { ...init, headers: h });
-            },
-        },
-        requestInit: {
-            headers: { Authorization: authHeader },
-        },
-    });
-}
-/**
- * Start the stdio ↔ SSE proxy. Blocks until the connection is permanently closed.
+ * Legacy thin wrapper that starts the new ProxyServer in SSE mode and blocks
+ * until the underlying SSE backend exits. Preserved so index.ts (Session C)
+ * keeps compiling until the wiring PR; the return/throw contract matches the
+ * original (resolves on clean exit, throws TokenExpiredError / TenantSuspendedError).
  *
- * Message flow:
- *   Claude Code → stdin → StdioServerTransport.onmessage → SSEClientTransport.send → POST /message
- *   Pharaoh → SSE stream → SSEClientTransport.onmessage → StdioServerTransport.send → stdout
- *
- * CRITICAL ordering: SSE must be connected BEFORE stdio starts reading stdin.
- * Otherwise the MCP `initialize` message arrives before the remote transport is ready,
- * gets permanently lost ("send error — Not connected"), and the client times out.
- *
- * On SSE disconnect, attempts reconnect with exponential backoff (5 retries, ~62s total).
- * Throws TokenExpiredError on 401, TenantSuspendedError on 403.
+ * @deprecated Session C will call ProxyServer / startInSseMode directly.
  */
 export async function startProxy(sseUrl, token) {
-    const stdio = new StdioServerTransport();
-    let sse = createSSETransport(sseUrl, token);
-    let reconnectAttempt = 0;
-    let stdioStarted = false;
-    /** Wire up bidirectional message relay between the two transports. */
-    function bridge(sseTransport) {
-        stdio.onmessage = (msg) => {
-            sseTransport.send(msg).catch((err) => {
-                process.stderr.write(`Pharaoh: send error — ${err instanceof Error ? err.message : String(err)}\n`);
-            });
-        };
-        sseTransport.onmessage = (msg) => {
-            stdio.send(msg).catch((err) => {
-                process.stderr.write(`Pharaoh: stdout error — ${err instanceof Error ? err.message : String(err)}\n`);
-            });
-        };
+    // Lazy imports to keep module load order clean — backend.ts imports from
+    // proxy.ts for the typed errors and classifier above, so a top-level
+    // import would create a cycle.
+    const { createSseBackend } = await import("./backend.js");
+    const { ProxyServer } = await import("./proxy-server.js");
+    const backend = createSseBackend(sseUrl, token);
+    const proxy = new ProxyServer(backend);
+    await proxy.start();
+    // Block on the SSE reconnect loop — matches the original semantics of
+    // startProxy, which resolved only when the connection terminated.
+    try {
+        await backend.waitForExit();
     }
-    // Connect SSE with reconnect loop — stdio starts AFTER first successful connection
-    await connectWithReconnect();
-    /** Attempt SSE connection with exponential backoff on failure. */
-    async function connectWithReconnect() {
-        while (reconnectAttempt <= BACKOFF_MS.length) {
-            try {
-                if (reconnectAttempt > 0) {
-                    const delay = BACKOFF_MS[reconnectAttempt - 1];
-                    process.stderr.write(`Pharaoh: reconnecting in ${delay / 1000}s (attempt ${reconnectAttempt}/${BACKOFF_MS.length})...\n`);
-                    await sleep(delay);
-                    sse = createSSETransport(sseUrl, token);
-                }
-                await sse.start();
-                reconnectAttempt = 0; // Reset on successful connection
-                // Bridge AFTER SSE is connected — messages can now be forwarded
-                bridge(sse);
-                // Start stdio AFTER first SSE connection — prevents initialize race
-                if (!stdioStarted) {
-                    process.stderr.write("Pharaoh: connected\n");
-                    await stdio.start();
-                    stdioStarted = true;
-                }
-                else {
-                    process.stderr.write("Pharaoh: reconnected\n");
-                }
-                // Wait for close — this promise resolves when SSE disconnects
-                await new Promise((resolve, reject) => {
-                    sse.onclose = () => resolve();
-                    sse.onerror = (err) => {
-                        try {
-                            classifySSEError(err);
-                        }
-                        catch (typed) {
-                            reject(typed);
-                            return;
-                        }
-                        // Non-fatal error — explicitly close the transport to kill
-                        // EventSource's built-in auto-reconnect. Without this, EventSource
-                        // reconnects every ~3s, creating ghost sessions on the server
-                        // (100+ auth successes, zero tool calls completing).
-                        // close() fires onclose which resolves this promise, handing
-                        // control back to the proxy's backoff loop.
-                        sse.close().catch(() => { });
-                    };
-                });
-                // SSE closed — attempt reconnect
-                reconnectAttempt++;
-            }
-            catch (err) {
-                if (err instanceof TokenExpiredError || err instanceof TenantSuspendedError) {
-                    await stdio.close().catch(() => { });
-                    throw err;
-                }
-                reconnectAttempt++;
-                if (reconnectAttempt > BACKOFF_MS.length) {
-                    process.stderr.write("Pharaoh: max reconnect attempts reached — exiting\n");
-                    await stdio.close().catch(() => { });
-                    throw new Error("SSE connection failed after maximum retries");
-                }
-            }
-        }
+    finally {
+        await proxy.stop().catch(() => { });
     }
 }
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}

package/dist/refresh.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Silent access-token renewal via OAuth2 refresh grant.
+ *
+ * Called at proxy startup (when access is expired but refresh is valid) and on
+ * mid-session 401 (from proxy.ts TokenExpiredError handler). Success writes new
+ * credentials to disk. Failure returns a classified action so the caller can
+ * decide whether to delete credentials or preserve them for a later retry.
+ */
+import type { Credentials } from "./credentials.js";
+/** Outcome of a refresh attempt. */
+export type RefreshOutcome = {
+    ok: true;
+    creds: Credentials;
+} | {
+    ok: false;
+    action: RefreshFailureAction;
+    message: string;
+};
+/**
+ * How the caller should handle a failed refresh.
+ *
+ * - `reauth`:    server says the refresh token is dead (revoked, expired past
+ *                grace, user removed from org). Delete credentials and prompt
+ *                for re-auth on next start.
+ * - `preserve`:  transient server/network failure (503, fetch error). Keep the
+ *                credentials file intact — the next startup may succeed.
+ * - `transient`: unexpected response shape we can't confidently classify. Keep
+ *                credentials, exit with a diagnostic message. If this branch
+ *                fires often in production, tighten classification.
+ */
+export type RefreshFailureAction = "reauth" | "preserve" | "transient";
+/**
+ * Attempt to renew the access token using the stored refresh token.
+ *
+ * On success: writes new credentials to disk and returns them.
+ * On failure: returns a classified action — caller owns the creds lifecycle.
+ *
+ * @param creds   current (possibly-expired-access) credentials
+ * @param server  Pharaoh server base URL (e.g. "https://mcp.pharaoh.so")
+ * @param path    optional custom credentials path (for tests)
+ */
+export declare function refreshIfNeeded(creds: Credentials, server: string, path?: string): Promise<RefreshOutcome>;
+/**
+ * Read credentials from disk and refresh if the access token is expired.
+ *
+ * Returns:
+ * - `null` if no credentials exist (caller should show re-auth instructions)
+ * - `RefreshOutcome` with `ok: true` if creds are fresh or refresh succeeded
+ * - `RefreshOutcome` with `ok: false` if refresh failed (check `.action`)
+ *
+ * Intended use: called at proxy startup to replace the current "die if expired"
+ * branch in index.ts.
+ */
+export declare function loadAndRefresh(server: string, path?: string): Promise<RefreshOutcome | null>;

package/dist/refresh.js

@@ -0,0 +1,157 @@
+import { isRefreshExpired, readCredentials, writeCredentials } from "./credentials.js";
+/** Classify a non-200 response from the /token refresh endpoint. */
+function classifyRefreshError(status, body) {
+    // 503 or network — the server or GitHub API had a blip. Keep the refresh
+    // token; the next proxy spawn will retry. Blowing away good creds on a
+    // transient failure is exactly the "forced re-auth" pattern we're trying
+    // to eliminate (VestaTech-BV churn was this exact shape).
+    if (status >= 500)
+        return "preserve";
+    // 400 invalid_grant covers all three terminal cases from the server:
+    //   • user removed from GitHub org (not_member)
+    //   • session unreadable / pre-GCM CBC (reauth_required)
+    //   • refresh token expired or rotated out of grace window
+    // All three mean: the creds cannot produce a working session. Delete them
+    // so the next spawn shows the re-auth prompt instead of looping forever.
+    if (status === 400 && body.error === "invalid_grant")
+        return "reauth";
+    // Anything else — 401 without invalid_grant, 403, 404, parse error, etc.
+    // Don't delete creds (might be recoverable), but don't pretend it's
+    // transient either. Log-friendly exit, preserve creds, let the next spawn
+    // retry. If this case fires in practice, we'll see it in logs and tighten
+    // the classification.
+    return "transient";
+}
+/**
+ * Attempt to renew the access token using the stored refresh token.
+ *
+ * On success: writes new credentials to disk and returns them.
+ * On failure: returns a classified action — caller owns the creds lifecycle.
+ *
+ * @param creds   current (possibly-expired-access) credentials
+ * @param server  Pharaoh server base URL (e.g. "https://mcp.pharaoh.so")
+ * @param path    optional custom credentials path (for tests)
+ */
+export async function refreshIfNeeded(creds, server, path) {
+    // Guard: refresh token itself expired. No point hitting the server — the
+    // grant will fail with invalid_grant. Short-circuit to reauth.
+    if (isRefreshExpired(creds)) {
+        return {
+            ok: false,
+            action: "reauth",
+            message: "Refresh token expired",
+        };
+    }
+    let res;
+    try {
+        // POST to /device/token-refresh — RFC 8628 device-flow refresh. Distinct
+        // from /token (browser OAuth) because device flow has no client_id —
+        // the refresh_token itself is the credential.
+        res = await fetch(`${server}/device/token-refresh`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                refresh_token: creds.refresh_token,
+            }),
+        });
+    }
+    catch (err) {
+        // Network failure — keep creds, let the next spawn retry.
+        return {
+            ok: false,
+            action: "preserve",
+            message: `Network error: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    if (res.ok) {
+        // Parse body inside try/catch — a 200 response with truncated/malformed
+        // JSON (CDN/proxy mangling, connection drop mid-stream) would otherwise
+        // throw SyntaxError out of refreshIfNeeded and hit main()'s redact-only
+        // catch, giving the user no classification.
+        let token;
+        try {
+            token = (await res.json());
+        }
+        catch (err) {
+            return {
+                ok: false,
+                action: "transient",
+                message: `Malformed JSON in refresh response: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+        if (!token.access_token ||
+            !token.refresh_token ||
+            !token.expires_in ||
+            !token.refresh_token_expires_in) {
+            // Server OK'd the request but returned an incomplete body. Treat as
+            // transient rather than reauth — the creds we have are still valid.
+            // (0 is not a legal OAuth2 TTL per RFC 6749; a server returning 0 is
+            // a regression, not a signal to delete credentials.)
+            return {
+                ok: false,
+                action: "transient",
+                message: "Refresh response missing required fields",
+            };
+        }
+        const now = Date.now();
+        const newCreds = {
+            ...creds,
+            access_token: token.access_token,
+            refresh_token: token.refresh_token,
+            expires_at: new Date(now + token.expires_in * 1000).toISOString(),
+            refresh_expires_at: new Date(now + token.refresh_token_expires_in * 1000).toISOString(),
+            expires_in: token.expires_in,
+        };
+        // Persist new credentials. If the disk write fails (EACCES, ENOSPC,
+        // EROFS), report `preserve` — the server already rotated the token
+        // server-side, so the old refresh_token is now in grace. Returning
+        // `ok: true` here would mean the next spawn reads stale creds and
+        // attempts to refresh with a rotated token, forcing an unnecessary
+        // re-auth. Preserving lets the user fix the disk issue and retry
+        // within the grace window.
+        try {
+            writeCredentials(newCreds, path);
+        }
+        catch (err) {
+            return {
+                ok: false,
+                action: "preserve",
+                message: `Could not persist refreshed credentials: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+        return { ok: true, creds: newCreds };
+    }
+    let body = {};
+    try {
+        body = (await res.json());
+    }
+    catch {
+        // ALLOWED-CATCH: non-JSON body — classify on status alone
+    }
+    const action = classifyRefreshError(res.status, body);
+    const message = body.error_description ?? body.error ?? `HTTP ${res.status} ${res.statusText}`;
+    return { ok: false, action, message };
+}
+/**
+ * Read credentials from disk and refresh if the access token is expired.
+ *
+ * Returns:
+ * - `null` if no credentials exist (caller should show re-auth instructions)
+ * - `RefreshOutcome` with `ok: true` if creds are fresh or refresh succeeded
+ * - `RefreshOutcome` with `ok: false` if refresh failed (check `.action`)
+ *
+ * Intended use: called at proxy startup to replace the current "die if expired"
+ * branch in index.ts.
+ */
+export async function loadAndRefresh(server, path) {
+    const creds = readCredentials(path);
+    if (!creds)
+        return null;
+    // Access token still valid — no refresh needed.
+    const expiresAt = new Date(creds.expires_at).getTime();
+    const bufferMs = creds.expires_in * 1000 * 0.1;
+    if (Date.now() < expiresAt - bufferMs) {
+        return { ok: true, creds };
+    }
+    return refreshIfNeeded(creds, server, path);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pharaoh-so/mcp",
   "mcpName": "so.pharaoh/pharaoh",
-  "version": "0.3.21",
+  "version": "0.3.23",
   "description": "MCP proxy for Pharaoh — maps codebases into queryable knowledge graphs for AI agents. Enables Claude Code in headless environments (VPS, SSH, CI) via device flow auth.",
   "type": "module",
   "main": "dist/index.js",