@minhspark/codex-mcp-bridge 1.25.3 → 1.26.0

package/src/background-relay-service.mjs

@@ -0,0 +1,311 @@
+import { execFileSync, spawn as spawnProcess } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import { callBackgroundRelay } from "./background-relay-client.mjs";
+import { privateRelayDirectory, readRelayConfiguration, relayPaths, writeRelayJson } from "./background-relay-config.mjs";
+import { isMainModule, stableNodeBin } from "./install-paths.mjs";
+import { directoryBinding, readRegularConfigFile } from "./project-policy.mjs";
+
+export const RELAY_SERVICE_OWNER = "@minhspark/codex-mcp-bridge/background-relay-service/v1";
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const SOURCE = fileURLToPath(import.meta.url);
+const sourceHash = () => createHash("sha256").update(fs.readFileSync(SOURCE)).digest("hex");
+const SOURCE_HASH = sourceHash();
+const DIAGNOSTIC_LIMIT = 64 * 1024;
+const MESSAGES = {
+  SERVICE_CONFIG_INVALID: "The background relay configuration could not be loaded",
+  SERVICE_STORAGE_UNSAFE: "Background relay service storage could not be verified",
+  SERVICE_LOCK_OCCUPIED: "Another background relay service owns the service lock",
+  SERVICE_PROCESS_IDENTITY_UNAVAILABLE: "The background relay service process identity could not be verified",
+  DAEMON_START_FAILED: "The background relay daemon could not be started",
+  DAEMON_EXITED: "The background relay daemon exited unexpectedly; active work must be checked before retrying",
+  SERVICE_RUNTIME_FAILED: "The background relay service could not continue",
+  SERVICE_RUNTIME_INVALID: "The desired background relay runtime could not be verified",
+  SERVICE_MIGRATION_PENDING: "The service could not request an idle runtime update; existing jobs were left running",
+};
+
+function serviceFailure(code) {
+  return Object.assign(new Error(MESSAGES[code]), { code });
+}
+
+function daemonDiagnostic(line) {
+  if (Buffer.byteLength(line) > 8192) return null;
+  let value;
+  try { value = JSON.parse(line)?.diagnostic; } catch { return null; }
+  const validCode = (code) => typeof code === "string" && /^[A-Z][A-Z0-9_]{0,79}$/.test(code);
+  if (value?.schemaVersion !== 1 || value.component !== "background-relay" || !validCode(value.code)) return null;
+  const deliveryState = ["not_sent", "sent", "unknown", "not_applicable"].includes(value.deliveryState) ? value.deliveryState : "unknown";
+  return { schemaVersion: 1, component: "background-relay", code: value.code,
+    causeCodes: Array.isArray(value.causeCodes) ? [...new Set(value.causeCodes.filter(validCode))].filter((code) => code !== value.code).slice(0, 8) : [],
+    operation: ["startup", "watch_update"].includes(value.operation) ? value.operation : "startup",
+    phase: ["startup", "preflight", "inspection", "configuration", "storage", "transport", "relay", "delivery"].includes(value.phase) ? value.phase : "startup",
+    deliveryState, sent: deliveryState === "not_sent" ? false : deliveryState === "sent" ? true : null };
+}
+
+function alive(pid) {
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return error.code !== "ESRCH"; }
+}
+
+function processIdentity(pid) {
+  try {
+    const options = { windowsHide: true, shell: false, encoding: "utf8", timeout: 30000, maxBuffer: 4096, stdio: ["ignore", "pipe", "pipe"] };
+    const output = process.platform === "win32"
+      ? execFileSync(path.join(process.env.SystemRoot || "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "powershell.exe"),
+        ["-NoProfile", "-NonInteractive", "-WindowStyle", "Hidden", "-Command", `[System.Diagnostics.Process]::GetProcessById(${pid}).StartTime.ToUniversalTime().ToFileTimeUtc().ToString()`], options)
+      : execFileSync("/bin/ps", ["-o", "lstart=", "-p", String(pid)], { ...options, env: { ...process.env, LC_ALL: "C", TZ: "UTC" } });
+    const value = output.trim();
+    return value && value.length < 128 && !/[\u0000-\u001f\u007f]/.test(value) ? value : null;
+  } catch { return null; }
+}
+
+export function relayServiceRuntimeId(runtime) {
+  return createHash("sha256").update(JSON.stringify([runtime.packageRoot, runtime.nodeExecutable, runtime.packageVersion ?? null, runtime.environment ?? {}])).digest("hex");
+}
+
+export function readRelayServiceRuntime(directory, { root = ROOT, nodeExecutable = stableNodeBin() } = {}) {
+  let text;
+  try { text = readRegularConfigFile(path.join(directory, "service-runtime.json"), { missing: true, maxBytes: 64 * 1024 }); }
+  catch { throw serviceFailure("SERVICE_RUNTIME_INVALID"); }
+  if (text === null) return { schemaVersion: 1, owner: RELAY_SERVICE_OWNER, packageRoot: root, nodeExecutable };
+  let value;
+  try { value = JSON.parse(text); } catch { throw serviceFailure("SERVICE_RUNTIME_INVALID"); }
+  if (value?.schemaVersion !== 1 || value.owner !== RELAY_SERVICE_OWNER
+      || value.packageVersion !== undefined && (typeof value.packageVersion !== "string" || !/^\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.+-]+)?$/.test(value.packageVersion) || value.packageVersion.length > 96)
+      || ![value.packageRoot, value.nodeExecutable].every((entry) => typeof entry === "string" && path.isAbsolute(entry) && !/[\u0000-\u001f\u007f]/.test(entry))
+      || value.environment !== undefined && (!value.environment || typeof value.environment !== "object" || Array.isArray(value.environment)
+        || Object.entries(value.environment).some(([name, entry]) => !["HOME", "PATH", "CODEX_HOME", "CLAUDE_CONFIG_DIR", "XDG_CONFIG_HOME"].includes(name)
+          || typeof entry !== "string" || !entry || /[\u0000-\u001f\u007f]/.test(entry)))
+      || ![path.join(value.packageRoot, "src", "background-relay-service.mjs"), path.join(value.packageRoot, "src", "background-relay-daemon.mjs"), value.nodeExecutable].every((entry) => {
+        try { return fs.statSync(entry).isFile(); } catch { return false; }
+      })) throw serviceFailure("SERVICE_RUNTIME_INVALID");
+  return value;
+}
+
+export function acquireRelayServiceLock(root, { pid = process.pid, isAlive = alive, identity = processIdentity } = {}) {
+  if (!Number.isSafeInteger(pid) || pid < 1) throw serviceFailure("SERVICE_PROCESS_IDENTITY_UNAVAILABLE");
+  if (typeof root !== "string" || !path.isAbsolute(root) || /[\u0000-\u001f\u007f]/.test(root)) throw serviceFailure("SERVICE_STORAGE_UNSAFE");
+  privateRelayDirectory(root);
+  const binding = directoryBinding(root);
+  const file = path.resolve(binding.path, "service.lock");
+  if (!file.startsWith(binding.path.endsWith(path.sep) ? binding.path : `${binding.path}${path.sep}`)) throw serviceFailure("SERVICE_STORAGE_UNSAFE");
+  const assertDirectory = () => {
+    const current = directoryBinding(root);
+    if (current.path !== binding.path || current.identity !== binding.identity) throw serviceFailure("SERVICE_STORAGE_UNSAFE");
+  };
+  const sameFile = (expected) => {
+    const current = fs.lstatSync(file, { bigint: true });
+    return current.isFile() && !current.isSymbolicLink() && current.nlink === 1n
+      && ["dev", "ino", "birthtimeNs"].every((field) => current[field] === expected[field]);
+  };
+  const nonce = randomUUID();
+  const processStart = identity(pid);
+  if (typeof processStart !== "string" || !processStart) throw serviceFailure("SERVICE_PROCESS_IDENTITY_UNAVAILABLE");
+  const value = JSON.stringify({ schemaVersion: 1, owner: RELAY_SERVICE_OWNER, pid, processStart, nonce });
+  for (let attempt = 0; attempt < 2; attempt++) {
+    let descriptor;
+    try {
+      assertDirectory();
+      descriptor = fs.openSync(file, "wx", 0o600);
+      const created = fs.fstatSync(descriptor, { bigint: true });
+      fs.writeFileSync(descriptor, value);
+      fs.fsyncSync(descriptor);
+      fs.closeSync(descriptor);
+      descriptor = undefined;
+      return { acquired: true, release() {
+        assertDirectory();
+        if (readRegularConfigFile(file, { missing: true, maxBytes: 4096 }) === value) {
+          if (!sameFile(created)) throw serviceFailure("SERVICE_STORAGE_UNSAFE");
+          assertDirectory();
+          fs.unlinkSync(file);
+        }
+      } };
+    } catch (error) {
+      if (descriptor !== undefined) { try { fs.closeSync(descriptor); } catch {} }
+      if (error.code !== "EEXIST") throw serviceFailure("SERVICE_STORAGE_UNSAFE");
+      let raw;
+      let existing;
+      let before;
+      try {
+        assertDirectory();
+        before = fs.lstatSync(file, { bigint: true });
+        raw = readRegularConfigFile(file, { maxBytes: 4096 });
+        existing = JSON.parse(raw);
+      } catch { throw serviceFailure("SERVICE_STORAGE_UNSAFE"); }
+      if (existing?.owner !== RELAY_SERVICE_OWNER || existing.schemaVersion !== 1
+          || !Number.isSafeInteger(existing.pid) || existing.pid < 1 || typeof existing.nonce !== "string"
+          || typeof existing.processStart !== "string" || !existing.processStart) throw serviceFailure("SERVICE_STORAGE_UNSAFE");
+      if (isAlive(existing.pid)) {
+        const currentIdentity = identity(existing.pid);
+        if (!currentIdentity) throw serviceFailure("SERVICE_PROCESS_IDENTITY_UNAVAILABLE");
+        if (currentIdentity === existing.processStart) return { acquired: false, release() {} };
+      }
+      assertDirectory();
+      if (readRegularConfigFile(file, { maxBytes: 4096 }) !== raw || !sameFile(before)) throw serviceFailure("SERVICE_STORAGE_UNSAFE");
+      try { fs.unlinkSync(file); }
+      catch { throw serviceFailure("SERVICE_STORAGE_UNSAFE"); }
+    }
+  }
+  throw serviceFailure("SERVICE_LOCK_OCCUPIED");
+}
+
+function wait(ms, signal) {
+  return new Promise((resolve) => {
+    if (signal?.aborted) return resolve();
+    const finish = () => { clearTimeout(timer); signal?.removeEventListener("abort", finish); resolve(); };
+    const timer = setTimeout(finish, ms);
+    signal?.addEventListener("abort", finish, { once: true });
+  });
+}
+
+function serviceEnvironment(env, root) {
+  return { ...Object.fromEntries(Object.entries(env).filter(([name, value]) => value !== undefined
+    && !/^(?:AGENT_RELAY_|CODEX_BRIDGE_|CLAUDE_BRIDGE_|CODEX_NATIVE_RELAY_|CODEX_APP_TOOLS_PIPE_PATH$|CODEX_APP_SERVER_URL$|CODEX_INTERNAL_ORIGINATOR_OVERRIDE$|CODEX_THREAD_ID$|CODEX_SESSION_ID$|CODEX_RELAY_ID$)/i.test(name))), AGENT_RELAY_DIRECTORY: root };
+}
+
+export async function runBackgroundRelayService({ env = process.env, platform = process.platform, root = ROOT,
+  spawn = spawnProcess, signal, sleep = wait, now = Date.now, readConfig = readRelayConfiguration,
+  writeState = writeRelayJson, acquireLock = acquireRelayServiceLock, changed = () => sourceHash() !== SOURCE_HASH,
+  readRuntime = readRelayServiceRuntime, callRelay = callBackgroundRelay, watchIntervalMs = 2000 } = {}) {
+  let config;
+  try { config = readConfig({ env, platform }); }
+  catch { throw serviceFailure("SERVICE_CONFIG_INVALID"); }
+  if (!config.enabled) return { status: "disabled" };
+  const lock = acquireLock(config.paths.root);
+  if (!lock.acquired) return { status: "already-running" };
+  const statusFile = path.join(config.paths.root, "service-status.json");
+  const errorFile = path.join(config.paths.root, "last-service-error.json");
+  let failures = 0;
+  const state = (status, extra = {}) => writeState(statusFile, { schemaVersion: 1, owner: RELAY_SERVICE_OWNER,
+    pid: process.pid, status, updatedAt: new Date(now()).toISOString(), ...extra });
+  const record = (code, extra = {}) => writeState(errorFile, { schemaVersion: 1, owner: RELAY_SERVICE_OWNER,
+    code, message: MESSAGES[code], at: new Date(now()).toISOString(), ...extra });
+  try {
+    while (!signal?.aborted) {
+      try { config = readConfig({ env, platform }); }
+      catch { record("SERVICE_CONFIG_INVALID"); state("failed"); throw serviceFailure("SERVICE_CONFIG_INVALID"); }
+      if (!config.enabled) { state("disabled"); return { status: "disabled" }; }
+      const runtime = readRuntime(config.paths.root, { root, nodeExecutable: stableNodeBin(env) });
+      if (path.resolve(runtime.packageRoot) !== path.resolve(root)) {
+        state("reloading");
+        return { status: "reload", moduleFile: path.join(runtime.packageRoot, "src", "background-relay-service.mjs") };
+      }
+      const runtimeId = relayServiceRuntimeId(runtime);
+      const childEnv = { ...serviceEnvironment(env, config.paths.root), ...runtime.environment, AGENT_RELAY_RUNTIME_ID: runtimeId };
+      const started = now();
+      state("starting", { consecutiveFailures: failures, runtimeId });
+      const outcome = await new Promise((resolve) => {
+        let child;
+        let settled = false;
+        let checking = false;
+        let poll;
+        let diagnostic = null;
+        let stderr = "";
+        let stderrBytes = 0;
+        let stderrTruncated = false;
+        const captureDiagnostic = (chunk) => {
+          if (settled) return;
+          const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+          const remaining = DIAGNOSTIC_LIMIT - stderrBytes;
+          if (bytes.length > remaining) stderrTruncated = true;
+          if (remaining <= 0) return;
+          const bounded = bytes.subarray(0, remaining);
+          stderrBytes += bounded.length;
+          stderr += bounded.toString("utf8");
+          let newline;
+          while ((newline = stderr.indexOf("\n")) >= 0) {
+            diagnostic = daemonDiagnostic(stderr.slice(0, newline)) ?? diagnostic;
+            stderr = stderr.slice(newline + 1);
+          }
+        };
+        const finish = (value) => {
+          if (settled) return;
+          settled = true;
+          clearInterval(poll);
+          signal?.removeEventListener("abort", stop);
+          diagnostic = daemonDiagnostic(stderr) ?? diagnostic;
+          resolve({ ...value, ...(diagnostic ? { diagnostic } : {}), ...(stderrTruncated ? { stderrTruncated: true } : {}) });
+        };
+        const stop = () => { try { child?.kill("SIGTERM"); } catch {} };
+        signal?.addEventListener("abort", stop, { once: true });
+        try {
+          child = spawn(runtime.nodeExecutable, [path.join(root, "src", "background-relay-daemon.mjs")], {
+            cwd: root, env: childEnv, windowsHide: true, shell: false, stdio: ["ignore", "ignore", "pipe"],
+          });
+          child.stderr?.on("error", () => {});
+          child.stderr?.on("data", captureDiagnostic);
+          child.on("spawn", () => {
+            if (signal?.aborted) return stop();
+            try { state("running", { daemonPid: Number.isSafeInteger(child.pid) ? child.pid : null, consecutiveFailures: failures, runtimeId }); }
+            catch { finish({ code: null, failure: "SERVICE_STORAGE_UNSAFE" }); stop(); return; }
+            poll = setInterval(async () => {
+              if (checking || settled || signal?.aborted) return;
+              checking = true;
+              try {
+                const desired = readRuntime(config.paths.root, { root, nodeExecutable: stableNodeBin(env) });
+                if (relayServiceRuntimeId(desired) !== runtimeId || changed()) {
+                  await callRelay("drain", {}, { env: childEnv, connection: { endpoint: config.endpoint, token: config.token, workerId: null }, timeoutMs: 1000 });
+                }
+              } catch {
+                if (!settled) { try { record("SERVICE_MIGRATION_PENDING"); } catch {} }
+              } finally { checking = false; }
+            }, watchIntervalMs);
+          });
+          child.on("error", () => finish({ code: null, failure: "DAEMON_START_FAILED" }));
+          child.on("close", (code) => finish({ code: Number.isInteger(code) ? code : null }));
+        } catch { finish({ code: null, failure: "DAEMON_START_FAILED" }); }
+      });
+      if (signal?.aborted) { state("stopped"); return { status: "stopped" }; }
+      if (outcome.failure === "SERVICE_STORAGE_UNSAFE") throw serviceFailure("SERVICE_STORAGE_UNSAFE");
+      if (outcome.code === 75) {
+        failures = 0;
+        const desired = readRuntime(config.paths.root, { root, nodeExecutable: stableNodeBin(env) });
+        if (changed() || path.resolve(desired.packageRoot) !== path.resolve(root)) {
+          state("reloading");
+          return { status: "reload", moduleFile: path.join(desired.packageRoot, "src", "background-relay-service.mjs") };
+        }
+        state("restarting", { reason: "idle-code-reload", restartDelayMs: 250 });
+        await sleep(250, signal);
+        continue;
+      }
+      failures = now() - started >= 60000 ? 1 : failures + 1;
+      const delay = Math.min(30000, 500 * 2 ** Math.min(failures - 1, 10));
+      const code = outcome.failure ?? "DAEMON_EXITED";
+      record(code, { daemonExitCode: outcome.code, consecutiveFailures: failures, restartDelayMs: delay,
+        ...(outcome.diagnostic ? { daemonDiagnostic: outcome.diagnostic } : {}),
+        ...(outcome.stderrTruncated ? { daemonDiagnosticTruncated: true } : {}) });
+      state("restarting", { code, consecutiveFailures: failures, restartDelayMs: delay });
+      await sleep(delay, signal);
+    }
+    state("stopped");
+    return { status: "stopped" };
+  } finally { lock.release(); }
+}
+
+if (!new URL(import.meta.url).search && isMainModule(process.argv[1], import.meta.url)) {
+  const controller = new AbortController();
+  const stop = () => controller.abort();
+  process.on("SIGINT", stop);
+  process.on("SIGTERM", stop);
+  try {
+    let run = runBackgroundRelayService;
+    while (true) {
+      const result = await run({ signal: controller.signal });
+      if (result.status !== "reload") break;
+      run = (await import(`${result.moduleFile ? pathToFileURL(result.moduleFile).href : import.meta.url}?reload=${randomUUID()}`)).runBackgroundRelayService;
+    }
+  } catch (error) {
+    const code = Object.hasOwn(MESSAGES, error.code) ? error.code : "SERVICE_RUNTIME_FAILED";
+    try { writeRelayJson(path.join(relayPaths().root, "last-service-error.json"), {
+      schemaVersion: 1, owner: RELAY_SERVICE_OWNER, code, message: MESSAGES[code], at: new Date().toISOString(),
+    }); } catch {}
+    process.stderr.write(`${code}: ${MESSAGES[code]}\n`);
+    process.exitCode = 1;
+  } finally {
+    process.removeListener("SIGINT", stop);
+    process.removeListener("SIGTERM", stop);
+  }
+}

package/src/background-relay-storage.mjs

@@ -0,0 +1,203 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const caches = new WeakMap();
+const writes = new WeakMap();
+const helper = fileURLToPath(new URL("./background-relay-storage.ps1", import.meta.url));
+const unsafe = () => Object.assign(new Error("Relay storage must be owned by the current user and inaccessible to other users"), { code: "WORKER_STORAGE_UNSAFE", phase: "storage", deliveryState: "not_sent", sent: false });
+const changed = () => Object.assign(new Error("Relay storage kept changing during privacy verification; retry after the current update finishes"), { code: "WORKER_STORAGE_CHANGED", phase: "storage", deliveryState: "not_sent", sent: false });
+
+function targetPath(input) {
+  if (typeof input !== "string" || !path.isAbsolute(input) || input.includes("\0")) throw unsafe();
+  const target = path.resolve(input);
+  if (target === path.parse(target).root || target === path.resolve(os.homedir())) throw unsafe();
+  return target;
+}
+
+function inspectPath(target, kind, missing = false) {
+  let stat;
+  try { stat = fs.lstatSync(target, { bigint: true }); }
+  catch (error) { if (missing && error.code === "ENOENT") return null; throw unsafe(); }
+  if (stat.isSymbolicLink() || kind === "directory" && !stat.isDirectory() || kind === "file" && (!stat.isFile() || stat.nlink !== 1n)) throw unsafe();
+  return stat;
+}
+
+const identity = stat => [stat.dev, stat.ino, stat.birthtimeNs, stat.ctimeNs, stat.mtimeNs, stat.size, stat.mode, stat.nlink].join(":");
+const cacheKey = (target, kind) => `${kind}:${target.toLowerCase()}`;
+const sameNode = (left, right) => left.dev === right.dev && left.ino === right.ino;
+const sameObject = (left, right) => ["dev", "ino", "birthtimeNs", "uid", "mode"].every(key => left[key] === right[key])
+  && (left.isDirectory() && right.isDirectory() || left.nlink === right.nlink);
+const validReadback = (value, kind) => value?.ownerTrusted === true && value?.allowedPrincipalsOnly === true && value?.currentUserFullControl === true
+  && value?.noReparse === true && (kind !== "directory" || value?.protected === true) && value?.kind === kind;
+
+function runWindowsHelper(target, kind, mode, run, input, timeout = 15000) {
+  const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => key.toLowerCase() !== "psmodulepath"));
+  const windows = process.env.SystemRoot || "C:\\Windows";
+  env.PSModulePath = path.win32.join(windows, "System32", "WindowsPowerShell", "v1.0", "Modules");
+  try {
+    const response = run(path.win32.join(windows, "System32", "WindowsPowerShell", "v1.0", "powershell.exe"),
+      ["-NoProfile", "-NonInteractive", "-File", helper, "-LiteralPath", target, "-Kind", kind, "-Mode", mode],
+      { env, windowsHide: true, shell: false, stdio: [input === undefined ? "ignore" : "pipe", "pipe", "pipe"], input,
+        timeout, maxBuffer: mode === "batch" ? 2 * 1024 * 1024 : 16384, encoding: "utf8" });
+    if (response && typeof response === "object" && !Buffer.isBuffer(response) && (response.status ?? response.exitCode ?? 0) !== 0) throw unsafe();
+    return JSON.parse(typeof response === "object" && !Buffer.isBuffer(response) ? response.stdout : String(response));
+  } catch { throw unsafe(); }
+}
+
+function windowsPrivacy(target, kind, mode, stat, run) {
+  let cache = caches.get(run);
+  if (!cache) { cache = new Map(); caches.set(run, cache); }
+  const key = cacheKey(target, kind);
+  const previous = cache.get(key);
+  if (previous?.identity === identity(stat)) return stat;
+  const deadline = Date.now() + 15000;
+  try {
+    for (let attempt = 0; attempt < 3; attempt++) {
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) throw changed();
+      const result = runWindowsHelper(target, kind, mode, run, undefined, remaining);
+      const current = inspectPath(target, kind);
+      if (current.dev !== stat.dev || current.ino !== stat.ino || current.birthtimeNs !== stat.birthtimeNs || !validReadback(result, kind)) throw unsafe();
+      if (mode === "assert" && identity(current) !== identity(stat)) { stat = current; continue; }
+      cache.set(key, { identity: identity(current) });
+      if (cache.size > 2048) cache.delete(cache.keys().next().value);
+      return current;
+    }
+    throw changed();
+  } catch (error) { cache.delete(key); throw error; }
+}
+
+function assertPrivacy(target, kind, stat, { platform = process.platform, run = execFileSync } = {}) {
+  if (platform === "win32") return windowsPrivacy(target, kind, "assert", stat, run);
+  if (typeof process.getuid !== "function" || stat.uid !== BigInt(process.getuid()) || (stat.mode & 0o7777n) !== (kind === "directory" ? 0o700n : 0o600n)) throw unsafe();
+  return stat;
+}
+
+export function assertPrivateRelayDirectory(input, options = {}) {
+  const target = targetPath(input);
+  return assertPrivacy(target, "directory", inspectPath(target, "directory"), options);
+}
+
+export function assertPrivateRelayFile(input, { missing = false, ...options } = {}) {
+  const target = targetPath(input);
+  assertPrivateRelayDirectory(path.dirname(target), options);
+  const stat = inspectPath(target, "file", missing);
+  return stat === null ? null : assertPrivacy(target, "file", stat, options);
+}
+
+export function assertPrivateRelayFiles(inputs, { platform = process.platform, run = execFileSync } = {}) {
+  if (!Array.isArray(inputs) || inputs.length > 1024) throw unsafe();
+  if (!inputs.length) return [];
+  const files = inputs.map(targetPath);
+  const directory = path.dirname(files[0]);
+  const names = files.map(file => path.basename(file));
+  if (files.some(file => path.dirname(file) !== directory) || names.some(name => /[\\/:]/.test(name))
+    || new Set(files.map(file => platform === "win32" ? file.toLowerCase() : file)).size !== files.length) throw unsafe();
+  const input = JSON.stringify({ files: names });
+  if (Buffer.byteLength(input) > 1024 * 1024) throw unsafe();
+  const before = inspectPath(directory, "directory");
+  const states = files.map(file => inspectPath(file, "file"));
+  if (platform !== "win32") {
+    assertPrivacy(directory, "directory", before, { platform, run });
+    return states.map((stat, index) => assertPrivacy(files[index], "file", stat, { platform, run }));
+  }
+  let cache = caches.get(run);
+  if (!cache) { cache = new Map(); caches.set(run, cache); }
+  const pending = files.flatMap((file, index) => cache.get(cacheKey(file, "file"))?.identity === identity(states[index]) ? [] : [index]);
+  if (!pending.length && cache.get(cacheKey(directory, "directory"))?.identity === identity(before)) return states;
+  try {
+    const result = runWindowsHelper(directory, "directory", "batch", run, JSON.stringify({ files: pending.map(index => names[index]) }));
+    if (!validReadback(result?.directory, "directory") || !Array.isArray(result?.files) || result.files.length !== pending.length) throw unsafe();
+    for (let index = 0; index < pending.length; index++) {
+      if (result.files[index]?.name !== names[pending[index]] || !validReadback(result.files[index]?.state, "file")) throw unsafe();
+    }
+    const currentDirectory = inspectPath(directory, "directory");
+    const current = files.map(file => inspectPath(file, "file"));
+    if (identity(before) !== identity(currentDirectory) || current.some((stat, index) => identity(stat) !== identity(states[index]))) throw unsafe();
+    cache.set(cacheKey(directory, "directory"), { identity: identity(currentDirectory) });
+    for (const index of pending) cache.set(cacheKey(files[index], "file"), { identity: identity(current[index]) });
+    while (cache.size > 2048) cache.delete(cache.keys().next().value);
+    return current;
+  } catch {
+    cache.delete(cacheKey(directory, "directory"));
+    for (const file of files) cache.delete(cacheKey(file, "file"));
+    throw unsafe();
+  }
+}
+
+export function protectPrivateRelayDirectory(input, { platform = process.platform, run = execFileSync } = {}) {
+  const target = targetPath(input);
+  try { fs.mkdirSync(target, { recursive: true, mode: 0o700 }); } catch { throw unsafe(); }
+  const before = inspectPath(target, "directory");
+  if (platform === "win32") return windowsPrivacy(target, "directory", "protect", before, run);
+  if (typeof process.getuid !== "function" || before.uid !== BigInt(process.getuid())) throw unsafe();
+  let descriptor;
+  try {
+    descriptor = fs.openSync(target, fs.constants.O_RDONLY | (fs.constants.O_DIRECTORY ?? 0) | (fs.constants.O_NOFOLLOW ?? 0));
+    const opened = fs.fstatSync(descriptor, { bigint: true });
+    if (!opened.isDirectory() || opened.dev !== before.dev || opened.ino !== before.ino || opened.uid !== before.uid) throw unsafe();
+    if ((opened.mode & 0o7777n) !== 0o700n) fs.fchmodSync(descriptor, 0o700);
+  } catch { throw unsafe(); }
+  finally { if (descriptor !== undefined) fs.closeSync(descriptor); }
+  const after = inspectPath(target, "directory");
+  if (before.dev !== after.dev || before.ino !== after.ino) throw unsafe();
+  return assertPrivacy(target, "directory", after, { platform, run });
+}
+
+export function beginPrivateRelayWrite(input, { platform = process.platform, run = execFileSync } = {}) {
+  const file = targetPath(input);
+  const directory = path.dirname(file);
+  protectPrivateRelayDirectory(directory, { platform, run });
+  assertPrivateRelayFile(file, { missing: true, platform, run });
+  const before = assertPrivateRelayDirectory(directory, { platform, run });
+  const ticket = Object.freeze({});
+  writes.set(ticket, { file, directory, before, platform, run });
+  return ticket;
+}
+
+export function bindPrivateRelayWrite(ticket, temporary, descriptor) {
+  const pending = writes.get(ticket);
+  if (!pending || pending.temporary || typeof temporary !== "string" || path.dirname(temporary) !== pending.directory
+    || !path.basename(temporary).startsWith(`.${path.basename(pending.file)}.`) || !temporary.endsWith(".tmp") || !Number.isInteger(descriptor)) throw unsafe();
+  const opened = fs.fstatSync(descriptor, { bigint: true });
+  const current = inspectPath(temporary, "file");
+  if (!opened.isFile() || opened.nlink !== 1n || identity(opened) !== identity(current)) throw unsafe();
+  if (pending.platform !== "win32") assertPrivacy(temporary, "file", current, pending);
+  pending.temporary = temporary;
+  pending.created = opened;
+}
+
+export function abortPrivateRelayWrite(ticket) {
+  const pending = writes.get(ticket);
+  if (!pending) return;
+  writes.delete(ticket);
+  const cache = caches.get(pending.run);
+  cache?.delete(cacheKey(pending.directory, "directory"));
+  cache?.delete(cacheKey(pending.file, "file"));
+}
+
+export function finishPrivateRelayWrite(ticket) {
+  const pending = writes.get(ticket);
+  if (!pending?.created) throw unsafe();
+  try {
+    const directory = inspectPath(pending.directory, "directory");
+    const file = inspectPath(pending.file, "file");
+    if (pending.created.size !== file.size || fs.existsSync(pending.temporary)) throw unsafe();
+    if (pending.platform === "win32") {
+      if (!sameObject(pending.before, directory) || !sameObject(pending.created, file) || pending.created.mtimeNs !== file.mtimeNs) throw unsafe();
+      const cache = caches.get(pending.run);
+      if (cache?.get(cacheKey(pending.directory, "directory"))?.identity !== identity(pending.before)) throw unsafe();
+      cache.set(cacheKey(pending.directory, "directory"), { identity: identity(directory) });
+      cache.set(cacheKey(pending.file, "file"), { identity: identity(file) });
+      if (cache.size > 2048) cache.delete(cache.keys().next().value);
+    } else {
+      if (!sameNode(pending.before, directory) || !sameNode(pending.created, file)) throw unsafe();
+      assertPrivacy(pending.directory, "directory", directory, pending);
+      assertPrivacy(pending.file, "file", file, pending);
+    }
+    writes.delete(ticket);
+  } catch (error) { abortPrivateRelayWrite(ticket); throw error; }
+}

package/src/background-relay-storage.ps1

@@ -0,0 +1,64 @@
+param(
+  [Parameter(Mandatory = $true)][string]$LiteralPath,
+  [Parameter(Mandatory = $true)][ValidateSet('directory', 'file')][string]$Kind,
+  [Parameter(Mandatory = $true)][ValidateSet('protect', 'assert', 'batch')][string]$Mode
+)
+$ErrorActionPreference = 'Stop'
+[Console]::InputEncoding = New-Object Text.UTF8Encoding($false)
+[Console]::OutputEncoding = New-Object Text.UTF8Encoding($false)
+function Get-PrivateStorageState([string]$EntryPath, [string]$EntryKind, [bool]$Protect) {
+  $item = Get-Item -LiteralPath $EntryPath -Force
+  if (($item.Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0) { throw 'Unsafe path' }
+  if (($EntryKind -eq 'directory') -ne [bool]$item.PSIsContainer) { throw 'Wrong path type' }
+  if ($Protect -and $EntryKind -ne 'directory') { throw 'Invalid protection scope' }
+  $acl = Get-Acl -LiteralPath $EntryPath
+  $owner = $acl.GetOwner([Security.Principal.SecurityIdentifier]).Value
+  if ($trusted -notcontains $owner) { throw 'Untrusted owner' }
+  if ($Protect) {
+    $replacement = New-Object Security.AccessControl.DirectorySecurity
+    $replacement.SetAccessRuleProtection($true, $false)
+    foreach ($sidValue in $trusted) {
+      $sid = New-Object Security.Principal.SecurityIdentifier($sidValue)
+      $rule = New-Object Security.AccessControl.FileSystemAccessRule($sid, [Security.AccessControl.FileSystemRights]::FullControl, ([Security.AccessControl.InheritanceFlags]::ContainerInherit -bor [Security.AccessControl.InheritanceFlags]::ObjectInherit), [Security.AccessControl.PropagationFlags]::None, [Security.AccessControl.AccessControlType]::Allow)
+      $replacement.AddAccessRule($rule)
+    }
+    [IO.Directory]::SetAccessControl($EntryPath, $replacement)
+    $acl = Get-Acl -LiteralPath $EntryPath
+  }
+  $ownerTrusted = $trusted -contains $acl.GetOwner([Security.Principal.SecurityIdentifier]).Value
+  $allowedOnly = $true
+  $userFullControl = $false
+  $rules = $acl.GetAccessRules($true, $true, [Security.Principal.SecurityIdentifier])
+  foreach ($rule in $rules) {
+    if ($trusted -notcontains $rule.IdentityReference.Value -or $rule.AccessControlType -ne [Security.AccessControl.AccessControlType]::Allow) { $allowedOnly = $false }
+    if ($rule.IdentityReference.Value -eq $currentSid.Value -and $rule.AccessControlType -eq [Security.AccessControl.AccessControlType]::Allow -and ($rule.FileSystemRights -band [Security.AccessControl.FileSystemRights]::FullControl) -eq [Security.AccessControl.FileSystemRights]::FullControl -and ($rule.PropagationFlags -band [Security.AccessControl.PropagationFlags]::InheritOnly) -eq 0) { $userFullControl = $true }
+  }
+  $item = Get-Item -LiteralPath $EntryPath -Force
+  return @{ ownerTrusted = $ownerTrusted; allowedPrincipalsOnly = $allowedOnly; currentUserFullControl = $userFullControl; protected = $acl.AreAccessRulesProtected; noReparse = (($item.Attributes -band [IO.FileAttributes]::ReparsePoint) -eq 0); kind = $EntryKind }
+}
+try {
+  $currentSid = [Security.Principal.WindowsIdentity]::GetCurrent().User
+  $trusted = @($currentSid.Value, 'S-1-5-18', 'S-1-5-32-544') | Select-Object -Unique
+  if ($Mode -eq 'batch') {
+    if ($Kind -ne 'directory') { throw 'Invalid batch scope' }
+    $encoded = [Console]::In.ReadToEnd()
+    if ($encoded.Length -gt 1048576) { throw 'Batch limit exceeded' }
+    $request = ConvertFrom-Json -InputObject $encoded
+    if ($request.files -isnot [Array] -or $request.files.Count -gt 1024) { throw 'Invalid batch' }
+    $directoryState = Get-PrivateStorageState $LiteralPath 'directory' $false
+    if (-not ($directoryState.ownerTrusted -and $directoryState.allowedPrincipalsOnly -and $directoryState.currentUserFullControl -and $directoryState.protected -and $directoryState.noReparse)) { throw 'Unsafe directory' }
+    $results = New-Object 'System.Collections.Generic.List[object]'
+    foreach ($entryName in $request.files) {
+      if ($entryName -isnot [string] -or $entryName.Length -eq 0 -or $entryName -match '[\\/:]' -or $entryName -eq '.' -or $entryName -eq '..') { throw 'Invalid batch path' }
+      $entryPath = [IO.Path]::Combine($LiteralPath, $entryName)
+      $entryState = Get-PrivateStorageState $entryPath 'file' $false
+      $results.Add(@{ name = $entryName; state = $entryState })
+    }
+    @{ directory = $directoryState; files = @($results.ToArray()) } | ConvertTo-Json -Compress -Depth 6
+  } else {
+    Get-PrivateStorageState $LiteralPath $Kind ($Mode -eq 'protect') | ConvertTo-Json -Compress
+  }
+} catch {
+  [Console]::Error.WriteLine('Private relay storage verification failed')
+  exit 1
+}