@pharaoh-so/mcp 0.3.37 → 0.3.38

package/dist/credentials.d.ts

@@ -30,9 +30,20 @@ export interface Credentials {
 export declare function readCredentials(path?: string): Credentials | null;
 /**
  * Write credentials to disk with restrictive permissions.
- * Creates the parent directory (0700) if it doesn't exist.
+ * Creates the parent directory (0700) if it doesn't exist. Writes a 0600 temp
+ * file and renames it over the target, so a reader never sees a half-written file.
  */
 export declare function writeCredentials(creds: Credentials, path?: string): void;
+/**
+ * Take the lock that serializes token refreshes across every proxy on this
+ * machine. Waits while another proxy holds it; breaks a lock older than
+ * LOCK_STALE_MS (its owner died mid-refresh).
+ *
+ * @param path - Credentials file the lock guards (lock lives at `${path}.lock`).
+ * @returns A release function that removes the lock only if this caller still owns it.
+ * @throws If the lock stays held for LOCK_WAIT_MS, or a stale lock can't be removed.
+ */
+export declare function acquireCredentialsLock(path?: string): Promise<() => void>;
 /** Delete the credential file. No-op if it doesn't exist. */
 export declare function deleteCredentials(path?: string): void;
 /**

package/dist/credentials.js

@@ -1,10 +1,24 @@
 /**
  * Credential storage for Pharaoh MCP proxy — persists device flow tokens to ~/.pharaoh/credentials.json.
- * File permissions: 0600 (credentials.json), 0700 (~/.pharaoh/).
+ * File permissions: 0600 (credentials.json, its lock and temp files), 0700 (~/.pharaoh/).
+ *
+ * Every proxy on a machine shares this file and the one OAuth session behind it, so
+ * refreshes take a lock (acquireCredentialsLock) and writes are atomic.
  */
-import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+/**
+ * A lock older than this was left by a proxy that died mid-refresh; it may be
+ * broken. Above refresh.ts REFRESH_TIMEOUT_MS, so a live refresh never looks stale.
+ */
+const LOCK_STALE_MS = 15_000;
+/** How long to wait for another proxy's refresh — longer than LOCK_STALE_MS, so a dead holder's lock gets broken. */
+const LOCK_WAIT_MS = 20_000;
+/** How often to check whether the lock is free. */
+const LOCK_POLL_MS = 50;
 /**
  * Current credential schema version. v2 adds refresh_token + refresh_expires_at
  * so the proxy can silently renew access tokens. v1 files parse as null, which
@@ -33,14 +47,112 @@ export function readCredentials(path = CREDENTIALS_PATH) {
 }
 /**
  * Write credentials to disk with restrictive permissions.
- * Creates the parent directory (0700) if it doesn't exist.
+ * Creates the parent directory (0700) if it doesn't exist. Writes a 0600 temp
+ * file and renames it over the target, so a reader never sees a half-written file.
  */
 export function writeCredentials(creds, path = CREDENTIALS_PATH) {
+    ensureDir(path);
+    const tmp = `${path}.${randomUUID()}.tmp`;
+    try {
+        writeFileSync(tmp, JSON.stringify(creds, null, "\t"), { mode: 0o600 });
+        renameSync(tmp, path);
+    }
+    catch (err) {
+        rmSync(tmp, { force: true });
+        throw err;
+    }
+}
+/**
+ * Take the lock that serializes token refreshes across every proxy on this
+ * machine. Waits while another proxy holds it; breaks a lock older than
+ * LOCK_STALE_MS (its owner died mid-refresh).
+ *
+ * @param path - Credentials file the lock guards (lock lives at `${path}.lock`).
+ * @returns A release function that removes the lock only if this caller still owns it.
+ * @throws If the lock stays held for LOCK_WAIT_MS, or a stale lock can't be removed.
+ */
+export async function acquireCredentialsLock(path = CREDENTIALS_PATH) {
+    ensureDir(path);
+    const lockPath = `${path}.lock`;
+    const owner = `${process.pid}:${randomUUID()}`;
+    const deadline = Date.now() + LOCK_WAIT_MS;
+    for (;;) {
+        try {
+            writeFileSync(lockPath, owner, { flag: "wx", mode: 0o600 });
+            return () => {
+                try {
+                    releaseLock(lockPath, owner);
+                }
+                catch (err) {
+                    // The refresh is done; a lock left behind goes stale and is broken later.
+                    process.stderr.write(`Pharaoh: couldn't remove ${lockPath}: ${err instanceof Error ? err.message : String(err)}\n`);
+                }
+            };
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+        }
+        // Remove only the lock judged stale: another waiter may already have broken
+        // it and taken a fresh one, which an unconditional unlink would delete.
+        const holder = lockHolder(lockPath);
+        if (holder !== null && lockAgeMs(lockPath) > LOCK_STALE_MS) {
+            releaseLock(lockPath, holder);
+            continue;
+        }
+        if (Date.now() >= deadline) {
+            throw new Error(`Another Pharaoh process has held ${lockPath} for over ${LOCK_WAIT_MS / 1000}s`);
+        }
+        await sleep(LOCK_POLL_MS);
+    }
+}
+/** The lock's owner tag, or null when no lock exists. */
+function lockHolder(lockPath) {
+    try {
+        return readFileSync(lockPath, "utf-8");
+    }
+    catch (err) {
+        if (!isMissing(err))
+            throw err;
+        return null; // released between our create attempt and this read — retry immediately
+    }
+}
+/**
+ * Remove the lock file — only while it still holds `owner`.
+ * @throws When the lock exists but can't be read or removed (permissions).
+ */
+function releaseLock(lockPath, owner) {
+    try {
+        if (readFileSync(lockPath, "utf-8") !== owner)
+            return;
+        unlinkSync(lockPath);
+    }
+    catch (err) {
+        if (!isMissing(err))
+            throw err; // already gone — nothing to release
+    }
+}
+/** True when a filesystem error means the file isn't there — the only one the lock helpers expect. */
+function isMissing(err) {
+    return err.code === "ENOENT";
+}
+/** Milliseconds since the lock was written; 0 if it vanished meanwhile. */
+function lockAgeMs(lockPath) {
+    try {
+        return Date.now() - statSync(lockPath).mtimeMs;
+    }
+    catch (err) {
+        if (!isMissing(err))
+            throw err;
+        return 0; // released between our create attempt and this stat — retry immediately
+    }
+}
+/** Create the credentials directory (0700) if it doesn't exist. */
+function ensureDir(path) {
     const dir = dirname(path);
     if (!existsSync(dir)) {
         mkdirSync(dir, { recursive: true, mode: 0o700 });
     }
-    writeFileSync(path, JSON.stringify(creds, null, "\t"), { mode: 0o600 });
 }
 /** Delete the credential file. No-op if it doesn't exist. */
 export function deleteCredentials(path = CREDENTIALS_PATH) {

package/dist/gateway.js

@@ -17,6 +17,7 @@
 import { openBrowser, pollOnce, requestDeviceCode, } from "./auth.js";
 import { readCredentials, writeCredentials } from "./credentials.js";
 import { resolveSseUrl, tokenToCredentials } from "./helpers.js";
+import { refreshIfNeeded } from "./refresh.js";
 /**
  * True when the credentials' access token is at or past its expiry.
  *
@@ -146,6 +147,13 @@ export function createGateway(opts) {
         return state.response;
     }
     async function handleToolCall() {
+        // Another process may have signed in since this proxy started — a sibling
+        // proxy finishing device flow, or `npx @pharaoh-so/mcp` in a terminal.
+        // Use those credentials rather than asking the user to sign in again.
+        if (await useStoredCredentials()) {
+            pending = null;
+            return null;
+        }
         // No active cycle — start one.
         if (pending === null) {
             return startNewCycle();
@@ -174,6 +182,26 @@ export function createGateway(opts) {
         lastCreds = creds;
         return !isAccessExpired(creds, now);
     }
+    /**
+     * True when credentials on disk are usable now: valid as stored, or
+     * refreshed successfully. Sets lastCreds to whatever will be used.
+     */
+    async function useStoredCredentials() {
+        if (hasValidCredentials())
+            return true;
+        // Read the file again rather than reuse lastCreds: a rejected refresh
+        // deletes the file, and its dead token must not be sent on every call.
+        const stored = readCredentials(opts.credentialsPath);
+        if (!stored)
+            return false;
+        const refreshed = await refreshIfNeeded(stored, opts.server, opts.credentialsPath);
+        if (!refreshed.ok) {
+            process.stderr.write(`Pharaoh: stored credentials unusable (${refreshed.action}) — ${refreshed.message}\n`);
+            return false;
+        }
+        lastCreds = refreshed.creds;
+        return true;
+    }
     function getCredentials() {
         return lastCreds;
     }

package/dist/index.js

@@ -14,7 +14,7 @@
  */
 import { pollForToken, printActivationPrompt, printAuthSuccess, requestDeviceCode, } from "./auth.js";
 import { AuthRequiredBackend, createSseBackend } from "./backend.js";
-import { deleteCredentials, readCredentials, writeCredentials } from "./credentials.js";
+import { deleteCredentials, readCredentials, writeCredentials, } from "./credentials.js";
 import { createGateway } from "./gateway.js";
 import { formatTtl, parseArgs, printLines, printUsage, resolveSseUrl, tokenToCredentials, } from "./helpers.js";
 import { runInstallSkills } from "./install-skills.js";
@@ -116,11 +116,8 @@ async function main() {
     // device flow, then swap to SSE via the onAuthorized callback.
     const needsAuth = outcome === null || (!outcome.ok && outcome.action === "reauth");
     if (needsAuth) {
-        // If we reached here via a rejected refresh, delete the stale creds
-        // file so the gateway's internal readCredentials() doesn't pick up the
-        // just-invalidated refresh token on restart.
-        if (outcome && !outcome.ok)
-            deleteCredentials();
+        // A rejected refresh has already removed the stale creds file
+        // (refreshIfNeeded, under the lock) unless another process replaced it.
         // The callback closure captures `proxy` via the destructured `const`
         // binding declared below. The closure is only invoked once authorization
         // completes (after the user's device-flow round trip), long after the
@@ -128,7 +125,7 @@ async function main() {
         const { proxy } = await startInAuthRequiredMode(server, {
             onAuthorized: async (creds) => {
                 printLines("Pharaoh: authenticated — swapping to SSE backend.");
-                await proxy.setBackend(createSseBackend(creds.sse_url, creds.access_token));
+                await useSse(proxy, creds);
             },
         });
         printLines("Pharaoh: awaiting authentication via Claude Code...");
@@ -147,6 +144,7 @@ async function main() {
     // handle any mid-session failures by swapping backends in place.
     const creds = outcome.creds;
     printLines(`Pharaoh: token valid for ${formatTtl(creds.expires_at)} — connecting`);
+    activeCreds = creds;
     const proxy = await startInSseMode(creds);
     await waitForProxyLifetime(proxy, server);
 }
@@ -214,21 +212,22 @@ async function waitForProxyLifetime(proxy, server) {
  * swap-back or process.exit()'d for a non-recoverable case).
  */
 async function recoverFromTokenExpired(proxy, server) {
-    // Re-read creds from disk — the SSE backend doesn't expose its token, and
-    // a prior refresh may have rotated what's on disk. Silent-refresh the
-    // token regardless of the on-disk expiry (the 401 is authoritative: the
-    // server rejected us, so force a round trip).
-    const diskCreds = readCredentials();
-    if (!diskCreds) {
-        // No creds on disk — shouldn't happen mid-session, but if it does,
+    // The rejected token is the one the live backend was built from. Pass
+    // those creds, not a fresh disk read: if another proxy already refreshed
+    // (which is what invalidated ours — the server keeps one access token per
+    // session), refreshIfNeeded sees the newer token on disk and adopts it
+    // instead of refreshing again and invalidating everyone else in turn.
+    const rejected = activeCreds ?? readCredentials();
+    if (!rejected) {
+        // No creds anywhere — shouldn't happen mid-session, but if it does,
         // fall through to auth-required mode to get new ones.
         await swapToAuthRequired(proxy, server);
         return true;
     }
-    const result = await tryMidSessionRefresh(diskCreds, server);
+    const result = await tryMidSessionRefresh(rejected, server);
     if (result.ok) {
         printLines("Pharaoh: token refreshed mid-session — swapping SSE backend");
-        await proxy.setBackend(createSseBackend(result.creds.sse_url, result.creds.access_token));
+        await useSse(proxy, result.creds);
         return true;
     }
     // Branch on the explicit classification returned by tryMidSessionRefresh
@@ -244,6 +243,16 @@ async function recoverFromTokenExpired(proxy, server) {
     printLines(`Pharaoh: mid-session refresh failed (${result.action}) — credentials preserved; restart to retry.`);
     process.exit(1);
 }
+/**
+ * Credentials the live SSE backend was built from. After a 401 these are the
+ * rejected ones — recoverFromTokenExpired compares them with what's on disk.
+ */
+let activeCreds = null;
+/** Point the proxy at a fresh SSE backend for `creds`, remembering which creds it uses. */
+async function useSse(proxy, creds) {
+    activeCreds = creds;
+    await proxy.setBackend(createSseBackend(creds.sse_url, creds.access_token));
+}
 /**
  * Swap the live ProxyServer over to an AuthRequiredBackend, wiring an
  * onAuthorized callback that swaps back to SSE. Used on both mid-session
@@ -258,7 +267,7 @@ async function swapToAuthRequired(proxy, server) {
             return;
         }
         printLines("Pharaoh: re-authenticated — swapping back to SSE backend.");
-        await proxy.setBackend(createSseBackend(fresh.sse_url, fresh.access_token));
+        await useSse(proxy, fresh);
     });
     printLines("Pharaoh: re-authentication required — next tool call will surface the URL.");
     await proxy.setBackend(authBackend);

package/dist/lifecycle.d.ts

@@ -5,7 +5,7 @@
  * booting the full CLI. Imported by main() and exercised as a real runtime
  * dependency — no "test-only exports" here.
  */
-import { type Credentials } from "./credentials.js";
+import type { Credentials } from "./credentials.js";
 import { type RefreshFailureAction } from "./refresh.js";
 /** Discriminated result from tryMidSessionRefresh. */
 export type MidSessionRefreshResult = {
@@ -21,10 +21,15 @@ export type MidSessionRefreshResult = {
  * Returns new credentials on success, or a tagged failure carrying the
  * RefreshFailureAction so the caller can branch on the real classification
  * instead of re-inferring from disk state.
+ *
+ * @param creds - The credentials whose access token the server just rejected.
+ *   When another proxy has already refreshed, its newer credentials come back
+ *   without a second refresh.
  */
 export declare function tryMidSessionRefresh(creds: Credentials, server: string): Promise<MidSessionRefreshResult>;
 /**
  * Handle a failed `loadAndRefresh` at startup. Exits the process with the
- * appropriate message and creds-file state per the classified action.
+ * appropriate message per the classified action. Never deletes credentials:
+ * refreshIfNeeded already did, under the lock, if they were the rejected ones.
  */
 export declare function handleRefreshFailure(action: RefreshFailureAction, message: string): never;

package/dist/lifecycle.js

@@ -1,11 +1,3 @@
-/**
- * Proxy lifecycle helpers — credential state transitions and re-auth messaging.
- *
- * Extracted from index.ts so the branching logic can be unit-tested without
- * booting the full CLI. Imported by main() and exercised as a real runtime
- * dependency — no "test-only exports" here.
- */
-import { deleteCredentials } from "./credentials.js";
 import { NPX_COMMAND, printLines } from "./helpers.js";
 import { refreshIfNeeded } from "./refresh.js";
 /**
@@ -13,6 +5,10 @@ import { refreshIfNeeded } from "./refresh.js";
  * Returns new credentials on success, or a tagged failure carrying the
  * RefreshFailureAction so the caller can branch on the real classification
  * instead of re-inferring from disk state.
+ *
+ * @param creds - The credentials whose access token the server just rejected.
+ *   When another proxy has already refreshed, its newer credentials come back
+ *   without a second refresh.
  */
 export async function tryMidSessionRefresh(creds, server) {
     const outcome = await refreshIfNeeded(creds, server);
@@ -20,8 +16,9 @@ export async function tryMidSessionRefresh(creds, server) {
         return { ok: true, creds: outcome.creds };
     // Log the failure reason before the caller decides what to do.
     if (outcome.action === "reauth") {
+        // refreshIfNeeded already removed the rejected credentials (if no other
+        // process had replaced them) — deletion has one owner, under the lock.
         printLines("Pharaoh: refresh rejected — re-authentication required.", `  ${NPX_COMMAND}`, "");
-        deleteCredentials();
     }
     else {
         // preserve / transient — keep creds, print diagnostic + next-step hint so
@@ -32,11 +29,11 @@ export async function tryMidSessionRefresh(creds, server) {
 }
 /**
  * Handle a failed `loadAndRefresh` at startup. Exits the process with the
- * appropriate message and creds-file state per the classified action.
+ * appropriate message per the classified action. Never deletes credentials:
+ * refreshIfNeeded already did, under the lock, if they were the rejected ones.
  */
 export function handleRefreshFailure(action, message) {
     if (action === "reauth") {
-        deleteCredentials();
         printLines("Pharaoh: session no longer valid — re-authenticate.", `  ${NPX_COMMAND}`, "");
         process.exit(1);
     }

package/dist/refresh.d.ts

@@ -4,7 +4,13 @@
  * 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.
+ * decide whether to preserve credentials for a later retry or re-authenticate.
+ *
+ * Every proxy on the machine shares one credentials file and one OAuth session,
+ * and the server keeps one access token per session — each refresh invalidates
+ * every other proxy's token. So refreshes run one at a time under the
+ * credentials lock, and a proxy whose token was replaced by another proxy's
+ * refresh adopts the new credentials instead of refreshing again.
  */
 import type { Credentials } from "./credentials.js";
 /** Outcome of a refresh attempt. */
@@ -30,16 +36,22 @@ export type RefreshOutcome = {
  */
 export type RefreshFailureAction = "reauth" | "preserve" | "transient";
 /**
- * Attempt to renew the access token using the stored refresh token.
+ * Renew the access token, coordinating with every other proxy on the machine.
  *
- * On success: writes new credentials to disk and returns them.
- * On failure: returns a classified action — caller owns the creds lifecycle.
+ * Under the credentials lock: if the file already holds a different, unexpired
+ * access token than `creds` (another proxy refreshed, or someone signed in), those
+ * credentials are returned without a request. Otherwise the refresh grant runs.
+ * On `reauth`, the file is deleted only if it still holds the rejected refresh
+ * token; a file rewritten while the request was in flight is adopted instead.
  *
- * @param creds   current (possibly-expired-access) credentials
+ * @param creds   the credentials the caller was using (possibly access-expired or rejected)
  * @param server  Pharaoh server base URL (e.g. "https://mcp.pharaoh.so")
  * @param path    optional custom credentials path (for tests)
+ * @param timeoutMs how long the refresh request may take (for tests)
+ * @returns New or adopted credentials, or a classified failure. A lock held by
+ *   another proxy for too long is `transient` (credentials untouched).
  */
-export declare function refreshIfNeeded(creds: Credentials, server: string, path?: string): Promise<RefreshOutcome>;
+export declare function refreshIfNeeded(creds: Credentials, server: string, path?: string, timeoutMs?: number): Promise<RefreshOutcome>;
 /**
  * Read credentials from disk and refresh if the access token is expired.
  *

package/dist/refresh.js

@@ -1,4 +1,4 @@
-import { isRefreshExpired, readCredentials, writeCredentials } from "./credentials.js";
+import { acquireCredentialsLock, deleteCredentials, isExpired, 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
@@ -23,16 +23,64 @@ function classifyRefreshError(status, body) {
     return "transient";
 }
 /**
- * Attempt to renew the access token using the stored refresh token.
+ * Deadline for the refresh request. Kept under the lock's stale age
+ * (credentials.ts LOCK_STALE_MS) so a refresh still in flight is never broken
+ * by another proxy that would then refresh the same token again.
+ */
+const REFRESH_TIMEOUT_MS = 10_000;
+/**
+ * Renew the access token, coordinating with every other proxy on the machine.
  *
- * On success: writes new credentials to disk and returns them.
- * On failure: returns a classified action — caller owns the creds lifecycle.
+ * Under the credentials lock: if the file already holds a different, unexpired
+ * access token than `creds` (another proxy refreshed, or someone signed in), those
+ * credentials are returned without a request. Otherwise the refresh grant runs.
+ * On `reauth`, the file is deleted only if it still holds the rejected refresh
+ * token; a file rewritten while the request was in flight is adopted instead.
  *
- * @param creds   current (possibly-expired-access) credentials
+ * @param creds   the credentials the caller was using (possibly access-expired or rejected)
  * @param server  Pharaoh server base URL (e.g. "https://mcp.pharaoh.so")
  * @param path    optional custom credentials path (for tests)
+ * @param timeoutMs how long the refresh request may take (for tests)
+ * @returns New or adopted credentials, or a classified failure. A lock held by
+ *   another proxy for too long is `transient` (credentials untouched).
+ */
+export async function refreshIfNeeded(creds, server, path, timeoutMs = REFRESH_TIMEOUT_MS) {
+    let release;
+    try {
+        release = await acquireCredentialsLock(path);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            action: "transient",
+            message: err instanceof Error ? err.message : String(err),
+        };
+    }
+    try {
+        const current = readCredentials(path);
+        if (current && current.access_token !== creds.access_token && !isExpired(current)) {
+            return { ok: true, creds: current };
+        }
+        const source = current ?? creds;
+        const outcome = await requestRefresh(source, server, timeoutMs, path);
+        if (outcome.ok || outcome.action !== "reauth")
+            return outcome;
+        const after = readCredentials(path);
+        if (!after || after.refresh_token === source.refresh_token) {
+            deleteCredentials(path);
+            return outcome;
+        }
+        return isExpired(after) ? outcome : { ok: true, creds: after };
+    }
+    finally {
+        release();
+    }
+}
+/**
+ * One refresh-grant round trip: POST the refresh token, persist and return the
+ * new credentials on success, or classify the failure. Caller holds the lock.
  */
-export async function refreshIfNeeded(creds, server, path) {
+async function requestRefresh(creds, server, timeoutMs, 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)) {
@@ -53,6 +101,7 @@ export async function refreshIfNeeded(creds, server, path) {
             body: JSON.stringify({
                 refresh_token: creds.refresh_token,
             }),
+            signal: AbortSignal.timeout(timeoutMs),
         });
     }
     catch (err) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pharaoh-so/mcp",
   "mcpName": "so.pharaoh/pharaoh",
-  "version": "0.3.37",
+  "version": "0.3.38",
   "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",