@remodex/rmx 1.0.2

package/src/lib/local-management-attestation.ts

@@ -0,0 +1,51 @@
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+
+export const LOCAL_ATTESTATION_CHALLENGE_HEADER = "x-opencodex-attestation-challenge";
+export const LOCAL_ATTESTATION_PROOF_HEADER = "x-opencodex-attestation-proof";
+
+const BASE64URL_256 = /^[A-Za-z0-9_-]{43}$/;
+
+export function isLocalAttestationSecret(value: unknown): value is string {
+  return typeof value === "string" && BASE64URL_256.test(value);
+}
+
+export function createLocalAttestationSecret(): string {
+  return randomBytes(32).toString("base64url");
+}
+
+export function createLocalAttestationChallenge(): string {
+  return randomBytes(32).toString("base64url");
+}
+
+function attestationPayload(challenge: string, pid: number, port: number): string | null {
+  if (!BASE64URL_256.test(challenge)) return null;
+  if (!Number.isSafeInteger(pid) || pid <= 0) return null;
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) return null;
+  return `opencodex-local-management-v1\n${challenge}\n${pid}\n${port}`;
+}
+
+export function createLocalAttestationProof(
+  secret: string,
+  challenge: string,
+  pid: number,
+  port: number,
+): string | null {
+  if (!isLocalAttestationSecret(secret)) return null;
+  const payload = attestationPayload(challenge, pid, port);
+  if (!payload) return null;
+  return createHmac("sha256", secret).update(payload).digest("base64url");
+}
+
+export function verifyLocalAttestationProof(
+  secret: string,
+  challenge: string,
+  pid: number,
+  port: number,
+  proof: string | null,
+): boolean {
+  const expected = createLocalAttestationProof(secret, challenge, pid, port);
+  if (!expected || !proof || !BASE64URL_256.test(proof)) return false;
+  const expectedBytes = Buffer.from(expected);
+  const actualBytes = Buffer.from(proof);
+  return expectedBytes.length === actualBytes.length && timingSafeEqual(expectedBytes, actualBytes);
+}

package/src/lib/open-url.ts

@@ -0,0 +1,25 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+function windowsRundll32(): string {
+  const windowsRoot = process.env.SystemRoot || process.env.WINDIR || "C:\\Windows";
+  const candidate = join(windowsRoot, "System32", "rundll32.exe");
+  return existsSync(candidate) ? candidate : "rundll32";
+}
+
+export function openUrl(url: string): void {
+  if (!/^https?:\/\//i.test(url)) return;
+  const cmd =
+    process.platform === "darwin" ? "open"
+    : process.platform === "win32" ? windowsRundll32()
+    : "xdg-open";
+  const args = process.platform === "win32"
+    ? ["url.dll,FileProtocolHandler", url]
+    : [url];
+  const child = spawn(cmd, args, { detached: true, stdio: "ignore", shell: false });
+  // Headless hosts (no xdg-open) emit ENOENT as an async 'error' event; without a
+  // listener that is an uncaught exception that kills the whole proxy/login flow.
+  child.on("error", () => {});
+  child.unref();
+}

package/src/lib/pinned-http.ts

@@ -0,0 +1,182 @@
+import http, { type IncomingMessage, type RequestOptions } from "node:http";
+import https from "node:https";
+
+export type PinnedAddress = { address: string; family: number };
+
+export interface PinnedHttpRequestOptions {
+  headers?: HeadersInit;
+  maxBytes?: number;
+  idleTimeoutMs?: number;
+  rejectUnauthorized?: boolean;
+  context?: string;
+}
+
+/** @deprecated Use {@link PinnedHttpRequestOptions}. */
+export type PinnedHttpGetOptions = PinnedHttpRequestOptions;
+
+function pinnedHttpRequest(
+  url: string,
+  pinned: PinnedAddress,
+  method: "GET" | "POST",
+  body: string | undefined,
+  signal?: AbortSignal,
+  options?: PinnedHttpRequestOptions,
+): Promise<Response> {
+  const parsed = new URL(url);
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error(`${options?.context ?? "request"} must use HTTP or HTTPS, got ${parsed.protocol}`);
+  }
+  const context = options?.context ?? "request";
+  const idleTimeoutMs = options?.idleTimeoutMs ?? 60_000;
+  const maxBytes = options?.maxBytes;
+  const headers = new Headers(options?.headers);
+  headers.set("host", parsed.host);
+  if (body !== undefined && !headers.has("content-length")) {
+    headers.set("content-length", String(Buffer.byteLength(body)));
+  }
+  const requestHeaders: Record<string, string> = {};
+  headers.forEach((value, key) => { requestHeaders[key] = value; });
+
+  return new Promise<Response>((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason instanceof Error ? signal.reason : new Error("aborted"));
+      return;
+    }
+
+    let settled = false;
+    const fail = (error: unknown) => {
+      try { req.destroy(); } catch { /* ignore */ }
+      if (settled) return;
+      settled = true;
+      reject(error instanceof Error ? error : new Error(String(error)));
+    };
+    const requestOptions: RequestOptions & { servername?: string } = {
+      protocol: parsed.protocol,
+      hostname: parsed.hostname,
+      port: parsed.port || (parsed.protocol === "https:" ? 443 : 80),
+      path: `${parsed.pathname}${parsed.search}`,
+      method,
+      headers: requestHeaders,
+      ...(parsed.protocol === "https:"
+        ? {
+          servername: parsed.hostname,
+          rejectUnauthorized: options?.rejectUnauthorized ?? true,
+        }
+        : {}),
+      lookup(_hostname, lookupOptions, callback) {
+        const opts = typeof lookupOptions === "function" ? undefined : lookupOptions;
+        const cb = typeof lookupOptions === "function" ? lookupOptions : callback;
+        if (!cb) return;
+        if (opts && typeof opts === "object" && "all" in opts && opts.all) {
+          (cb as (error: NodeJS.ErrnoException | null, addresses: PinnedAddress[]) => void)(
+            null,
+            [{ address: pinned.address, family: pinned.family }],
+          );
+          return;
+        }
+        (cb as (error: NodeJS.ErrnoException | null, address: string, family: 4 | 6) => void)(
+          null,
+          pinned.address,
+          pinned.family as 4 | 6,
+        );
+      },
+    };
+
+    const onResponse = (response: IncomingMessage) => {
+      const status = response.statusCode ?? 0;
+      const responseHeaders = new Headers();
+      for (const [key, value] of Object.entries(response.headers)) {
+        if (value === undefined || value === null) continue;
+        if (Array.isArray(value)) {
+          for (const item of value) responseHeaders.append(key, String(item));
+        } else {
+          responseHeaders.set(key, String(value));
+        }
+      }
+
+      if (status < 200 || status >= 300) {
+        try { response.destroy(); } catch { /* ignore */ }
+        try { req.destroy(); } catch { /* ignore */ }
+        if (settled) return;
+        settled = true;
+        resolve(new Response(null, { status, headers: responseHeaders }));
+        return;
+      }
+
+      let received = 0;
+      const stream = new ReadableStream<Uint8Array>({
+        start(controller) {
+          response.setTimeout(idleTimeoutMs, () => {
+            const error = new Error(`${context} stalled`);
+            fail(error);
+            try { controller.error(error); } catch { /* closed */ }
+          });
+          response.on("data", (chunk: Buffer | string) => {
+            const buffer = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+            received += buffer.byteLength;
+            if (maxBytes !== undefined && received > maxBytes) {
+              const error = new Error(`${context} exceeds ${maxBytes} byte cap`);
+              fail(error);
+              try { controller.error(error); } catch { /* closed */ }
+              return;
+            }
+            try { controller.enqueue(buffer); } catch { /* closed */ }
+          });
+          response.on("end", () => {
+            try { controller.close(); } catch { /* closed */ }
+          });
+          response.on("error", (error: Error) => {
+            fail(error);
+            try { controller.error(error); } catch { /* closed */ }
+          });
+        },
+        cancel() {
+          req.destroy();
+        },
+      });
+
+      if (settled) return;
+      settled = true;
+      resolve(new Response(stream, { status, headers: responseHeaders }));
+    };
+
+    const requestFn = parsed.protocol === "https:" ? https.request : http.request;
+    const req = requestFn(requestOptions, onResponse);
+    const onAbort = () => fail(signal?.reason instanceof Error ? signal.reason : new Error("aborted"));
+    signal?.addEventListener("abort", onAbort, { once: true });
+    req.setTimeout(idleTimeoutMs, () => fail(new Error(`${context} timed out`)));
+    req.on("error", error => {
+      signal?.removeEventListener("abort", onAbort);
+      fail(error);
+    });
+    req.on("close", () => signal?.removeEventListener("abort", onAbort));
+    req.end(body);
+  });
+}
+
+/**
+ * GET a URL through one previously validated address. The original hostname
+ * remains authoritative for Host, SNI, and certificate verification.
+ */
+export function pinnedHttpGet(
+  url: string,
+  pinned: PinnedAddress,
+  signal?: AbortSignal,
+  options?: PinnedHttpRequestOptions,
+): Promise<Response> {
+  return pinnedHttpRequest(url, pinned, "GET", undefined, signal, options);
+}
+
+/**
+ * POST a string body through one previously validated address. The original
+ * hostname remains authoritative for Host, SNI, and certificate verification.
+ */
+export function pinnedHttpPost(
+  url: string,
+  pinned: PinnedAddress,
+  body: string,
+  signal?: AbortSignal,
+  options?: PinnedHttpRequestOptions,
+): Promise<Response> {
+  return pinnedHttpRequest(url, pinned, "POST", body, signal, options);
+}

package/src/lib/privacy.ts

@@ -0,0 +1,20 @@
+export function maskEmail(value: string | null | undefined): string | null {
+  if (!value) return null;
+  const at = value.indexOf("@");
+  if (at <= 0) return value;
+  const local = value.slice(0, at);
+  const domain = value.slice(at + 1);
+  if (!domain) return value;
+  if (local.length === 1) return `*@${domain}`;
+  if (local.length === 2) return `${local[0]}*@${domain}`;
+  return `${local[0]}***${local[local.length - 1]}@${domain}`;
+}
+
+export function maskAccountId(value: string | null | undefined): string | null {
+  if (!value) return null;
+  const id = value.trim();
+  if (!id) return null;
+  // Short IDs would disclose the entire identifier via the suffix; use a non-identifying placeholder.
+  if (id.length <= 4) return "account-…";
+  return `account-…${id.slice(-4)}`;
+}

package/src/lib/process-control.ts

@@ -0,0 +1,168 @@
+import { execFileSync } from "node:child_process";
+import { loadConfig, readRuntimePort } from "../config";
+import { configuredAdminToken } from "./admin-secrets";
+
+export function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function waitForExit(pid: number, timeoutMs: number): boolean {
+  const deadline = Date.now() + timeoutMs;
+  const marker = new Int32Array(new SharedArrayBuffer(4));
+  while (Date.now() < deadline) {
+    if (!isProcessAlive(pid)) return true;
+    Atomics.wait(marker, 0, 0, 50);
+  }
+  return !isProcessAlive(pid);
+}
+
+/** Injectable seams so the graceful-stop flow is unit-testable without a live proxy. */
+export interface GracefulStopIo {
+  fetchFn?: typeof fetch;
+  readRuntime?: (pid: number) => { port: number; hostname?: string } | null;
+  waitExit?: (pid: number, timeoutMs: number) => boolean;
+  env?: Record<string, string | undefined>;
+  exitTimeoutMs?: number;
+}
+
+/**
+ * Host to POST /api/stop against: follow the recorded bind hostname when it names a
+ * concrete address (a proxy bound to ::1 or a LAN IP is unreachable on 127.0.0.1);
+ * loopback aliases and wildcard binds all answer on IPv4 loopback.
+ */
+export function gracefulStopHost(hostname: string | undefined): string {
+  const trimmed = (hostname ?? "").trim();
+  const lower = trimmed.toLowerCase();
+  if (!trimmed || lower === "localhost" || trimmed === "127.0.0.1" || trimmed === "0.0.0.0" || trimmed === "::" || trimmed === "[::]") {
+    return "127.0.0.1";
+  }
+  if (lower === "::1" || lower === "[::1]") return "[::1]";
+  if (trimmed.startsWith("[") && trimmed.endsWith("]")) return trimmed;
+  return trimmed.includes(":") ? `[${trimmed}]` : trimmed;
+}
+
+/**
+ * Outcome of a graceful stop attempt. `"refused"` is distinct from failure: the proxy answered
+ * that it must NOT be stopped from here, so callers must not escalate to a forced kill.
+ */
+export type GracefulStopResult = boolean | "refused";
+
+/** A proxy declined shutdown because a service under another home owns it (HTTP 409). */
+export class ProxyOwnershipRefusedError extends Error {}
+
+/**
+ * Ask a running proxy to stop itself via the management API (`POST /api/stop`), which
+ * drains in-flight turns, restores native Codex, and cleans its pid/runtime files.
+ * This is the only way to get a GRACEFUL stop on Windows, where the POSIX
+ * SIGTERM-then-SIGKILL ladder does not exist and `taskkill /F` gives the proxy no
+ * chance to run its shutdown handlers. Returns false when the proxy can't be reached
+ * or doesn't exit in time — callers fall back to {@link killProxy}. Returns `"refused"`
+ * when the proxy declines the stop (HTTP 409), which callers must NOT force past.
+ */
+export async function stopProxyGracefully(pid: number, io: GracefulStopIo = {}): Promise<GracefulStopResult> {
+  const readRuntime = io.readRuntime ?? readRuntimePort;
+  const runtime = readRuntime(pid);
+  if (!runtime?.port) return false;
+  const env = io.env ?? process.env;
+  const headers: Record<string, string> = {};
+  const token = configuredAdminToken(env.OPENCODEX_HOME?.trim() || undefined, env as NodeJS.ProcessEnv);
+  if (token) headers["x-opencodex-api-key"] = token;
+  const fetchFn = io.fetchFn ?? fetch;
+  try {
+    const res = await fetchFn(`http://${gracefulStopHost(runtime.hostname)}:${runtime.port}/api/stop`, {
+      method: "POST",
+      headers,
+      // Hung proxies with many CLOSE_WAIT clients can be slow to accept; give them
+      // longer than a health poll so we prefer drain over taskkill /F.
+      signal: AbortSignal.timeout(io.exitTimeoutMs ? Math.min(io.exitTimeoutMs, 10_000) : 10_000),
+    });
+    // 409 is the proxy REFUSING to stop (a service installed under another home owns it and
+    // would respawn it anyway). That is a policy answer, not a dead endpoint — escalating to
+    // SIGTERM here would run the daemon's cleanup and strip shared config out from under the
+    // still-running service. Report the refusal instead of forcing.
+    if (res.status === 409) return "refused";
+    if (!res.ok) return false;
+  } catch {
+    return false;
+  }
+  const waitExit = io.waitExit ?? waitForExit;
+  // Honor the server's own drain window: /api/stop answers 200 first, then drains for
+  // config.shutdownTimeoutMs. Waiting less than that hard-kills mid-drain.
+  const exitTimeoutMs = io.exitTimeoutMs ?? drainDeadlineMs();
+  return waitExit(pid, exitTimeoutMs);
+}
+
+function drainDeadlineMs(): number {
+  try {
+    return (loadConfig().shutdownTimeoutMs ?? 5000) + 3000;
+  } catch {
+    return 8000;
+  }
+}
+
+/** Graceful-first stop: management-API drain, then the platform kill ladder. */
+export async function stopProxy(pid: number): Promise<void> {
+  if (!isProcessAlive(pid)) return;
+  const runtime = readRuntimePort(pid);
+  const graceful = await stopProxyGracefully(pid);
+  if (graceful === "refused") {
+    // The proxy refused on purpose (foreign service owns it). Forcing would strip shared
+    // config while that service keeps the proxy alive.
+    throw new ProxyOwnershipRefusedError(
+      "The running proxy refused to stop: a service installed under a different "
+      + "CODEX_HOME/OPENCODEX_HOME owns it. Run the stop from that home.",
+    );
+  }
+  if (graceful) {
+    await waitForStoppedPort(runtime, pid);
+    return;
+  }
+  killProxy(pid);
+  await waitForStoppedPort(runtime, pid);
+}
+
+/** After stop/kill, wait for the former listen port to become bindable (Windows drain). */
+async function waitForStoppedPort(
+  runtime: { port: number; hostname?: string } | null | undefined,
+  stoppedPid?: number,
+): Promise<void> {
+  if (!runtime?.port) return;
+  try {
+    const { reclaimListenPort } = await import("../server/port-reclaim");
+    await reclaimListenPort(runtime.port, runtime.hostname ?? "127.0.0.1", {
+      timeoutMs: 15_000,
+      intervalMs: 100,
+      scanIntervalMs: 500,
+      // Only the process we just stopped — never kill a newly started twin proxy.
+      killOcxHolders: !!(stoppedPid && stoppedPid > 0),
+      onlyKillPids: stoppedPid && stoppedPid > 0 ? [stoppedPid] : [],
+    });
+  } catch {
+    /* best-effort — callers that need a hard guarantee reclaim again before bind */
+  }
+}
+
+export function killProxy(pid: number): void {
+  if (!isProcessAlive(pid)) return;
+  if (process.platform === "win32") {
+    // Windows process.kill(SIGTERM/SIGINT) is TerminateProcess — not a graceful signal.
+    // Graceful drain happens only via stopProxyGracefully() (POST /api/stop). This path
+    // is the hard fallback: taskkill /T /F so the process tree exits (ghost LISTEN /
+    // CLOSE_WAIT are then cleared by reclaimListenPort / SetTcpEntry).
+    const taskkill = `${process.env.SystemRoot ?? "C:\\Windows"}\\System32\\taskkill.exe`;
+    try {
+      execFileSync(taskkill, ["/PID", String(pid), "/T", "/F"], { stdio: "pipe", windowsHide: true });
+    } catch (err) {
+      if (isProcessAlive(pid)) throw err;
+    }
+  } else {
+    process.kill(pid, "SIGTERM");
+    if (!waitForExit(pid, 5000)) process.kill(pid, "SIGKILL");
+  }
+  if (!waitForExit(pid, 5000)) throw new Error(`process ${pid} did not exit`);
+}