@pharaoh-so/mcp 0.1.0

package/README.md

@@ -0,0 +1,33 @@
+# @pharaoh-so/mcp
+
+Stdio-to-SSE proxy for [Pharaoh](https://pharaoh.so) — enables Claude Code in headless environments (VPS, SSH, CI) where a browser isn't available for OAuth.
+
+## Quick Start
+
+```bash
+claude mcp add pharaoh -- npx @pharaoh-so/mcp
+```
+
+On first run, the proxy shows a device code and URL. Open the URL on any device (phone, laptop) to authorize. The proxy stores credentials at `~/.pharaoh/credentials.json` and reuses them until they expire (7 days).
+
+## How It Works
+
+```
+Claude Code ← stdio → @pharaoh-so/mcp ← SSE/HTTP → mcp.pharaoh.so
+```
+
+The proxy presents itself as an MCP server to Claude Code via stdio, and relays all messages to the remote Pharaoh server over SSE. Authentication uses the RFC 8628 device authorization flow — no browser required on the machine running Claude Code.
+
+## Options
+
+```
+--server <url>  Pharaoh server URL (default: https://mcp.pharaoh.so)
+--logout        Clear stored credentials and exit
+--help          Show help
+```
+
+## Security
+
+- Credentials stored with `0600` permissions (owner-read/write only)
+- Only use trusted server URLs — the proxy sends your auth token to the configured server
+- Tokens expire after 7 days; re-authorization is automatic

package/dist/auth.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Device flow client for Pharaoh MCP proxy (RFC 8628).
+ * All user-visible output goes to stderr — stdout is reserved for JSON-RPC.
+ */
+/** Response from POST /device. */
+export interface DeviceCodeResponse {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete: string;
+    expires_in: number;
+    interval: number;
+}
+/** Successful response from POST /device/token. */
+export interface TokenResponse {
+    access_token: string;
+    token_type: string;
+    expires_in: number;
+    sse_url: string;
+    github_login?: string;
+    tenant_name?: string;
+    repos?: string[];
+    provisional?: boolean;
+    install_url?: string;
+}
+/**
+ * Request a device code from the Pharaoh server (RFC 8628 §3.1).
+ * Returns the device code, user code, and verification URIs.
+ */
+export declare function requestDeviceCode(baseUrl: string): Promise<DeviceCodeResponse>;
+/**
+ * Poll for device authorization completion (RFC 8628 §3.5).
+ * Blocks until the user authorizes, the code expires, or an error occurs.
+ * Adds 1s jitter to the server-specified interval to avoid thundering herd.
+ */
+export declare function pollForToken(baseUrl: string, deviceCode: string, interval: number): Promise<TokenResponse>;
+/**
+ * Print the device activation prompt to stderr.
+ * Shows the user code and verification URI in a visible box.
+ */
+export declare function printActivationPrompt(userCode: string, verificationUri: string): void;
+/**
+ * Print authentication success message to stderr.
+ */
+export declare function printAuthSuccess(login: string | null, tenant: string | null, repoCount: number): void;

package/dist/auth.js

@@ -0,0 +1,93 @@
+/**
+ * Device flow client for Pharaoh MCP proxy (RFC 8628).
+ * All user-visible output goes to stderr — stdout is reserved for JSON-RPC.
+ */
+/**
+ * Request a device code from the Pharaoh server (RFC 8628 §3.1).
+ * Returns the device code, user code, and verification URIs.
+ */
+export async function requestDeviceCode(baseUrl) {
+    const res = await fetch(`${baseUrl}/device`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({}),
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new Error(`Device code request failed (${res.status}): ${text}`);
+    }
+    return (await res.json());
+}
+/**
+ * Poll for device authorization completion (RFC 8628 §3.5).
+ * Blocks until the user authorizes, the code expires, or an error occurs.
+ * Adds 1s jitter to the server-specified interval to avoid thundering herd.
+ */
+export async function pollForToken(baseUrl, deviceCode, interval) {
+    const grantType = "urn:ietf:params:oauth:grant-type:device_code";
+    while (true) {
+        // Wait interval + 0–1s jitter before each poll
+        const jitterMs = Math.random() * 1000;
+        await sleep(interval * 1000 + jitterMs);
+        const res = await fetch(`${baseUrl}/device/token`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ device_code: deviceCode, grant_type: grantType }),
+        });
+        if (res.ok) {
+            return (await res.json());
+        }
+        const body = (await res.json().catch(() => ({ error: "unknown" })));
+        if (body.error === "authorization_pending") {
+            continue;
+        }
+        if (body.error === "slow_down") {
+            // RFC 8628 §3.5: increase interval by 5 seconds
+            interval += 5;
+            continue;
+        }
+        if (body.error === "expired_token") {
+            throw new Error("Device code expired. Please try again.");
+        }
+        if (body.error === "access_denied") {
+            throw new Error("Authorization was denied.");
+        }
+        throw new Error(`Device token error: ${body.error} — ${body.error_description ?? ""}`);
+    }
+}
+/**
+ * Print the device activation prompt to stderr.
+ * Shows the user code and verification URI in a visible box.
+ */
+export function printActivationPrompt(userCode, verificationUri) {
+    const lines = [
+        "",
+        "┌───────────────────────────────────────────┐",
+        "│  Pharaoh — Device Authorization            │",
+        "│                                            │",
+        `│  Code:  ${userCode.padEnd(33)}│`,
+        `│  URL:   ${verificationUri.padEnd(33)}│`,
+        "│                                            │",
+        "│  Open the URL and enter the code to sign   │",
+        "│  in. You can do this on any device.        │",
+        "└───────────────────────────────────────────┘",
+        "",
+    ];
+    process.stderr.write(lines.join("\n") + "\n");
+}
+/**
+ * Print authentication success message to stderr.
+ */
+export function printAuthSuccess(login, tenant, repoCount) {
+    const parts = ["Pharaoh: authenticated"];
+    if (login)
+        parts.push(`as ${login}`);
+    if (tenant)
+        parts.push(`(${tenant})`);
+    parts.push(`— ${repoCount} repo${repoCount === 1 ? "" : "s"} connected`);
+    process.stderr.write(`${parts.join(" ")}\n`);
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"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"}

package/dist/credentials.d.ts

@@ -0,0 +1,33 @@
+/** Current credential schema version — bump when the format changes. */
+declare const SCHEMA_VERSION = 1;
+/** Stored credential shape. */
+export interface Credentials {
+    version: typeof SCHEMA_VERSION;
+    access_token: string;
+    /** ISO 8601 timestamp when the token expires. */
+    expires_at: string;
+    /** Original TTL in seconds (from the token response). */
+    expires_in: number;
+    sse_url: string;
+    github_login: string | null;
+    tenant_name: string | null;
+    repos: string[];
+}
+/**
+ * Read and parse stored credentials. Returns null if missing, unreadable,
+ * malformed, or wrong schema version.
+ */
+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.
+ */
+export declare function writeCredentials(creds: Credentials, path?: string): void;
+/** Delete the credential file. No-op if it doesn't exist. */
+export declare function deleteCredentials(path?: string): void;
+/**
+ * Check if credentials are expired or within 10% of expiry.
+ * The 10% buffer prevents connecting with a token that will expire mid-session.
+ */
+export declare function isExpired(creds: Credentials): boolean;
+export {};

package/dist/credentials.js

@@ -0,0 +1,73 @@
+/**
+ * Credential storage for Pharaoh MCP proxy — persists device flow tokens to ~/.pharaoh/credentials.json.
+ * File permissions: 0600 (credentials.json), 0700 (~/.pharaoh/).
+ */
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+/** Current credential schema version — bump when the format changes. */
+const SCHEMA_VERSION = 1;
+/** Default credential file path. */
+const CREDENTIALS_PATH = join(homedir(), ".pharaoh", "credentials.json");
+/**
+ * Read and parse stored credentials. Returns null if missing, unreadable,
+ * malformed, or wrong schema version.
+ */
+export function readCredentials(path = CREDENTIALS_PATH) {
+    try {
+        const raw = readFileSync(path, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (!isValidCredentials(parsed))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write credentials to disk with restrictive permissions.
+ * Creates the parent directory (0700) if it doesn't exist.
+ */
+export function writeCredentials(creds, path = CREDENTIALS_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) {
+    try {
+        unlinkSync(path);
+    }
+    catch {
+        // File doesn't exist — nothing to delete
+    }
+}
+/**
+ * Check if credentials are expired or within 10% of expiry.
+ * The 10% buffer prevents connecting with a token that will expire mid-session.
+ */
+export function isExpired(creds) {
+    const expiresAt = new Date(creds.expires_at).getTime();
+    if (Number.isNaN(expiresAt))
+        return true;
+    const now = Date.now();
+    const totalTtlMs = creds.expires_in * 1000;
+    const bufferMs = totalTtlMs * 0.1;
+    return now >= expiresAt - bufferMs;
+}
+/** Type guard for valid credential objects. */
+function isValidCredentials(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const obj = value;
+    return (obj.version === SCHEMA_VERSION &&
+        typeof obj.access_token === "string" &&
+        typeof obj.expires_at === "string" &&
+        typeof obj.expires_in === "number" &&
+        typeof obj.sse_url === "string" &&
+        Array.isArray(obj.repos));
+}
+//# sourceMappingURL=credentials.js.map

package/dist/credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.js","sourceRoot":"","sources":["../src/credentials.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACzF,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAE1C,wEAAwE;AACxE,MAAM,cAAc,GAAG,CAAC,CAAC;AAgBzB,oCAAoC;AACpC,MAAM,gBAAgB,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,UAAU,EAAE,kBAAkB,CAAC,CAAC;AAEzE;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,IAAI,GAAG,gBAAgB;IACtD,IAAI,CAAC;QACJ,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACxC,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACxC,IAAI,CAAC,kBAAkB,CAAC,MAAM,CAAC;YAAE,OAAO,IAAI,CAAC;QAC7C,OAAO,MAAM,CAAC;IACf,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,IAAI,CAAC;IACb,CAAC;AACF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAkB,EAAE,IAAI,GAAG,gBAAgB;IAC3E,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACtB,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAClD,CAAC;IACD,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;AACzE,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,iBAAiB,CAAC,IAAI,GAAG,gBAAgB;IACxD,IAAI,CAAC;QACJ,UAAU,CAAC,IAAI,CAAC,CAAC;IAClB,CAAC;IAAC,MAAM,CAAC;QACR,yCAAyC;IAC1C,CAAC;AACF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,KAAkB;IAC3C,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,OAAO,EAAE,CAAC;IACvD,IAAI,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC;QAAE,OAAO,IAAI,CAAC;IAEzC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,MAAM,UAAU,GAAG,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC;IAC3C,MAAM,QAAQ,GAAG,UAAU,GAAG,GAAG,CAAC;IAElC,OAAO,GAAG,IAAI,SAAS,GAAG,QAAQ,CAAC;AACpC,CAAC;AAED,+CAA+C;AAC/C,SAAS,kBAAkB,CAAC,KAAc;IACzC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,GAAG,GAAG,KAAgC,CAAC;IAC7C,OAAO,CACN,GAAG,CAAC,OAAO,KAAK,cAAc;QAC9B,OAAO,GAAG,CAAC,YAAY,KAAK,QAAQ;QACpC,OAAO,GAAG,CAAC,UAAU,KAAK,QAAQ;QAClC,OAAO,GAAG,CAAC,UAAU,KAAK,QAAQ;QAClC,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ;QAC/B,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CACxB,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+/**
+ * @pharaoh-so/mcp — Stdio-to-SSE proxy for headless MCP environments.
+ *
+ * Presents as an MCP server on stdio (for Claude Code) and relays messages
+ * to a remote Pharaoh SSE server. Authenticates via RFC 8628 device flow
+ * so the user can authorize on any device with a browser.
+ */
+import { printActivationPrompt, printAuthSuccess, pollForToken, requestDeviceCode, } from "./auth.js";
+import { deleteCredentials, isExpired, readCredentials, writeCredentials, } from "./credentials.js";
+import { TokenExpiredError, TenantSuspendedError, startProxy } from "./proxy.js";
+const DEFAULT_SERVER = "https://mcp.pharaoh.so";
+/** Parse CLI arguments. */
+function parseArgs() {
+    const args = process.argv.slice(2);
+    let server = DEFAULT_SERVER;
+    let logout = false;
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === "--server" && args[i + 1]) {
+            server = args[i + 1];
+            i++;
+        }
+        else if (args[i] === "--logout") {
+            logout = true;
+        }
+        else if (args[i] === "--help" || args[i] === "-h") {
+            printUsage();
+            process.exit(0);
+        }
+    }
+    // Strip trailing slash
+    server = server.replace(/\/+$/, "");
+    return { server, logout };
+}
+function printUsage() {
+    process.stderr.write([
+        "Usage: pharaoh-mcp [options]",
+        "",
+        "Options:",
+        "  --server <url>  Pharaoh server URL (default: https://mcp.pharaoh.so)",
+        "  --logout        Clear stored credentials and exit",
+        "  --help, -h      Show this help",
+        "",
+        "Add to Claude Code:",
+        "  claude mcp add pharaoh -- npx @pharaoh-so/mcp",
+        "",
+    ].join("\n") + "\n");
+}
+/** Run the device flow and return a token response. */
+async function authenticate(server) {
+    const deviceCode = await requestDeviceCode(server);
+    printActivationPrompt(deviceCode.user_code, deviceCode.verification_uri);
+    return pollForToken(server, deviceCode.device_code, deviceCode.interval);
+}
+/**
+ * Validate that a server-supplied SSE URL shares the same origin as the configured server.
+ * Prevents a compromised auth response from redirecting the Bearer token to an attacker's host.
+ * Falls back to `${server}/sse` if the URL is missing, malformed, or cross-origin.
+ */
+function resolveSseUrl(tokenSseUrl, server) {
+    const fallback = `${server}/sse`;
+    if (!tokenSseUrl)
+        return fallback;
+    try {
+        const sseOrigin = new URL(tokenSseUrl).origin;
+        const serverOrigin = new URL(server).origin;
+        if (sseOrigin !== serverOrigin) {
+            process.stderr.write(`Pharaoh: ignoring cross-origin sse_url (${sseOrigin} ≠ ${serverOrigin})\n`);
+            return fallback;
+        }
+        return tokenSseUrl;
+    }
+    catch {
+        return fallback;
+    }
+}
+/** Convert a token response to storable credentials. */
+function tokenToCredentials(token, sseUrl) {
+    return {
+        version: 1,
+        access_token: token.access_token,
+        expires_at: new Date(Date.now() + token.expires_in * 1000).toISOString(),
+        expires_in: token.expires_in,
+        sse_url: sseUrl,
+        github_login: token.github_login ?? null,
+        tenant_name: token.tenant_name ?? null,
+        repos: token.repos ?? [],
+    };
+}
+/** Format remaining TTL as human-readable string (e.g. "5d 12h"). */
+function formatTtl(expiresAt) {
+    const remainingMs = new Date(expiresAt).getTime() - Date.now();
+    if (remainingMs <= 0)
+        return "expired";
+    const hours = Math.floor(remainingMs / 3_600_000);
+    const days = Math.floor(hours / 24);
+    const remHours = hours % 24;
+    if (days > 0)
+        return `${days}d ${remHours}h`;
+    if (hours > 0)
+        return `${hours}h`;
+    return `${Math.floor(remainingMs / 60_000)}m`;
+}
+async function main() {
+    const { server, logout } = parseArgs();
+    // --logout: clear credentials and exit
+    if (logout) {
+        deleteCredentials();
+        process.stderr.write("Pharaoh: credentials cleared\n");
+        process.exit(0);
+    }
+    let creds = readCredentials();
+    // If we have valid credentials, try to connect directly
+    if (creds && !isExpired(creds)) {
+        process.stderr.write(`Pharaoh: token valid for ${formatTtl(creds.expires_at)} — connecting\n`);
+        try {
+            await startProxy(creds.sse_url, creds.access_token);
+            return;
+        }
+        catch (err) {
+            if (err instanceof TokenExpiredError) {
+                process.stderr.write("Pharaoh: token rejected by server — re-authenticating\n");
+                deleteCredentials();
+                creds = null;
+            }
+            else if (err instanceof TenantSuspendedError) {
+                process.stderr.write(`Pharaoh: ${err.message}\n`);
+                process.exit(1);
+            }
+            else {
+                throw err;
+            }
+        }
+    }
+    // No valid credentials — run device flow
+    if (!creds || isExpired(creds)) {
+        process.stderr.write("Pharaoh: no valid credentials — starting device authorization\n");
+        const token = await authenticate(server);
+        if (token.provisional) {
+            process.stderr.write(`Pharaoh: provisional access — install the GitHub App to map your repos: ${token.install_url ?? ""}\n`);
+        }
+        const sseUrl = resolveSseUrl(token.sse_url, server);
+        creds = tokenToCredentials(token, sseUrl);
+        writeCredentials(creds);
+        printAuthSuccess(token.github_login ?? null, token.tenant_name ?? null, token.repos?.length ?? 0);
+    }
+    // Start proxy with fresh credentials
+    try {
+        await startProxy(creds.sse_url, creds.access_token);
+    }
+    catch (err) {
+        if (err instanceof TokenExpiredError) {
+            // Token expired during session — delete creds and re-auth
+            process.stderr.write("Pharaoh: session expired — re-authenticating\n");
+            deleteCredentials();
+            const token = await authenticate(server);
+            const sseUrl = resolveSseUrl(token.sse_url, server);
+            creds = tokenToCredentials(token, sseUrl);
+            writeCredentials(creds);
+            await startProxy(creds.sse_url, creds.access_token);
+        }
+        else if (err instanceof TenantSuspendedError) {
+            process.stderr.write(`Pharaoh: ${err.message}\n`);
+            process.exit(1);
+        }
+        else {
+            throw err;
+        }
+    }
+}
+main().catch((err) => {
+    process.stderr.write(`Pharaoh: fatal — ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/proxy.d.ts

@@ -0,0 +1,24 @@
+/** Thrown when the remote server returns 401 — token is expired or revoked. */
+export declare class TokenExpiredError extends Error {
+    constructor();
+}
+/** Thrown when the remote server returns 403 — tenant is suspended. */
+export declare class TenantSuspendedError extends Error {
+    constructor(message: string);
+}
+/**
+ * Classify an SSE error — detect 401/403 and throw typed errors.
+ * Exported for testability; used internally by the reconnect loop.
+ */
+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
+ *
+ * On SSE disconnect, attempts reconnect with exponential backoff (5 retries, ~62s total).
+ * Throws TokenExpiredError on 401, TenantSuspendedError on 403.
+ */
+export declare function startProxy(sseUrl: string, token: string): Promise<void>;

package/dist/proxy.js

@@ -0,0 +1,157 @@
+/**
+ * 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).
+ */
+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() {
+        super("Token expired or revoked (401)");
+        this.name = "TokenExpiredError";
+    }
+}
+/** Thrown when the remote server returns 403 — tenant is suspended. */
+export class TenantSuspendedError extends Error {
+    constructor(message) {
+        super(message);
+        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.
+ */
+export function classifySSEError(err) {
+    const msg = err.message ?? "";
+    // SseError from SDK includes the HTTP status code
+    if ("code" in err) {
+        const code = err.code;
+        if (code === 401)
+            throw new TokenExpiredError();
+        if (code === 403)
+            throw new TenantSuspendedError(msg || "Tenant suspended");
+    }
+    // Fallback: check message for status codes
+    if (msg.includes("401"))
+        throw new TokenExpiredError();
+    if (msg.includes("403"))
+        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.
+ *
+ * Message flow:
+ *   Claude Code → stdin → StdioServerTransport.onmessage → SSEClientTransport.send → POST /message
+ *   Pharaoh → SSE stream → SSEClientTransport.onmessage → StdioServerTransport.send → stdout
+ *
+ * On SSE disconnect, attempts reconnect with exponential backoff (5 retries, ~62s total).
+ * Throws TokenExpiredError on 401, TenantSuspendedError on 403.
+ */
+export async function startProxy(sseUrl, token) {
+    const stdio = new StdioServerTransport();
+    let sse = createSSETransport(sseUrl, token);
+    let reconnectAttempt = 0;
+    /** 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`);
+            });
+        };
+    }
+    /** Handle SSE errors — delegates to classifySSEError for 401/403 detection. */
+    const handleSSEError = classifySSEError;
+    // Wire up initial bridge
+    bridge(sse);
+    // Handle SSE connection drops with reconnect
+    sse.onerror = (err) => {
+        try {
+            handleSSEError(err);
+        }
+        catch (typed) {
+            // TokenExpiredError or TenantSuspendedError — propagate via close
+            sse.close().catch(() => { });
+            throw typed;
+        }
+    };
+    // Start both transports
+    await stdio.start();
+    // Connect SSE with reconnect loop
+    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);
+                    bridge(sse);
+                }
+                await sse.start();
+                reconnectAttempt = 0; // Reset on successful connection
+                // Wait for close — this promise resolves when SSE disconnects
+                await new Promise((resolve, reject) => {
+                    sse.onclose = () => resolve();
+                    sse.onerror = (err) => {
+                        try {
+                            handleSSEError(err);
+                        }
+                        catch (typed) {
+                            reject(typed);
+                            return;
+                        }
+                        // Non-fatal error — SSE will auto-close, onclose will fire
+                    };
+                });
+                // 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");
+                }
+            }
+        }
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=proxy.js.map

package/dist/proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.js","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAC;AAC7E,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF,+EAA+E;AAC/E,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC3C;QACC,KAAK,CAAC,gCAAgC,CAAC,CAAC;QACxC,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IACjC,CAAC;CACD;AAED,uEAAuE;AACvE,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC9C,YAAY,OAAe;QAC1B,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACpC,CAAC;CACD;AAED,8DAA8D;AAC9D,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;AAEpD;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAU;IAC1C,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC;IAC9B,kDAAkD;IAClD,IAAI,MAAM,IAAI,GAAG,EAAE,CAAC;QACnB,MAAM,IAAI,GAAI,GAAyB,CAAC,IAAI,CAAC;QAC7C,IAAI,IAAI,KAAK,GAAG;YAAE,MAAM,IAAI,iBAAiB,EAAE,CAAC;QAChD,IAAI,IAAI,KAAK,GAAG;YAAE,MAAM,IAAI,oBAAoB,CAAC,GAAG,IAAI,kBAAkB,CAAC,CAAC;IAC7E,CAAC;IACD,2CAA2C;IAC3C,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,iBAAiB,EAAE,CAAC;IACvD,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,oBAAoB,CAAC,GAAG,IAAI,kBAAkB,CAAC,CAAC;AACpF,CAAC;AAED;;;;GAIG;AACH,SAAS,kBAAkB,CAAC,MAAc,EAAE,KAAa;IACxD,MAAM,UAAU,GAAG,UAAU,KAAK,EAAE,CAAC;IACrC,OAAO,IAAI,kBAAkB,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,EAAE;QAC9C,eAAe,EAAE;YAChB,KAAK,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE;gBACpB,MAAM,CAAC,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,OAAsB,CAAC,CAAC;gBACnD,CAAC,CAAC,GAAG,CAAC,eAAe,EAAE,UAAU,CAAC,CAAC;gBACnC,OAAO,KAAK,CAAC,GAAG,EAAE,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,CAAC,EAAiB,CAAC,CAAC;YAC3D,CAAC;SACD;QACD,WAAW,EAAE;YACZ,OAAO,EAAE,EAAE,aAAa,EAAE,UAAU,EAAE;SACtC;KACD,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,MAAc,EAAE,KAAa;IAC7D,MAAM,KAAK,GAAG,IAAI,oBAAoB,EAAE,CAAC;IACzC,IAAI,GAAG,GAAG,kBAAkB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC5C,IAAI,gBAAgB,GAAG,CAAC,CAAC;IAEzB,sEAAsE;IACtE,SAAS,MAAM,CAAC,YAAgC;QAC/C,KAAK,CAAC,SAAS,GAAG,CAAC,GAAG,EAAE,EAAE;YACzB,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;gBACpC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,yBAAyB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACrG,CAAC,CAAC,CAAC;QACJ,CAAC,CAAC;QACF,YAAY,CAAC,SAAS,GAAG,CAAC,GAAG,EAAE,EAAE;YAChC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;gBAC7B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,2BAA2B,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACvG,CAAC,CAAC,CAAC;QACJ,CAAC,CAAC;IACH,CAAC;IAED,+EAA+E;IAC/E,MAAM,cAAc,GAAG,gBAAgB,CAAC;IAExC,yBAAyB;IACzB,MAAM,CAAC,GAAG,CAAC,CAAC;IAEZ,6CAA6C;IAC7C,GAAG,CAAC,OAAO,GAAG,CAAC,GAAG,EAAE,EAAE;QACrB,IAAI,CAAC;YACJ,cAAc,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,kEAAkE;YAClE,GAAG,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;YAC5B,MAAM,KAAK,CAAC;QACb,CAAC;IACF,CAAC,CAAC;IAEF,wBAAwB;IACxB,MAAM,KAAK,CAAC,KAAK,EAAE,CAAC;IAEpB,kCAAkC;IAClC,MAAM,oBAAoB,EAAE,CAAC;IAE7B,kEAAkE;IAClE,KAAK,UAAU,oBAAoB;QAClC,OAAO,gBAAgB,IAAI,UAAU,CAAC,MAAM,EAAE,CAAC;YAC9C,IAAI,CAAC;gBACJ,IAAI,gBAAgB,GAAG,CAAC,EAAE,CAAC;oBAC1B,MAAM,KAAK,GAAG,UAAU,CAAC,gBAAgB,GAAG,CAAC,CAAC,CAAC;oBAC/C,OAAO,CAAC,MAAM,CAAC,KAAK,CACnB,4BAA4B,KAAK,GAAG,IAAI,cAAc,gBAAgB,IAAI,UAAU,CAAC,MAAM,QAAQ,CACnG,CAAC;oBACF,MAAM,KAAK,CAAC,KAAK,CAAC,CAAC;oBACnB,GAAG,GAAG,kBAAkB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;oBACxC,MAAM,CAAC,GAAG,CAAC,CAAC;gBACb,CAAC;gBAED,MAAM,GAAG,CAAC,KAAK,EAAE,CAAC;gBAClB,gBAAgB,GAAG,CAAC,CAAC,CAAC,iCAAiC;gBAEvD,8DAA8D;gBAC9D,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;oBAC3C,GAAG,CAAC,OAAO,GAAG,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC;oBAC9B,GAAG,CAAC,OAAO,GAAG,CAAC,GAAG,EAAE,EAAE;wBACrB,IAAI,CAAC;4BACJ,cAAc,CAAC,GAAG,CAAC,CAAC;wBACrB,CAAC;wBAAC,OAAO,KAAK,EAAE,CAAC;4BAChB,MAAM,CAAC,KAAK,CAAC,CAAC;4BACd,OAAO;wBACR,CAAC;wBACD,2DAA2D;oBAC5D,CAAC,CAAC;gBACH,CAAC,CAAC,CAAC;gBAEH,iCAAiC;gBACjC,gBAAgB,EAAE,CAAC;YACpB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACd,IAAI,GAAG,YAAY,iBAAiB,IAAI,GAAG,YAAY,oBAAoB,EAAE,CAAC;oBAC7E,MAAM,KAAK,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;oBACpC,MAAM,GAAG,CAAC;gBACX,CAAC;gBACD,gBAAgB,EAAE,CAAC;gBACnB,IAAI,gBAAgB,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC;oBAC1C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,qDAAqD,CAAC,CAAC;oBAC5E,MAAM,KAAK,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;oBACpC,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;gBAChE,CAAC;YACF,CAAC;QACF,CAAC;IACF,CAAC;AACF,CAAC;AAED,SAAS,KAAK,CAAC,EAAU;IACxB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC1D,CAAC"}

package/package.json

@@ -0,0 +1,28 @@
+{
+	"name": "@pharaoh-so/mcp",
+	"version": "0.1.0",
+	"description": "Stdio-to-SSE proxy for Pharaoh MCP — enables headless environments (VPS, SSH, CI) via device flow auth",
+	"type": "module",
+	"main": "dist/index.js",
+	"bin": {
+		"pharaoh-mcp": "./dist/index.js"
+	},
+	"scripts": {
+		"build": "tsc && node -e \"const fs=require('fs'),f='dist/index.js',c=fs.readFileSync(f,'utf8');if(!c.startsWith('#!'))fs.writeFileSync(f,'#!/usr/bin/env node\\n'+c);fs.chmodSync(f,0o755)\"",
+		"typecheck": "tsc --noEmit",
+		"test": "vitest run",
+		"lint": "biome check src/"
+	},
+	"license": "MIT",
+	"engines": {
+		"node": ">=18"
+	},
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "^1.26.0"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.3.15",
+		"typescript": "^5.9.3",
+		"vitest": "^4.0.18"
+	}
+}

package/src/auth.ts

@@ -0,0 +1,143 @@
+/**
+ * Device flow client for Pharaoh MCP proxy (RFC 8628).
+ * All user-visible output goes to stderr — stdout is reserved for JSON-RPC.
+ */
+
+/** Response from POST /device. */
+export interface DeviceCodeResponse {
+	device_code: string;
+	user_code: string;
+	verification_uri: string;
+	verification_uri_complete: string;
+	expires_in: number;
+	interval: number;
+}
+
+/** Successful response from POST /device/token. */
+export interface TokenResponse {
+	access_token: string;
+	token_type: string;
+	expires_in: number;
+	sse_url: string;
+	github_login?: string;
+	tenant_name?: string;
+	repos?: string[];
+	provisional?: boolean;
+	install_url?: string;
+}
+
+/** Error response from POST /device/token while still waiting. */
+interface DeviceTokenError {
+	error: string;
+	error_description?: string;
+}
+
+/**
+ * Request a device code from the Pharaoh server (RFC 8628 §3.1).
+ * Returns the device code, user code, and verification URIs.
+ */
+export async function requestDeviceCode(baseUrl: string): Promise<DeviceCodeResponse> {
+	const res = await fetch(`${baseUrl}/device`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({}),
+	});
+
+	if (!res.ok) {
+		const text = await res.text().catch(() => "");
+		throw new Error(`Device code request failed (${res.status}): ${text}`);
+	}
+
+	return (await res.json()) as DeviceCodeResponse;
+}
+
+/**
+ * Poll for device authorization completion (RFC 8628 §3.5).
+ * Blocks until the user authorizes, the code expires, or an error occurs.
+ * Adds 1s jitter to the server-specified interval to avoid thundering herd.
+ */
+export async function pollForToken(
+	baseUrl: string,
+	deviceCode: string,
+	interval: number,
+): Promise<TokenResponse> {
+	const grantType = "urn:ietf:params:oauth:grant-type:device_code";
+
+	while (true) {
+		// Wait interval + 0–1s jitter before each poll
+		const jitterMs = Math.random() * 1000;
+		await sleep(interval * 1000 + jitterMs);
+
+		const res = await fetch(`${baseUrl}/device/token`, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({ device_code: deviceCode, grant_type: grantType }),
+		});
+
+		if (res.ok) {
+			return (await res.json()) as TokenResponse;
+		}
+
+		const body = (await res.json().catch(() => ({ error: "unknown" }))) as DeviceTokenError;
+
+		if (body.error === "authorization_pending") {
+			continue;
+		}
+
+		if (body.error === "slow_down") {
+			// RFC 8628 §3.5: increase interval by 5 seconds
+			interval += 5;
+			continue;
+		}
+
+		if (body.error === "expired_token") {
+			throw new Error("Device code expired. Please try again.");
+		}
+
+		if (body.error === "access_denied") {
+			throw new Error("Authorization was denied.");
+		}
+
+		throw new Error(`Device token error: ${body.error} — ${body.error_description ?? ""}`);
+	}
+}
+
+/**
+ * Print the device activation prompt to stderr.
+ * Shows the user code and verification URI in a visible box.
+ */
+export function printActivationPrompt(userCode: string, verificationUri: string): void {
+	const lines = [
+		"",
+		"┌───────────────────────────────────────────┐",
+		"│  Pharaoh — Device Authorization            │",
+		"│                                            │",
+		`│  Code:  ${userCode.padEnd(33)}│`,
+		`│  URL:   ${verificationUri.padEnd(33)}│`,
+		"│                                            │",
+		"│  Open the URL and enter the code to sign   │",
+		"│  in. You can do this on any device.        │",
+		"└───────────────────────────────────────────┘",
+		"",
+	];
+	process.stderr.write(lines.join("\n") + "\n");
+}
+
+/**
+ * Print authentication success message to stderr.
+ */
+export function printAuthSuccess(
+	login: string | null,
+	tenant: string | null,
+	repoCount: number,
+): void {
+	const parts: string[] = ["Pharaoh: authenticated"];
+	if (login) parts.push(`as ${login}`);
+	if (tenant) parts.push(`(${tenant})`);
+	parts.push(`— ${repoCount} repo${repoCount === 1 ? "" : "s"} connected`);
+	process.stderr.write(`${parts.join(" ")}\n`);
+}
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/credentials.ts

@@ -0,0 +1,92 @@
+/**
+ * Credential storage for Pharaoh MCP proxy — persists device flow tokens to ~/.pharaoh/credentials.json.
+ * File permissions: 0600 (credentials.json), 0700 (~/.pharaoh/).
+ */
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+/** Current credential schema version — bump when the format changes. */
+const SCHEMA_VERSION = 1;
+
+/** Stored credential shape. */
+export interface Credentials {
+	version: typeof SCHEMA_VERSION;
+	access_token: string;
+	/** ISO 8601 timestamp when the token expires. */
+	expires_at: string;
+	/** Original TTL in seconds (from the token response). */
+	expires_in: number;
+	sse_url: string;
+	github_login: string | null;
+	tenant_name: string | null;
+	repos: string[];
+}
+
+/** Default credential file path. */
+const CREDENTIALS_PATH = join(homedir(), ".pharaoh", "credentials.json");
+
+/**
+ * Read and parse stored credentials. Returns null if missing, unreadable,
+ * malformed, or wrong schema version.
+ */
+export function readCredentials(path = CREDENTIALS_PATH): Credentials | null {
+	try {
+		const raw = readFileSync(path, "utf-8");
+		const parsed: unknown = JSON.parse(raw);
+		if (!isValidCredentials(parsed)) return null;
+		return parsed;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Write credentials to disk with restrictive permissions.
+ * Creates the parent directory (0700) if it doesn't exist.
+ */
+export function writeCredentials(creds: Credentials, path = CREDENTIALS_PATH): void {
+	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): void {
+	try {
+		unlinkSync(path);
+	} catch {
+		// File doesn't exist — nothing to delete
+	}
+}
+
+/**
+ * Check if credentials are expired or within 10% of expiry.
+ * The 10% buffer prevents connecting with a token that will expire mid-session.
+ */
+export function isExpired(creds: Credentials): boolean {
+	const expiresAt = new Date(creds.expires_at).getTime();
+	if (Number.isNaN(expiresAt)) return true;
+
+	const now = Date.now();
+	const totalTtlMs = creds.expires_in * 1000;
+	const bufferMs = totalTtlMs * 0.1;
+
+	return now >= expiresAt - bufferMs;
+}
+
+/** Type guard for valid credential objects. */
+function isValidCredentials(value: unknown): value is Credentials {
+	if (typeof value !== "object" || value === null) return false;
+	const obj = value as Record<string, unknown>;
+	return (
+		obj.version === SCHEMA_VERSION &&
+		typeof obj.access_token === "string" &&
+		typeof obj.expires_at === "string" &&
+		typeof obj.expires_in === "number" &&
+		typeof obj.sse_url === "string" &&
+		Array.isArray(obj.repos)
+	);
+}

package/src/index.ts

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+/**
+ * @pharaoh-so/mcp — Stdio-to-SSE proxy for headless MCP environments.
+ *
+ * Presents as an MCP server on stdio (for Claude Code) and relays messages
+ * to a remote Pharaoh SSE server. Authenticates via RFC 8628 device flow
+ * so the user can authorize on any device with a browser.
+ */
+import {
+	printActivationPrompt,
+	printAuthSuccess,
+	pollForToken,
+	requestDeviceCode,
+	type TokenResponse,
+} from "./auth.js";
+import {
+	type Credentials,
+	deleteCredentials,
+	isExpired,
+	readCredentials,
+	writeCredentials,
+} from "./credentials.js";
+import { TokenExpiredError, TenantSuspendedError, startProxy } from "./proxy.js";
+
+const DEFAULT_SERVER = "https://mcp.pharaoh.so";
+
+/** Parse CLI arguments. */
+function parseArgs(): { server: string; logout: boolean } {
+	const args = process.argv.slice(2);
+	let server = DEFAULT_SERVER;
+	let logout = false;
+
+	for (let i = 0; i < args.length; i++) {
+		if (args[i] === "--server" && args[i + 1]) {
+			server = args[i + 1];
+			i++;
+		} else if (args[i] === "--logout") {
+			logout = true;
+		} else if (args[i] === "--help" || args[i] === "-h") {
+			printUsage();
+			process.exit(0);
+		}
+	}
+
+	// Strip trailing slash
+	server = server.replace(/\/+$/, "");
+
+	return { server, logout };
+}
+
+function printUsage(): void {
+	process.stderr.write(
+		[
+			"Usage: pharaoh-mcp [options]",
+			"",
+			"Options:",
+			"  --server <url>  Pharaoh server URL (default: https://mcp.pharaoh.so)",
+			"  --logout        Clear stored credentials and exit",
+			"  --help, -h      Show this help",
+			"",
+			"Add to Claude Code:",
+			"  claude mcp add pharaoh -- npx @pharaoh-so/mcp",
+			"",
+		].join("\n") + "\n",
+	);
+}
+
+/** Run the device flow and return a token response. */
+async function authenticate(server: string): Promise<TokenResponse> {
+	const deviceCode = await requestDeviceCode(server);
+	printActivationPrompt(deviceCode.user_code, deviceCode.verification_uri);
+	return pollForToken(server, deviceCode.device_code, deviceCode.interval);
+}
+
+/**
+ * Validate that a server-supplied SSE URL shares the same origin as the configured server.
+ * Prevents a compromised auth response from redirecting the Bearer token to an attacker's host.
+ * Falls back to `${server}/sse` if the URL is missing, malformed, or cross-origin.
+ */
+function resolveSseUrl(tokenSseUrl: string | undefined, server: string): string {
+	const fallback = `${server}/sse`;
+	if (!tokenSseUrl) return fallback;
+	try {
+		const sseOrigin = new URL(tokenSseUrl).origin;
+		const serverOrigin = new URL(server).origin;
+		if (sseOrigin !== serverOrigin) {
+			process.stderr.write(
+				`Pharaoh: ignoring cross-origin sse_url (${sseOrigin} ≠ ${serverOrigin})\n`,
+			);
+			return fallback;
+		}
+		return tokenSseUrl;
+	} catch {
+		return fallback;
+	}
+}
+
+/** Convert a token response to storable credentials. */
+function tokenToCredentials(token: TokenResponse, sseUrl: string): Credentials {
+	return {
+		version: 1,
+		access_token: token.access_token,
+		expires_at: new Date(Date.now() + token.expires_in * 1000).toISOString(),
+		expires_in: token.expires_in,
+		sse_url: sseUrl,
+		github_login: token.github_login ?? null,
+		tenant_name: token.tenant_name ?? null,
+		repos: token.repos ?? [],
+	};
+}
+
+/** Format remaining TTL as human-readable string (e.g. "5d 12h"). */
+function formatTtl(expiresAt: string): string {
+	const remainingMs = new Date(expiresAt).getTime() - Date.now();
+	if (remainingMs <= 0) return "expired";
+	const hours = Math.floor(remainingMs / 3_600_000);
+	const days = Math.floor(hours / 24);
+	const remHours = hours % 24;
+	if (days > 0) return `${days}d ${remHours}h`;
+	if (hours > 0) return `${hours}h`;
+	return `${Math.floor(remainingMs / 60_000)}m`;
+}
+
+async function main(): Promise<void> {
+	const { server, logout } = parseArgs();
+
+	// --logout: clear credentials and exit
+	if (logout) {
+		deleteCredentials();
+		process.stderr.write("Pharaoh: credentials cleared\n");
+		process.exit(0);
+	}
+
+	let creds = readCredentials();
+
+	// If we have valid credentials, try to connect directly
+	if (creds && !isExpired(creds)) {
+		process.stderr.write(`Pharaoh: token valid for ${formatTtl(creds.expires_at)} — connecting\n`);
+		try {
+			await startProxy(creds.sse_url, creds.access_token);
+			return;
+		} catch (err) {
+			if (err instanceof TokenExpiredError) {
+				process.stderr.write("Pharaoh: token rejected by server — re-authenticating\n");
+				deleteCredentials();
+				creds = null;
+			} else if (err instanceof TenantSuspendedError) {
+				process.stderr.write(`Pharaoh: ${err.message}\n`);
+				process.exit(1);
+			} else {
+				throw err;
+			}
+		}
+	}
+
+	// No valid credentials — run device flow
+	if (!creds || isExpired(creds)) {
+		process.stderr.write("Pharaoh: no valid credentials — starting device authorization\n");
+		const token = await authenticate(server);
+
+		if (token.provisional) {
+			process.stderr.write(
+				`Pharaoh: provisional access — install the GitHub App to map your repos: ${token.install_url ?? ""}\n`,
+			);
+		}
+
+		const sseUrl = resolveSseUrl(token.sse_url, server);
+		creds = tokenToCredentials(token, sseUrl);
+		writeCredentials(creds);
+
+		printAuthSuccess(
+			token.github_login ?? null,
+			token.tenant_name ?? null,
+			token.repos?.length ?? 0,
+		);
+	}
+
+	// Start proxy with fresh credentials
+	try {
+		await startProxy(creds.sse_url, creds.access_token);
+	} catch (err) {
+		if (err instanceof TokenExpiredError) {
+			// Token expired during session — delete creds and re-auth
+			process.stderr.write("Pharaoh: session expired — re-authenticating\n");
+			deleteCredentials();
+			const token = await authenticate(server);
+			const sseUrl = resolveSseUrl(token.sse_url, server);
+			creds = tokenToCredentials(token, sseUrl);
+			writeCredentials(creds);
+			await startProxy(creds.sse_url, creds.access_token);
+		} else if (err instanceof TenantSuspendedError) {
+			process.stderr.write(`Pharaoh: ${err.message}\n`);
+			process.exit(1);
+		} else {
+			throw err;
+		}
+	}
+}
+
+main().catch((err) => {
+	process.stderr.write(`Pharaoh: fatal — ${err instanceof Error ? err.message : String(err)}\n`);
+	process.exit(1);
+});

package/src/proxy.ts

@@ -0,0 +1,168 @@
+/**
+ * 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).
+ */
+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() {
+		super("Token expired or revoked (401)");
+		this.name = "TokenExpiredError";
+	}
+}
+
+/** Thrown when the remote server returns 403 — tenant is suspended. */
+export class TenantSuspendedError extends Error {
+	constructor(message: string) {
+		super(message);
+		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.
+ */
+export function classifySSEError(err: Error): void {
+	const msg = err.message ?? "";
+	// SseError from SDK includes the HTTP status code
+	if ("code" in err) {
+		const code = (err as { code?: number }).code;
+		if (code === 401) throw new TokenExpiredError();
+		if (code === 403) throw new TenantSuspendedError(msg || "Tenant suspended");
+	}
+	// Fallback: check message for status codes
+	if (msg.includes("401")) throw new TokenExpiredError();
+	if (msg.includes("403")) 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: string, token: string): SSEClientTransport {
+	const authHeader = `Bearer ${token}`;
+	return new SSEClientTransport(new URL(sseUrl), {
+		eventSourceInit: {
+			fetch: (url, init) => {
+				const h = new Headers(init.headers as HeadersInit);
+				h.set("Authorization", authHeader);
+				return fetch(url, { ...init, headers: h } as RequestInit);
+			},
+		},
+		requestInit: {
+			headers: { Authorization: authHeader },
+		},
+	});
+}
+
+/**
+ * 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
+ *
+ * On SSE disconnect, attempts reconnect with exponential backoff (5 retries, ~62s total).
+ * Throws TokenExpiredError on 401, TenantSuspendedError on 403.
+ */
+export async function startProxy(sseUrl: string, token: string): Promise<void> {
+	const stdio = new StdioServerTransport();
+	let sse = createSSETransport(sseUrl, token);
+	let reconnectAttempt = 0;
+
+	/** Wire up bidirectional message relay between the two transports. */
+	function bridge(sseTransport: SSEClientTransport): void {
+		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`);
+			});
+		};
+	}
+
+	/** Handle SSE errors — delegates to classifySSEError for 401/403 detection. */
+	const handleSSEError = classifySSEError;
+
+	// Wire up initial bridge
+	bridge(sse);
+
+	// Handle SSE connection drops with reconnect
+	sse.onerror = (err) => {
+		try {
+			handleSSEError(err);
+		} catch (typed) {
+			// TokenExpiredError or TenantSuspendedError — propagate via close
+			sse.close().catch(() => {});
+			throw typed;
+		}
+	};
+
+	// Start both transports
+	await stdio.start();
+
+	// Connect SSE with reconnect loop
+	await connectWithReconnect();
+
+	/** Attempt SSE connection with exponential backoff on failure. */
+	async function connectWithReconnect(): Promise<void> {
+		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);
+					bridge(sse);
+				}
+
+				await sse.start();
+				reconnectAttempt = 0; // Reset on successful connection
+
+				// Wait for close — this promise resolves when SSE disconnects
+				await new Promise<void>((resolve, reject) => {
+					sse.onclose = () => resolve();
+					sse.onerror = (err) => {
+						try {
+							handleSSEError(err);
+						} catch (typed) {
+							reject(typed);
+							return;
+						}
+						// Non-fatal error — SSE will auto-close, onclose will fire
+					};
+				});
+
+				// 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");
+				}
+			}
+		}
+	}
+}
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+	"compilerOptions": {
+		"target": "ES2022",
+		"module": "NodeNext",
+		"moduleResolution": "NodeNext",
+		"outDir": "dist",
+		"rootDir": "src",
+		"strict": true,
+		"esModuleInterop": true,
+		"skipLibCheck": true,
+		"forceConsistentCasingInFileNames": true,
+		"declaration": true,
+		"sourceMap": true,
+		"resolveJsonModule": true
+	},
+	"include": ["src/**/*.ts"],
+	"exclude": ["node_modules", "dist"]
+}