@minhspark/codex-mcp-bridge 1.10.0

package/src/security-policy.mjs

@@ -0,0 +1,149 @@
+import { realpathSync } from "node:fs";
+import path from "node:path";
+
+const APPROVAL_POLICIES = new Set(["untrusted", "on-failure", "on-request", "never"]);
+const SANDBOXES = new Set(["read-only", "workspace-write"]);
+
+/**
+ * Resolves the deepest ancestor that exists and re-appends the rest, rather
+ * than giving up on the whole path when the leaf is missing. Falling back to
+ * the unresolved path made containment depend on the platform: macOS puts
+ * temporary and home directories behind symlinks (/var -> /private/var), so an
+ * allowed root canonicalised while a missing candidate did not, and the two
+ * stopped sharing a prefix; on Linux, with no symlink in the way, the same
+ * pair matched. Same policy, opposite answer, decided by a detail of the disk.
+ *
+ * Resolving the existing prefix keeps the protection that matters: a symlink
+ * pointing out of an allowed root resolves to where it really goes, so it is
+ * still recognised as outside.
+ */
+function canonicalPath(input) {
+  const resolved = path.resolve(input);
+  let head = resolved;
+  const missing = [];
+  for (;;) {
+    try {
+      return path.join(realpathSync.native(head), ...missing);
+    } catch {
+      const parent = path.dirname(head);
+      if (parent === head) return resolved;
+      missing.unshift(path.basename(head));
+      head = parent;
+    }
+  }
+}
+
+function isWithin(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === "" || (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+
+function parseList(value) {
+  return new Set(
+    String(value ?? "")
+      .split(",")
+      .map((entry) => entry.trim())
+      .filter(Boolean),
+  );
+}
+
+function parseRoots(value) {
+  return String(value ?? "")
+    .split(path.delimiter)
+    .map((entry) => entry.trim())
+    .filter(Boolean)
+    .map(canonicalPath);
+}
+
+export function assertAllowedAppServerUrl(value) {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new Error(`Invalid CODEX_APP_SERVER_URL: ${value}`);
+  }
+  if (!new Set(["ws:", "wss:"]).has(parsed.protocol)) {
+    throw new Error(`CODEX_APP_SERVER_URL must use ws:// or wss://: ${value}`);
+  }
+  const hostname = parsed.hostname.toLowerCase().replace(/^\[|\]$/g, "");
+  const loopback = hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1";
+  if (!loopback) {
+    throw new Error(
+      `Refusing non-loopback app-server endpoint ${value}; the bridge only supports authenticated local app-servers`,
+    );
+  }
+  return parsed;
+}
+
+export class BridgeSecurityPolicy {
+  constructor(env = process.env) {
+    this.allowedThreadIds = parseList(env.CODEX_BRIDGE_ALLOWED_THREADS);
+    this.allowedRoots = parseRoots(env.CODEX_BRIDGE_ALLOWED_ROOTS);
+    this.ownedThreadIds = new Set();
+
+    this.approvalPolicy = env.CODEX_BRIDGE_APPROVAL_POLICY ?? "on-request";
+    if (!APPROVAL_POLICIES.has(this.approvalPolicy)) {
+      throw new Error(`Invalid CODEX_BRIDGE_APPROVAL_POLICY: ${this.approvalPolicy}`);
+    }
+
+    this.sandbox = env.CODEX_BRIDGE_SANDBOX ?? "workspace-write";
+    if (!SANDBOXES.has(this.sandbox)) {
+      throw new Error(`CODEX_BRIDGE_SANDBOX must be read-only or workspace-write: ${this.sandbox}`);
+    }
+  }
+
+  registerThread(threadId) {
+    if (threadId) this.ownedThreadIds.add(threadId);
+  }
+
+  isThreadAuthorized(threadId) {
+    return this.ownedThreadIds.has(threadId) || this.allowedThreadIds.has(threadId);
+  }
+
+  assertThread(threadId) {
+    if (this.isThreadAuthorized(threadId)) return;
+    if (!this.allowedThreadIds.size && !this.ownedThreadIds.size) {
+      throw new Error(
+        "No authorized Codex threads are configured. Set CODEX_BRIDGE_ALLOWED_THREADS or create a thread with start_codex_thread.",
+      );
+    }
+    throw new Error(`Codex thread ${threadId} is not authorized for this bridge`);
+  }
+
+  /**
+   * Listing is gated on the workspace root, not on the send allowlist. Gating
+   * both ways left no path to a thread id at all: you cannot allowlist a
+   * thread whose id you have no way to learn, so the only usable thread was
+   * one the bridge had created itself. An operator who names a root has
+   * declared that project in scope, and the id is still useless without being
+   * allowlisted for the calls that act.
+   */
+  filterThreads(threads) {
+    return threads.filter((thread) => this.isCwdAuthorized(thread?.cwd));
+  }
+
+  isCwdAuthorized(cwd) {
+    if (!this.allowedRoots.length || !cwd) return false;
+    const candidate = canonicalPath(cwd);
+    return this.allowedRoots.some((root) => isWithin(root, candidate));
+  }
+
+  assertCwd(cwd) {
+    if (!this.allowedRoots.length) {
+      throw new Error(
+        "No authorized workspace roots are configured. Set CODEX_BRIDGE_ALLOWED_ROOTS to one or more project directories.",
+      );
+    }
+    if (this.isCwdAuthorized(cwd)) return;
+    throw new Error(`Working directory is outside CODEX_BRIDGE_ALLOWED_ROOTS: ${cwd}`);
+  }
+
+  summary() {
+    return {
+      authorizedThreads: this.allowedThreadIds.size + this.ownedThreadIds.size,
+      allowedRoots: this.allowedRoots,
+      approvalPolicy: this.approvalPolicy,
+      sandbox: this.sandbox,
+    };
+  }
+}

package/src/turn.mjs

@@ -0,0 +1,140 @@
+const TERMINAL_STATUSES = new Set(["completed", "interrupted", "failed"]);
+
+function summarizeItem(item) {
+  switch (item?.type) {
+    case "agentMessage":
+      return { kind: "agentMessage", text: item.text ?? "" };
+    case "commandExecution":
+      return {
+        kind: "command",
+        command: item.command ?? item.parsedCmd ?? null,
+        exitCode: item.exitCode ?? null,
+        status: item.status ?? null,
+      };
+    case "fileChange":
+      return {
+        kind: "fileChange",
+        files: (item.changes ?? []).map((c) => c.path ?? c.file ?? null).filter(Boolean),
+        status: item.status ?? null,
+      };
+    case "mcpToolCall":
+      return { kind: "mcpToolCall", server: item.server ?? null, tool: item.tool ?? null };
+    case "webSearch":
+      return { kind: "webSearch", query: item.query ?? null };
+    default:
+      return null;
+  }
+}
+
+/**
+ * Send one user turn into an existing Codex thread and wait for it to finish.
+ * Returns the agent text plus a compact activity trail.
+ */
+export async function runTurn(client, { threadId, input, timeoutMs = 240000, turnOverrides = {} }) {
+  const messages = [];
+  const activity = [];
+  const errors = [];
+  const buffered = [];
+  let turnId = null;
+  let settled = false;
+  let resolveDone;
+
+  /**
+   * Only ever resolved, never rejected. `done` has exactly one consumer, and it
+   * sits after `turn/start` has already returned - so rejecting it from the
+   * catch below would reject a promise nobody is awaiting, which Node turns
+   * into an unhandledRejection and, by default, into process exit. A failing
+   * `turn/start` (a thread locked by the desktop app is the everyday case) used
+   * to take the whole MCP server down that way, while the tool handler was
+   * still busy formatting a tidy error message for a client that no longer had
+   * a server to talk to.
+   */
+  const done = new Promise((resolve) => {
+    resolveDone = resolve;
+  });
+
+  const process = (msg) => {
+    const params = msg.params ?? {};
+    if (turnId && params.turnId && params.turnId !== turnId) return;
+
+    switch (msg.method) {
+      case "item/completed": {
+        const summary = summarizeItem(params.item);
+        if (!summary) return;
+        if (summary.kind === "agentMessage") {
+          if (summary.text.trim()) messages.push(summary.text);
+        } else {
+          activity.push(summary);
+        }
+        return;
+      }
+      case "error": {
+        errors.push(params.error ?? { message: "unknown error" });
+        if (!params.willRetry && !settled) {
+          settled = true;
+          resolveDone({ status: "failed", error: params.error ?? null });
+        }
+        return;
+      }
+      case "turn/completed": {
+        const turn = params.turn ?? {};
+        if (turnId && turn.id && turn.id !== turnId) return;
+        if (!TERMINAL_STATUSES.has(turn.status)) return;
+        if (settled) return;
+        settled = true;
+        resolveDone({ status: turn.status, error: turn.error ?? null, durationMs: turn.durationMs ?? null });
+        return;
+      }
+      default:
+    }
+  };
+
+  const unsubscribe = client.subscribe(threadId, (msg) => {
+    if (!turnId) {
+      buffered.push(msg);
+      return;
+    }
+    process(msg);
+  });
+
+  const timer = globalThis.setTimeout(() => {
+    if (settled) return;
+    settled = true;
+    resolveDone({ status: "timeout", error: null });
+  }, timeoutMs);
+
+  const unsubscribeDisconnect = client.subscribeDisconnect(() => {
+    if (settled) return;
+    settled = true;
+    resolveDone({
+      status: "disconnected",
+      error: { message: "the app-server connection dropped while the turn was running" },
+    });
+  });
+
+  try {
+    const started = await client.request(
+      "turn/start",
+      { threadId, input, ...turnOverrides },
+      { timeoutMs: Math.min(timeoutMs, 60000) },
+    );
+    turnId = started?.turn?.id ?? null;
+    for (const msg of buffered.splice(0)) process(msg);
+
+    const outcome = await done;
+    return {
+      threadId,
+      turnId,
+      status: outcome.status,
+      error: outcome.error,
+      durationMs: outcome.durationMs ?? null,
+      text: messages.join("\n\n").trim(),
+      activity,
+      errors,
+    };
+  } finally {
+    globalThis.clearTimeout(timer);
+    unsubscribe();
+    unsubscribeDisconnect();
+  }
+}