@minhspark/codex-mcp-bridge 1.20.1 → 1.21.1

package/src/native-creation-receipts.mjs

@@ -0,0 +1,159 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { homeDir } from "./platform.mjs";
+
+const sameFile = (left, right) => ["dev", "ino", "size", "mode", "uid", "nlink", "mtimeMs", "ctimeMs"].every(field => left[field] === right[field]);
+
+export const creationIdValid = value => typeof value === "string" && /^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/.test(value);
+export function creationRequestHash(args) {
+  const canonical = value => Array.isArray(value) ? value.map(canonical) : value && typeof value === "object"
+    ? Object.fromEntries(Object.keys(value).sort().filter(k => value[k] !== undefined).map(k => [k, canonical(value[k])])) : value;
+  return createHash("sha256").update(JSON.stringify(canonical(args))).digest("hex");
+}
+
+// Stores only exact native creation requests and their results. A missing or
+// pending receipt never permits dispatch again, including after a restart.
+export class NativeCreationReceipts {
+  #key;
+  #keyBoundary;
+  #keyDirectoryBoundary;
+  #keyDirectory;
+  constructor({ directory = path.join(process.env.CODEX_HOME ?? path.join(homeDir(), ".codex"), "bridge-native-creations") } = {}) {
+    this.directory = path.resolve(directory);
+    this.#keyDirectory = path.join(path.dirname(this.directory), "bridge-native-creation-authority");
+  }
+  #signingKey(create = false) {
+    if (create) {
+      try {
+        fs.mkdirSync(this.#keyDirectory, { mode: 0o700 });
+        if (process.platform === "win32") this.#protectWindowsPrivate(this.#keyDirectory, true);
+      } catch (error) { if (error.code !== "EEXIST") throw error; }
+    }
+    const directory = fs.lstatSync(this.#keyDirectory);
+    const canonical = fs.realpathSync.native(this.#keyDirectory);
+    if (!directory.isDirectory() || directory.isSymbolicLink() ||
+        process.platform !== "win32" && ((directory.mode & 0o077) || directory.uid !== process.getuid()) ||
+        this.#keyDirectoryBoundary && (this.#keyDirectoryBoundary.path !== canonical || this.#keyDirectoryBoundary.dev !== directory.dev || this.#keyDirectoryBoundary.ino !== directory.ino)) {
+      throw Error("Unsafe native creation authority directory");
+    }
+    if (process.platform === "win32" && !this.#keyDirectoryBoundary) {
+      this.#assertWindowsPrivate(canonical, true);
+    }
+    this.#keyDirectoryBoundary ??= { path: canonical, dev: directory.dev, ino: directory.ino };
+    const file = path.join(canonical, "signing-key");
+    if (create) {
+      let created, createdBoundary;
+      try {
+        created = fs.openSync(file, "wx", 0o600);
+        createdBoundary = fs.fstatSync(created);
+        if (process.platform === "win32") this.#protectWindowsPrivate(file, false);
+        fs.writeFileSync(created, randomBytes(32));
+        fs.fsyncSync(created);
+      }
+      catch (error) {
+        if (created !== undefined) {
+          fs.closeSync(created);
+          created = undefined;
+          const failed = fs.lstatSync(file);
+          if (failed.dev === createdBoundary.dev && failed.ino === createdBoundary.ino && !failed.isSymbolicLink()) fs.unlinkSync(file);
+        }
+        if (error.code !== "EEXIST") throw error;
+      }
+      finally { if (created !== undefined) fs.closeSync(created); }
+    }
+    const before = fs.lstatSync(file);
+    if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1 || before.size !== 32 ||
+        process.platform !== "win32" && ((before.mode & 0o077) || before.uid !== process.getuid())) throw Error("Unsafe native creation signing key");
+    if (process.platform === "win32" && !this.#keyBoundary) this.#assertWindowsPrivate(file, false);
+    const fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0) | (fs.constants.O_NONBLOCK ?? 0));
+    let key;
+    try {
+      const opened = fs.fstatSync(fd);
+      if (!opened.isFile() || !sameFile(before, opened)) throw Error("Native creation signing key changed");
+      const bytes = Buffer.alloc(33);
+      let count = 0, read;
+      while (count < bytes.length && (read = fs.readSync(fd, bytes, count, bytes.length - count, count))) count += read;
+      key = bytes.subarray(0, count);
+      const after = fs.fstatSync(fd);
+      const current = fs.lstatSync(file);
+      if (key.length !== 32 || current.isSymbolicLink() || !sameFile(opened, after) || !sameFile(after, current)) throw Error("Native creation signing key changed");
+    } finally { fs.closeSync(fd); }
+    if (this.#keyBoundary && (this.#keyBoundary.dev !== before.dev || this.#keyBoundary.ino !== before.ino || !timingSafeEqual(this.#key, key))) throw Error("Native creation signing key changed");
+    this.#keyBoundary ??= { dev: before.dev, ino: before.ino };
+    this.#key ??= key;
+    return this.#key;
+  }
+  #protectWindowsPrivate(file, directory) {
+    const encodedPath = Buffer.from(file, "utf8").toString("base64");
+    const securityType = directory ? "DirectorySecurity" : "FileSecurity";
+    const inheritance = directory ? "ContainerInherit,ObjectInherit" : "None";
+    const script = `$ErrorActionPreference='Stop';$s=[Security.Principal.WindowsIdentity]::GetCurrent().User;$a=New-Object Security.AccessControl.${securityType};$a.SetOwner($s);$a.SetAccessRuleProtection($true,$false);$r=New-Object Security.AccessControl.FileSystemAccessRule($s,'FullControl','${inheritance}','None','Allow');$a.AddAccessRule($r);Set-Acl -LiteralPath ([Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${encodedPath}'))) -AclObject $a`;
+    this.#runWindowsAclScript(script);
+  }
+  #assertWindowsPrivate(file, directory) {
+    const encodedPath = Buffer.from(file, "utf8").toString("base64");
+    const script = `$ErrorActionPreference='Stop';$a=Get-Acl -LiteralPath ([Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${encodedPath}')));$s=[Security.Principal.WindowsIdentity]::GetCurrent().User.Value;if(${directory ? "$true" : "$false"} -and !$a.AreAccessRulesProtected){throw 'Unprotected native authority'};if($a.GetOwner([Security.Principal.SecurityIdentifier]).Value -ne $s){throw 'Unexpected native authority owner'};foreach($r in $a.Access){if($r.IdentityReference.Translate([Security.Principal.SecurityIdentifier]).Value -ne $s -or $r.AccessControlType -ne 'Allow'){throw 'Unexpected native authority access'}};if($a.Access.Count -ne 1){throw 'Ambiguous native authority access'}`;
+    this.#runWindowsAclScript(script);
+  }
+  #runWindowsAclScript(script) {
+    const shellDirectory = path.win32.join(process.env.SystemRoot ?? "C:\\Windows", "System32", "WindowsPowerShell", "v1.0");
+    const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => key.toLowerCase() !== "psmodulepath"));
+    env.PSModulePath = path.win32.join(shellDirectory, "Modules");
+    execFileSync(path.win32.join(shellDirectory, "powershell.exe"), ["-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(script, "utf16le").toString("base64")], { env, stdio: "pipe", windowsHide: true, timeout: 10000 });
+  }
+  #signature(row, create = false) {
+    const { signature, ...payload } = row;
+    return createHmac("sha256", this.#signingKey(create)).update("native-creation-receipt-v1\0").update(creationRequestHash(payload)).digest("hex");
+  }
+  file(id) {
+    if (!creationIdValid(id)) throw Error("Invalid native creation receipt id");
+    fs.mkdirSync(this.directory, { recursive: true, mode: 0o700 });
+    const st = fs.lstatSync(this.directory);
+    if (!st.isDirectory() || st.isSymbolicLink()) throw Error("Unsafe native creation receipt directory");
+    const canonical = fs.realpathSync.native(this.directory);
+    if (this.boundary && (this.boundary.path !== canonical || this.boundary.dev !== st.dev || this.boundary.ino !== st.ino)) throw Error("Native creation receipt directory changed");
+    this.boundary ??= { path: canonical, dev: st.dev, ino: st.ino };
+    this.directory = canonical;
+    return path.join(canonical, id + ".json");
+  }
+  read(id, accounts, hash) {
+    const file = this.file(id);
+    let fd, receiptFound = false;
+    try {
+      const before = fs.lstatSync(file);
+      receiptFound = true;
+      if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1 || before.size > 1024 * 1024) throw Error("Unsafe native creation receipt");
+      fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0) | (fs.constants.O_NONBLOCK ?? 0));
+      const opened = fs.fstatSync(fd);
+      if (!opened.isFile() || !sameFile(before, opened)) throw Error("Native creation receipt changed");
+      const bytes = Buffer.alloc(1024 * 1024 + 1);
+      let count = 0, n;
+      while ((n = fs.readSync(fd, bytes, count, bytes.length - count, count))) { count += n; if (count > 1024 * 1024) throw Error("Oversized native creation receipt"); }
+      const after = fs.fstatSync(fd);
+      const current = fs.lstatSync(this.file(id));
+      if (current.isSymbolicLink() || !sameFile(opened, after) || !sameFile(after, current) || count !== opened.size) throw Error("Native creation receipt changed");
+      const row = JSON.parse(bytes.subarray(0, count).toString());
+      if (row.version !== 1 || row.id !== id || row.hash !== hash || creationRequestHash(row.args) !== hash ||
+          !accounts || ["claude", "codex"].some(k => !accounts[k] || row.accounts?.[k] !== accounts[k]) ||
+          typeof row.executorThreadId !== "string" || !["pending", "completed", "failed"].includes(row.state)) throw Error("Native creation receipt binding mismatch");
+      if (typeof row.signature !== "string" || !/^[a-f0-9]{64}$/.test(row.signature) ||
+          !timingSafeEqual(Buffer.from(row.signature, "hex"), Buffer.from(this.#signature(row), "hex"))) throw Error("Native creation receipt signature is invalid; ownership recovery is blocked");
+      return row;
+    } catch (e) { if (e.code === "ENOENT" && !receiptFound) return null; throw e; }
+    finally { if (fd !== undefined) fs.closeSync(fd); }
+  }
+  reserve(id, args, accounts, executorThreadId) {
+    const row = { version: 1, id, hash: creationRequestHash(args), args, accounts, executorThreadId, state: "pending" };
+    this.write(row, true); return row;
+  }
+  write(row, exclusive = false) {
+    const file = this.file(row.id), tmp = exclusive ? file : file + "." + randomUUID() + ".pending";
+    const bytes = JSON.stringify({ ...row, signature: this.#signature(row, exclusive) });
+    if (Buffer.byteLength(bytes) > 1024 * 1024) throw Error("Oversized native creation receipt");
+    const fd = fs.openSync(tmp, "wx", 0o600);
+    try { fs.writeFileSync(fd, bytes); fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+    if (!exclusive) fs.renameSync(tmp, file);
+  }
+}

package/src/native-relay-companion.mjs

@@ -32,9 +32,11 @@ import { hardenedBridgeEnabled } from "./hardened-root-policy.mjs";
 import { protectCurrentUserPipe } from "./windows-pipe-acl.mjs";
 import { createHardenedRootPolicy } from "./hardened-root-policy.mjs";
 
+import { NativeCreationReceipts, creationIdValid } from "./native-creation-receipts.mjs";
+
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.20.1";
+const VERSION = "1.21.1";
 const log = (msg) => process.stderr.write(`[native-relay] ${msg}\n`);
 
 function errorResponse(code, message, sent) {
@@ -238,12 +240,12 @@ export function createNativeScopeAuthorizer({ dispatchDesktop, env = process.env
  */
 export async function handleRelayRequest(
   payload,
-  { dispatch, dispatchDesktop, resolveExecutor = resolveRelayThreadId, env = process.env, assertAccount = assertAccountIdentity, authorize, strict = hardenedBridgeEnabled(env) } = {},
+  { dispatch, dispatchDesktop, resolveExecutor = resolveRelayThreadId, env = process.env, assertAccount = assertAccountIdentity, authorize, creationReceipts = new NativeCreationReceipts(), strict = hardenedBridgeEnabled(env) } = {},
 ) {
   if (strict && (!boundRequest(payload) || !validProtocol(payload))) return errorResponse("RELAY_BAD_REQUEST", "Hardened relay accepts only protocol 2 requests with account context", false);
   if (strict && typeof authorize !== "function") return errorResponse("NATIVE_SCOPE_UNVERIFIED", "Hardened relay requires verified current native project and task metadata; no dispatch was attempted", false);
   if (payload && typeof payload === "object" && Object.hasOwn(payload, "operation")) {
-    return handleDesktopRequest(payload, { dispatchDesktop, resolveExecutor, env, assertAccount, authorize, strict });
+    return handleDesktopRequest(payload, { dispatchDesktop, resolveExecutor, env, assertAccount, authorize, creationReceipts, strict });
   }
   if (!payload || typeof payload !== "object" || Array.isArray(payload) ||
       Object.keys(payload).some((key) => !["v", "targetThreadId", "message", "accountContext"].includes(key)) || !validProtocol(payload)) {
@@ -295,14 +297,15 @@ export async function handleRelayRequest(
   }
 }
 
-async function handleDesktopRequest(payload, { dispatchDesktop, resolveExecutor, env, assertAccount, authorize, strict = hardenedBridgeEnabled(env) }) {
+async function handleDesktopRequest(payload, { dispatchDesktop, resolveExecutor, env, assertAccount, authorize, creationReceipts, strict = hardenedBridgeEnabled(env) }) {
   if (strict && !boundRequest(payload)) return errorResponse("RELAY_BAD_REQUEST", "Hardened relay accepts only protocol 2 Desktop operations", false);
   if (Array.isArray(payload) || ![RELAY_PROTOCOL_VERSION, ACCOUNT_RELAY_PROTOCOL_VERSION].includes(payload.v) || !validProtocol(payload) ||
-      Object.keys(payload).some((key) => !["v", "operation", "arguments", "accountContext"].includes(key))) {
+      Object.keys(payload).some((key) => !["v", "operation", "arguments", "accountContext", "creationReceiptId"].includes(key))) {
     return errorResponse("RELAY_BAD_REQUEST", "expected an allowlisted Desktop operation");
   }
   try {
     validateDesktopOperation(payload.operation, payload.arguments);
+    if (payload.creationReceiptId !== undefined && (payload.operation !== "create_thread" || !boundRequest(payload) || !creationIdValid(payload.creationReceiptId))) throw new NativeRelayError("Invalid creation receipt binding", "RELAY_BAD_REQUEST");
     let accountContext;
     try {
       accountContext = await checkAccountContext(payload, assertAccount);
@@ -313,12 +316,29 @@ async function handleDesktopRequest(payload, { dispatchDesktop, resolveExecutor,
       return errorResponse("NATIVE_OPERATION_UNAVAILABLE", "This companion does not support Desktop operations; reload the native relay");
     }
     const executorThreadId = resolveExecutor(env).threadId;
+    if (payload.operation === "get_creation_receipt") {
+      if (!accountContext) throw new NativeRelayError("Creation receipts require bound accounts", "RELAY_BAD_REQUEST");
+      const row = creationReceipts.read(payload.arguments.receiptId, accountContext, payload.arguments.requestHash);
+      if (row && row.executorThreadId !== executorThreadId) throw new NativeRelayError("Creation receipt executor changed", "NATIVE_SCOPE_UNVERIFIED");
+      const original = row ? { executorThreadId, operation: "create_thread", arguments: row.args, accountContext } : { executorThreadId, operation: "list_projects", arguments: {}, accountContext };
+      if (strict) {
+        const initial = await authorize(original);
+        if (row?.state === "completed") await authorize({ ...original, phase: "return", expected: initial, result: row.result });
+      }
+      await assertAccount(accountContext);
+      return { ok: true, v: payload.v, operation: payload.operation, executorThreadId,
+        result: { status: row?.state ?? "missing", ...(row?.state === "completed" ? { result: row.result } : {}), ...(row?.state === "failed" ? { error: row.error } : {}) } };
+    }
     const request = { executorThreadId, targetThreadId: payload.arguments?.threadId, operation: payload.operation, arguments: payload.arguments, accountContext };
     const authorization = strict ? await authorize(request) : null;
     if (payload.operation === "send_message_to_thread" && payload.arguments.threadId === executorThreadId) {
       return errorResponse("RELAY_BAD_REQUEST", "The relay executor cannot receive its own relayed message");
     }
-    const nativeResult = await dispatchDesktop({
+    // Reserve before dispatch. A disconnected caller must not discard a late
+    // result, and even identical duplicate writes must not dispatch twice.
+    const creation = payload.creationReceiptId ? creationReceipts.reserve(payload.creationReceiptId, payload.arguments, accountContext, executorThreadId) : null;
+    let nativeResult;
+    try { nativeResult = await dispatchDesktop({
       executorThreadId,
       operation: payload.operation,
       arguments: payload.arguments,
@@ -328,6 +348,10 @@ async function handleDesktopRequest(payload, { dispatchDesktop, resolveExecutor,
     });
     const decoded = decodeNativeToolResult(nativeResult);
     const checked = strict ? await authorize({ ...request, phase: "return", expected: authorization, result: decoded }) : null;
+    if (creation) {
+      await assertAccount(accountContext);
+      creationReceipts.write({ ...creation, state: "completed", result: checked?.result ?? decoded });
+    }
     return {
       ok: true,
       v: boundRequest(payload) ? ACCOUNT_RELAY_PROTOCOL_VERSION : RELAY_PROTOCOL_VERSION,
@@ -335,6 +359,10 @@ async function handleDesktopRequest(payload, { dispatchDesktop, resolveExecutor,
       executorThreadId,
       result: checked?.result ?? decoded,
     };
+    } catch (error) {
+      if (creation) creationReceipts.write({ ...creation, state: "failed", error: { code: errorCode(error), message: error.message } });
+      throw error;
+    }
   } catch (err) {
     return errorResponse(errorCode(err), err?.message ?? String(err), err?.sent === false && err?.reachedCompanion !== true ? false : undefined);
   }
@@ -354,6 +382,7 @@ export class RelaySocketServer {
     resolveExecutor = resolveRelayThreadId,
     assertAccount = assertAccountIdentity,
     authorize,
+    creationReceipts = new NativeCreationReceipts(),
     requireAccountContext = false,
     strict = hardenedBridgeEnabled(),
     protectSocket = protectCurrentUserPipe,
@@ -368,6 +397,7 @@ export class RelaySocketServer {
     this.resolveExecutor = resolveExecutor;
     this.assertAccount = assertAccount;
     this.authorize = authorize;
+    this.creationReceipts = creationReceipts;
     this.requireAccountContext = requireAccountContext;
     this.strict = strict;
     this.protectSocket = protectSocket;
@@ -574,6 +604,7 @@ export class RelaySocketServer {
       assertAccount: this.assertAccount,
       authorize: this.authorize,
       strict: this.strict,
+      creationReceipts: this.creationReceipts,
     });
     if (!response.ok) this.log(`relay refused ${payload?.targetThreadId ?? "?"}: ${response.error.message}`);
     else this.log(response.operation ? `completed Desktop operation ${response.operation}` : `relayed a message into thread ${response.targetThreadId}`);

package/src/native-relay.mjs

@@ -177,6 +177,8 @@ export function nativeDispatchParams({ executorThreadId, targetThreadId, message
   };
 }
 
+import { creationIdValid } from "./native-creation-receipts.mjs";
+
 const DESKTOP_EFFORTS = new Set(["none", "minimal", "low", "medium", "high", "xhigh", "max", "ultra"]);
 
 function exactObject(value, keys) {
@@ -201,6 +203,9 @@ export function validateDesktopOperation(operation, args) {
   const modelSettings = () => optionalText(args.model) &&
     (args.thinking === undefined || DESKTOP_EFFORTS.has(args.thinking));
   switch (operation) {
+    case "get_creation_receipt":
+      valid = exactObject(args, ["receiptId", "requestHash"]) && creationIdValid(args.receiptId) && /^[a-f0-9]{64}$/.test(args.requestHash);
+      break;
     case "list_projects":
       valid = exactObject(args, []);
       break;
@@ -540,7 +545,10 @@ export async function resolveNativeToolsPipePath({
       const remaining = deadline - Date.now();
       if (remaining <= 0) break;
       try {
-        if (await probeWindowsPipe(candidate, { env, timeoutMs: Math.min(750, remaining) })) return candidate;
+        // Cold Desktop metadata reads can take over a second. Keep the shared
+        // seven-second discovery budget, but do not reject a valid endpoint
+        // merely because its first read exceeds the old 750ms probe window.
+        if (await probeWindowsPipe(candidate, { env, timeoutMs: Math.min(3000, remaining) })) return candidate;
       } catch {}
     }
     return null;
@@ -801,11 +809,12 @@ export class NativeDesktopRelay {
     return this.#request(request, timeoutMs, beforeSend);
   }
 
-  async requestDesktop(operation, args, { timeoutMs = this.timeoutMs, beforeSend, accountContext } = {}) {
+  async requestDesktop(operation, args, { timeoutMs = this.timeoutMs, beforeSend, accountContext, creationReceiptId } = {}) {
     validateDesktopOperation(operation, args);
     const accounts = relayAccountContext(accountContext);
     if (hardenedBridgeEnabled(this.env) && !accounts) throw beforeWriteError(new NativeRelayError("Hardened relay requires protocol 2 account context", "RELAY_BAD_REQUEST"));
-    return this.#request({ v: accounts ? ACCOUNT_RELAY_PROTOCOL_VERSION : RELAY_PROTOCOL_VERSION, operation, arguments: args, ...(accounts ? { accountContext: accounts } : {}) }, timeoutMs, beforeSend);
+    if (creationReceiptId !== undefined && (operation !== "create_thread" || !accounts || !creationIdValid(creationReceiptId))) throw beforeWriteError(new NativeRelayError("Invalid creation receipt binding", "RELAY_BAD_REQUEST"));
+    return this.#request({ v: accounts ? ACCOUNT_RELAY_PROTOCOL_VERSION : RELAY_PROTOCOL_VERSION, operation, arguments: args, ...(accounts ? { accountContext: accounts } : {}), ...(creationReceiptId ? { creationReceiptId } : {}) }, timeoutMs, beforeSend);
   }
 
   async #request(request, timeoutMs, beforeSend) {