blackriver-gateway 3.8.46

package/src/mitm/targets/openCode.ts

@@ -0,0 +1,34 @@
+/**
+ * OpenCode — MITM target descriptor.
+ *
+ * Hosts: `opencode.ai`.
+ * Format: OpenAI-compatible Chat Completions on `/v1/chat/completions`.
+ */
+import type { MitmTarget } from "../types";
+
+export const OPEN_CODE_TARGET: MitmTarget = {
+  id: "open-code",
+  name: "OpenCode",
+  icon: "code",
+  color: "#22D3EE",
+  hosts: ["opencode.ai"],
+  port: 443,
+  endpointPatterns: ["/v1/chat/completions"],
+  defaultModels: [
+    { id: "gpt-4o", name: "GPT-4o", alias: "gpt-4o" },
+    { id: "claude-3.5-sonnet", name: "Claude 3.5 Sonnet", alias: "claude-3.5-sonnet" },
+  ],
+  setupTutorial: {
+    steps: [
+      "Install the OpenCode CLI/IDE",
+      "Install OmniRoute's root certificate",
+      "Enable DNS routing for OpenCode",
+      "Restart OpenCode",
+      "Done — OpenCode traffic now routes through OmniRoute",
+    ],
+    detection: { command: "which opencode", platform: "all" },
+  },
+  handler: () =>
+    import("../handlers/openCode").then((m) => ({ default: m.OpenCodeHandler })),
+  riskNoticeKey: "providers.riskNotice.oauth",
+};

package/src/mitm/targets/trae.ts

@@ -0,0 +1,32 @@
+/**
+ * Trae — MITM target descriptor (stub).
+ *
+ * Viability is still under investigation (see plan 11 §5). The hostname
+ * `trae.invalid` is a deliberate non-routable placeholder so the target is
+ * registered (UI can list it as "investigating") without ever matching real
+ * traffic. The concrete host list will be filled in once we confirm the
+ * upstream API surface.
+ */
+import type { MitmTarget } from "../types";
+
+export const TRAE_TARGET: MitmTarget = {
+  id: "trae",
+  name: "Trae",
+  icon: "construction",
+  color: "#94A3B8",
+  hosts: ["trae.invalid"],
+  port: 443,
+  endpointPatterns: [],
+  defaultModels: [],
+  setupTutorial: {
+    steps: [
+      "Trae integration is under investigation",
+      "Setup steps will be published once the upstream API is confirmed",
+    ],
+    detection: { command: "which trae", platform: "all" },
+  },
+  handler: () =>
+    import("../handlers/trae").then((m) => ({ default: m.TraeHandler })),
+  riskNoticeKey: "providers.riskNotice.investigating",
+  viability: "investigating",
+};

package/src/mitm/targets/zed.ts

@@ -0,0 +1,32 @@
+/**
+ * Zed IDE — MITM target descriptor.
+ *
+ * Hosts: `api.zed.dev`.
+ * Format: OpenAI-compatible Chat Completions on `/v1/chat/completions`.
+ */
+import type { MitmTarget } from "../types";
+
+export const ZED_TARGET: MitmTarget = {
+  id: "zed",
+  name: "Zed",
+  icon: "bolt",
+  color: "#EF4444",
+  hosts: ["api.zed.dev"],
+  port: 443,
+  endpointPatterns: ["/v1/chat/completions"],
+  defaultModels: [
+    { id: "claude-3.5-sonnet", name: "Claude 3.5 Sonnet", alias: "claude-3.5-sonnet" },
+    { id: "gpt-4o", name: "GPT-4o", alias: "gpt-4o" },
+  ],
+  setupTutorial: {
+    steps: [
+      "Install OmniRoute's root certificate",
+      "Enable DNS routing for Zed",
+      "Restart Zed",
+      "Done — Zed traffic now routes through OmniRoute",
+    ],
+    detection: { command: "which zed", platform: "all" },
+  },
+  handler: () => import("../handlers/zed").then((m) => ({ default: m.ZedHandler })),
+  riskNoticeKey: "providers.riskNotice.oauth",
+};

package/src/mitm/tproxy/caTrust.ts

@@ -0,0 +1,120 @@
+/**
+ * Fase 3 / Epic A — OS trust-store install for the TPROXY dynamic CA (decrypt 4b/N).
+ *
+ * The decrypt capture mode issues per-SNI leaves from a dynamic CA (#4173); the
+ * intercepted clients must trust that CA. This installs the CA cert into the OS
+ * trust store under a DEDICATED slot (`omniroute-tproxy-ca.crt`), separate from
+ * the static MITM cert (`omniroute-mitm.crt` in `cert/install.ts`), so the two
+ * never clobber each other.
+ *
+ * Linux-only (TPROXY is Linux-only). Privileged commands run via the controlled
+ * `execFileWithPassword` helper — `spawn` with arg arrays, no shell, no string
+ * interpolation (Hard Rule #13). It already runs the target directly (no `sudo`)
+ * when the process is root, so on the VPS no password is needed. Every effectful
+ * seam is injectable so the command sequence is unit-testable without root.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileWithPassword } from "../systemCommands.ts";
+
+/** Dedicated trust-store filename — distinct from the static MITM cert's slot. */
+export const TPROXY_CA_CERT_NAME = "omniroute-tproxy-ca.crt";
+
+/** Trust-store anchor dirs + refresh command, in detection order (Debian first). */
+const LINUX_CERT_PATHS: ReadonlyArray<{ dir: string; cmd: string }> = [
+  { dir: "/usr/local/share/ca-certificates", cmd: "update-ca-certificates" },
+  { dir: "/etc/ca-certificates/trust-source/anchors", cmd: "update-ca-trust" },
+  { dir: "/etc/pki/ca-trust/source/anchors", cmd: "update-ca-trust" },
+  { dir: "/etc/pki/trust/anchors", cmd: "update-ca-certificates" },
+];
+
+export type SudoRunner = (command: string, args: string[], password: string) => Promise<unknown>;
+
+export interface CaTrustDeps {
+  /** Run a privileged command (sudo/arg-array; runs direct when root). */
+  run: SudoRunner;
+  /** Stage the CA PEM to a local file before the privileged copy. */
+  writeFile: (filePath: string, data: string) => void;
+  /** Remove the staged file (best-effort). */
+  rmFile: (filePath: string) => void;
+  /** Directory to stage the PEM in. */
+  tmpDir: () => string;
+  /** Resolve the trust-store anchor dir + refresh command for this distro. */
+  certConfig: () => { dir: string; cmd: string };
+  /** Host platform (Linux-only gate). */
+  platform: () => string;
+}
+
+function detectCertConfig(): { dir: string; cmd: string } {
+  for (const c of LINUX_CERT_PATHS) {
+    if (fs.existsSync(c.dir)) return c;
+  }
+  return LINUX_CERT_PATHS[0];
+}
+
+const realDeps: CaTrustDeps = {
+  run: execFileWithPassword,
+  writeFile: (filePath, data) => fs.writeFileSync(filePath, data, { mode: 0o644 }),
+  rmFile: (filePath) => {
+    try {
+      fs.unlinkSync(filePath);
+    } catch {
+      // best-effort cleanup
+    }
+  },
+  tmpDir: () => os.tmpdir(),
+  certConfig: detectCertConfig,
+  platform: () => process.platform,
+};
+
+/**
+ * Install the dynamic CA cert (PEM) into the OS trust store under the dedicated
+ * TPROXY slot. Stages the PEM to a temp file, then (privileged) copies it into the
+ * anchor dir and refreshes the trust store. Throws on non-Linux hosts.
+ */
+export async function installTproxyCa(
+  caPem: string,
+  sudoPassword = "",
+  deps: Partial<CaTrustDeps> = {}
+): Promise<void> {
+  if (process.env.OMNIROUTE_SKIP_SYSTEM_TRUST === "1" && deps.run === undefined) {
+    console.log("[tproxy-ca] OMNIROUTE_SKIP_SYSTEM_TRUST=1 — skipping OS trust-store mutation");
+    return;
+  }
+  const d = { ...realDeps, ...deps };
+  if (d.platform() !== "linux") {
+    throw new Error("TPROXY CA trust install is Linux-only.");
+  }
+  const cfg = d.certConfig();
+  const staged = path.join(d.tmpDir(), TPROXY_CA_CERT_NAME);
+  const dest = `${cfg.dir}/${TPROXY_CA_CERT_NAME}`;
+  d.writeFile(staged, caPem);
+  try {
+    await d.run("sudo", ["-S", "mkdir", "-p", cfg.dir], sudoPassword);
+    await d.run("sudo", ["-S", "cp", staged, dest], sudoPassword);
+    await d.run("sudo", ["-S", cfg.cmd], sudoPassword);
+  } finally {
+    d.rmFile(staged);
+  }
+}
+
+/**
+ * Remove the TPROXY CA from the OS trust store (its dedicated slot only — leaves
+ * the static MITM cert untouched) and refresh. No-op on non-Linux hosts.
+ */
+export async function uninstallTproxyCa(
+  sudoPassword = "",
+  deps: Partial<CaTrustDeps> = {}
+): Promise<void> {
+  if (process.env.OMNIROUTE_SKIP_SYSTEM_TRUST === "1" && deps.run === undefined) {
+    console.log("[tproxy-ca] OMNIROUTE_SKIP_SYSTEM_TRUST=1 — skipping OS trust-store mutation");
+    return;
+  }
+  const d = { ...realDeps, ...deps };
+  if (d.platform() !== "linux") return;
+  const cfg = d.certConfig();
+  const dest = `${cfg.dir}/${TPROXY_CA_CERT_NAME}`;
+  await d.run("sudo", ["-S", "rm", "-f", dest], sudoPassword);
+  await d.run("sudo", ["-S", cfg.cmd], sudoPassword);
+}

package/src/mitm/tproxy/captureManager.ts

@@ -0,0 +1,118 @@
+/**
+ * Fase 3 / Epic A — TPROXY capture-mode manager (decrypt 4a/N).
+ *
+ * Singleton lifecycle around the decrypt-capable transparent listener
+ * (`captureMode.ts`): builds the dynamic CA (#4173), gates on native-addon
+ * availability, holds the single running handle, counts interceptions, and
+ * exposes start / stop / status for a (local-only) route to drive.
+ *
+ * The OS trust-store mechanism is deliberately NOT baked in here: `installCa` /
+ * `uninstallCa` are injected by the caller (the route / VPS e2e provides the real
+ * installer, which needs its own trust-store slot so it does not clobber the
+ * static MITM cert). This keeps the manager unit-testable without root and means
+ * it never mutates the trust store on its own.
+ */
+import { DynamicCertStore } from "./dynamicCert";
+import { startTproxyCapture, type TproxyCaptureHandle } from "./captureMode";
+import { isTransparentSocketAvailable } from "./transparentSocket";
+import type { TproxyConfig } from "./commands";
+
+export interface CaptureManagerStatus {
+  /** Whether a capture session is currently running. */
+  running: boolean;
+  /** Whether the native IP_TRANSPARENT addon is loadable on this host. */
+  available: boolean;
+  /** ISO timestamp of when the running session started. */
+  startedAt?: string;
+  /** Number of connections intercepted in the running session. */
+  interceptCount?: number;
+  /** The transparent listener port of the running session. */
+  onPort?: number;
+}
+
+export interface CaptureManagerDeps {
+  startTproxyCapture: typeof startTproxyCapture;
+  isAvailable: () => boolean;
+  createCertStore: () => DynamicCertStore;
+  now: () => string;
+}
+
+const realDeps: CaptureManagerDeps = {
+  startTproxyCapture,
+  isAvailable: isTransparentSocketAvailable,
+  createCertStore: () => new DynamicCertStore(),
+  now: () => new Date().toISOString(),
+};
+
+export interface StartCaptureModeOptions {
+  cfg: TproxyConfig;
+  /** Install the dynamic CA cert (PEM) into the OS trust store. Injected so the
+   * manager never touches the trust store itself. */
+  installCa: (caPem: string) => Promise<void>;
+  /** Remove the CA from the trust store on stop (symmetric teardown). Injected. */
+  uninstallCa: () => Promise<void>;
+  /** Seam overrides for unit testing. */
+  deps?: Partial<CaptureManagerDeps>;
+}
+
+interface ActiveCapture {
+  handle: TproxyCaptureHandle;
+  startedAt: string;
+  intercepts: { count: number };
+}
+
+let active: ActiveCapture | null = null;
+
+/**
+ * Start the decrypt-capable TPROXY capture mode. Rejects if a session is already
+ * running or the native addon is unavailable. The dynamic CA is created here and
+ * installed in the trust store via the injected `installCa`.
+ */
+export async function startCaptureMode(
+  options: StartCaptureModeOptions
+): Promise<CaptureManagerStatus> {
+  if (active) throw new Error("TPROXY capture mode is already running");
+
+  const deps: CaptureManagerDeps = { ...realDeps, ...options.deps };
+  if (!deps.isAvailable()) {
+    throw new Error("TPROXY capture mode requires the native addon (Linux + CAP_NET_ADMIN).");
+  }
+
+  const certStore = deps.createCertStore();
+  const intercepts = { count: 0 };
+  const handle = await deps.startTproxyCapture(options.cfg, {
+    decrypt: { certStore, installCa: options.installCa, uninstallCa: options.uninstallCa },
+    onIntercept: () => {
+      intercepts.count += 1;
+    },
+  });
+  active = { handle, startedAt: deps.now(), intercepts };
+  return getCaptureStatus();
+}
+
+/** Stop the running capture session (closes the listener, uninstalls the CA, and
+ * reverts the rules via the handle). Idempotent — a no-op when nothing runs. */
+export async function stopCaptureMode(): Promise<CaptureManagerStatus> {
+  const current = active;
+  active = null;
+  if (current) await current.handle.stop();
+  return getCaptureStatus();
+}
+
+/** Current capture-mode status (safe to call any time, including when idle). */
+export function getCaptureStatus(): CaptureManagerStatus {
+  const available = isTransparentSocketAvailable();
+  if (!active) return { running: false, available };
+  return {
+    running: true,
+    available,
+    startedAt: active.startedAt,
+    interceptCount: active.intercepts.count,
+    onPort: active.handle.cfg.onPort,
+  };
+}
+
+/** Test-only: clear the singleton without invoking teardown. */
+export function __resetCaptureManager(): void {
+  active = null;
+}

package/src/mitm/tproxy/captureMode.ts

@@ -0,0 +1,226 @@
+/**
+ * Fase 3 / Epic A — TPROXY capture-mode listener (Linux).
+ *
+ * Ties the validated primitives together into a transparent capture mode for
+ * LOCAL outbound traffic (IDE agents on the same host) WITHOUT `/etc/hosts`
+ * spoofing or OS-wide proxy mutation:
+ *
+ *   1. apply the OUTPUT-based TPROXY rules (commands.ts / setup.ts)
+ *   2. open the IP_TRANSPARENT listener (native addon → fd → net.Server)
+ *   3. per intercepted connection: read the ORIGINAL destination
+ *      (`socket.localAddress` — TPROXY preserves it), report it, and forward to
+ *      that destination over a `connectMarked` (SO_MARK bypass) socket so the
+ *      OUTPUT rule excludes the forward (anti-loop), with a raw bidirectional pipe.
+ *
+ * Each primitive was validated e2e on the VPS (kernel 6.8.0): intercept,
+ * anti-loop (the marked SYN was excluded), and Node adoption of the marked fd +
+ * pipe (PONG round-tripped).
+ *
+ * Two forwarding modes, chosen per `options.decrypt`:
+ *   - raw tunnel (default): forward to the original destination over the
+ *     bypass-marked socket with a raw bidirectional pipe — bodies stay opaque;
+ *   - decrypt (opt-in): hand the raw socket to the TLS-terminating engine
+ *     (`tlsCapture.ts`, #4179), which decrypts with a per-SNI leaf from the
+ *     dynamic CA (#4173), captures the exchange (source "tproxy"), and forwards
+ *     re-encrypted over the SAME bypass-marked seam. The CA is installed in the
+ *     OS trust store on start (so clients trust the issued leaves) and removed on
+ *     stop, both via injected seams.
+ *
+ * All effectful seams are injected (`deps`) so the orchestration and the
+ * per-connection logic are unit-testable without root.
+ */
+import net from "node:net";
+import { applyTproxy, revertTproxy, type CommandRunner } from "./setup";
+import {
+  createTransparentListenerFd,
+  connectMarked,
+  isTransparentSocketAvailable,
+} from "./transparentSocket";
+import { validateTproxyConfig, type TproxyConfig } from "./commands";
+import { createForward, createTlsCaptureServer, type TlsCaptureServer } from "./tlsCapture";
+import type { DynamicCertStore } from "./dynamicCert";
+
+/** Default bypass SO_MARK when `cfg.bypassMark` is unset (anti-loop). */
+const DEFAULT_BYPASS_MARK = 0x539;
+
+/** Strip the IPv4-mapped-IPv6 prefix Node reports for dual-stack sockets. */
+export function normalizeDest(localAddress: string | undefined): string {
+  return (localAddress ?? "").replace(/^::ffff:/, "");
+}
+
+export interface TproxyInterceptInfo {
+  destIp: string;
+  destPort: number;
+}
+
+interface TproxyDeps {
+  applyTproxy: (cfg: TproxyConfig, run?: CommandRunner) => Promise<void>;
+  revertTproxy: (cfg: TproxyConfig, run?: CommandRunner) => Promise<void>;
+  createListenerFd: (ip: string, port: number) => number;
+  connectMarked: (ip: string, port: number, mark: number) => number;
+  createServer: (onConn: (s: net.Socket) => void) => net.Server;
+  createUpstreamSocket: (fd: number) => net.Socket;
+}
+
+const realDeps: TproxyDeps = {
+  applyTproxy,
+  revertTproxy,
+  createListenerFd: createTransparentListenerFd,
+  connectMarked,
+  createServer: (onConn) => net.createServer(onConn),
+  createUpstreamSocket: (fd) => new net.Socket({ fd }),
+};
+
+/**
+ * Enables TLS decryption + content capture for intercepted connections (instead
+ * of the raw tunnel). The CA private key never leaves the host; `installCa` is
+ * the only piece that touches the OS trust store and is injected by the caller.
+ */
+export interface TproxyDecryptOptions {
+  /** Dynamic CA that issues per-SNI leaves and exposes its CA cert (#4173). */
+  certStore: Pick<DynamicCertStore, "createSNICallback" | "getCaCertPem">;
+  /** Install the CA cert (PEM) into the OS trust store so clients trust the
+   * issued leaves. Called once on start; omit to manage the trust store yourself. */
+  installCa?: (caPem: string) => Promise<void>;
+  /** Remove the CA from the trust store on stop (symmetric teardown). */
+  uninstallCa?: () => Promise<void>;
+}
+
+export interface TproxyCaptureOptions {
+  /** Bind address for the transparent listener. Default "0.0.0.0". */
+  listenIp?: string;
+  /** Invoked for each intercepted connection (e.g. push metadata to the buffer). */
+  onIntercept?: (info: TproxyInterceptInfo) => void;
+  /** Opt into TLS decryption + content capture (source "tproxy"). */
+  decrypt?: TproxyDecryptOptions;
+  /** Injectable seams for unit testing. */
+  deps?: Partial<TproxyDeps>;
+}
+
+export interface TproxyCaptureHandle {
+  cfg: TproxyConfig;
+  server: net.Server;
+  stop: () => Promise<void>;
+}
+
+/**
+ * Handle one intercepted connection: read the original destination, report it,
+ * and forward it. When `terminate` is provided (decrypt mode), the raw socket is
+ * handed to the TLS-terminating engine; otherwise it is raw-piped to the
+ * destination over a bypass-marked socket.
+ */
+export function handleTproxyConnection(
+  client: net.Socket,
+  cfg: TproxyConfig,
+  deps: Pick<TproxyDeps, "connectMarked" | "createUpstreamSocket">,
+  onIntercept?: (info: TproxyInterceptInfo) => void,
+  terminate?: (client: net.Socket, dest: { ip: string; port: number }) => void
+): void {
+  const destIp = normalizeDest(client.localAddress);
+  const destPort = client.localPort ?? 0;
+  onIntercept?.({ destIp, destPort });
+
+  if (!destIp || destPort <= 0) {
+    client.destroy();
+    return;
+  }
+
+  // Decrypt mode: the engine TLS-terminates, captures (source "tproxy"), and
+  // forwards re-encrypted over its own bypass-marked socket (anti-loop).
+  if (terminate) {
+    terminate(client, { ip: destIp, port: destPort });
+    return;
+  }
+
+  let fd: number;
+  try {
+    fd = deps.connectMarked(destIp, destPort, cfg.bypassMark ?? DEFAULT_BYPASS_MARK);
+  } catch {
+    client.destroy();
+    return;
+  }
+
+  const upstream = deps.createUpstreamSocket(fd);
+  upstream.on("error", () => client.destroy());
+  client.on("error", () => upstream.destroy());
+  client.pipe(upstream);
+  upstream.pipe(client);
+}
+
+/**
+ * Start TPROXY capture: apply the rules, open the transparent listener, and wire
+ * the per-connection forwarder. Returns a handle whose `stop()` closes the
+ * listener and reverts the rules (crash-safe teardown). Throws (after reverting)
+ * if anything fails to come up.
+ */
+export async function startTproxyCapture(
+  cfg: TproxyConfig,
+  options: TproxyCaptureOptions = {}
+): Promise<TproxyCaptureHandle> {
+  const deps: TproxyDeps = { ...realDeps, ...options.deps };
+
+  // In production the native addon is required; tests inject createListenerFd.
+  if (!options.deps?.createListenerFd && !isTransparentSocketAvailable()) {
+    throw new Error("TPROXY capture mode requires the native addon (Linux + CAP_NET_ADMIN).");
+  }
+  const invalid = validateTproxyConfig(cfg);
+  if (invalid) throw new Error(invalid);
+
+  await deps.applyTproxy(cfg);
+
+  // Decrypt mode: stand up the TLS-terminating engine (forwarding over the SAME
+  // bypass-marked seam, anti-loop) and install its CA so clients trust the leaves.
+  // `cleanup` is the symmetric teardown for both the error paths and stop().
+  let engine: TlsCaptureServer | undefined;
+  let uninstallCa: (() => Promise<void>) | undefined;
+  const cleanup = async (): Promise<void> => {
+    await engine?.close().catch(() => {});
+    await uninstallCa?.().catch(() => {});
+    await deps.revertTproxy(cfg).catch(() => {});
+  };
+
+  try {
+    if (options.decrypt) {
+      const mark = cfg.bypassMark ?? DEFAULT_BYPASS_MARK;
+      const forward = createForward((ip, port) =>
+        deps.createUpstreamSocket(deps.connectMarked(ip, port, mark))
+      );
+      engine = createTlsCaptureServer(options.decrypt.certStore, { forward });
+      if (options.decrypt.installCa) {
+        await options.decrypt.installCa(await options.decrypt.certStore.getCaCertPem());
+      }
+      uninstallCa = options.decrypt.uninstallCa;
+    }
+
+    const terminate = engine
+      ? (client: net.Socket, dest: { ip: string; port: number }) => engine!.terminate(client, dest)
+      : undefined;
+
+    const fd = deps.createListenerFd(options.listenIp ?? "0.0.0.0", cfg.onPort);
+
+    const server = deps.createServer((client) =>
+      handleTproxyConnection(client, cfg, deps, options.onIntercept, terminate)
+    );
+
+    await new Promise<void>((resolve, reject) => {
+      const onErr = (e: Error) => reject(e);
+      server.once("error", onErr);
+      server.listen({ fd }, () => {
+        server.removeListener("error", onErr);
+        resolve();
+      });
+    });
+
+    return {
+      cfg,
+      server,
+      stop: async () => {
+        await new Promise<void>((resolve) => server.close(() => resolve()));
+        await cleanup();
+      },
+    };
+  } catch (err) {
+    await cleanup();
+    throw err;
+  }
+}

package/src/mitm/tproxy/commands.ts

@@ -0,0 +1,122 @@
+/**
+ * Fase 3 / Epic A — TPROXY transparent capture mode (Linux): command builder.
+ *
+ * A 5th capture mode that intercepts TCP transparently via Linux TPROXY + policy
+ * routing, WITHOUT spoofing `/etc/hosts` or mutating OS-wide system-proxy
+ * settings (headless-friendly, auto-flushed on reboot).
+ *
+ * ⚠️ OUTPUT-based recipe (validated e2e on the VPS, kernel 6.8.0): the MITM use
+ * case is LOCAL outbound traffic (IDE agents on the same host), which TPROXY in
+ * PREROUTING does NOT see — PREROUTING only sees *forwarded* traffic. So we mark
+ * new local outbound connections in the `mangle OUTPUT` chain, an `ip rule`
+ * reroutes the marked packets to local delivery (`lo`), and on re-entry the
+ * `mangle PREROUTING` TPROXY target assigns them to the IP_TRANSPARENT listener.
+ * (An earlier PREROUTING-only recipe was proven not to intercept local traffic.)
+ *
+ * Validated recipe (test port 9999, fwmark 0x2333 — isolated from prod 443/80):
+ *   iptables -t mangle -A OUTPUT -p tcp --dport N [-m mark ! --mark BYPASS] -j MARK --set-mark M
+ *   ip rule add fwmark M lookup T
+ *   ip route add local 0.0.0.0/0 dev lo table T
+ *   iptables -t mangle -A PREROUTING -p tcp --dport N -m mark --mark M -j TPROXY --on-port L --tproxy-mark M
+ * Result: client CONNECTED, listener saw orig-dest preserved (198.51.100.7:9999).
+ *
+ * Pure + unit-testable: the exact `iptables`/`ip` commands for apply and revert,
+ * with the invariant that **revert is the precise inverse of apply, in reverse
+ * order** — a crash must never leave a mangle rule behind (the Fase 1 /
+ * `repairMitm()` invariant). `setup.ts` runs these via `execFile` (arrays, never
+ * a shell string — Hard Rule #13).
+ *
+ * `bypassMark` (anti-loop): the SO_MARK the proxy sets on its OWN upstream
+ * connections; the OUTPUT rule excludes it so the proxy's forwarded traffic is
+ * not re-intercepted (infinite loop). When omitted, no exclusion is emitted
+ * (fine for a metadata-only listener that never forwards).
+ */
+
+export interface TproxyConfig {
+  /** Destination TCP port to transparently intercept (e.g. 443). */
+  dport: number;
+  /** Firewall mark set on OUTPUT and matched by the ip rule + PREROUTING (e.g. 0x2333). */
+  mark: number;
+  /** Local port the IP_TRANSPARENT listener binds (e.g. 8443). */
+  onPort: number;
+  /** Policy-routing table id holding the `local 0.0.0.0/0` route (e.g. 233). */
+  routeTable: number;
+  /** SO_MARK the proxy sets on its own upstream conns; excluded in OUTPUT (anti-loop). */
+  bypassMark?: number;
+}
+
+/** A single command to run via `execFile(bin, args)` — never a shell string. */
+export interface TproxyCommand {
+  bin: string;
+  args: string[];
+}
+
+function isPort(n: number): boolean {
+  return Number.isInteger(n) && n >= 1 && n <= 65535;
+}
+
+/**
+ * Validate a config before any command is built/run. Returns an error message
+ * string, or null when the config is sane.
+ */
+export function validateTproxyConfig(cfg: TproxyConfig): string | null {
+  if (!isPort(cfg.dport)) return `dport must be a valid TCP port (1-65535), got ${cfg.dport}`;
+  if (!isPort(cfg.onPort)) return `onPort must be a valid TCP port (1-65535), got ${cfg.onPort}`;
+  if (!Number.isInteger(cfg.mark) || cfg.mark < 1) return `mark must be a positive integer, got ${cfg.mark}`;
+  if (!Number.isInteger(cfg.routeTable) || cfg.routeTable < 1) {
+    return `routeTable must be a positive integer, got ${cfg.routeTable}`;
+  }
+  if (cfg.bypassMark !== undefined) {
+    if (!Number.isInteger(cfg.bypassMark) || cfg.bypassMark < 1) {
+      return `bypassMark must be a positive integer when set, got ${cfg.bypassMark}`;
+    }
+    if (cfg.bypassMark === cfg.mark) return "bypassMark must differ from mark (anti-loop)";
+  }
+  return null;
+}
+
+/** OUTPUT mangle rule spec (mark new local outbound conns), shared so -A/-D match. */
+function outputRuleSpec(cfg: TproxyConfig): string[] {
+  const spec = ["-t", "mangle", "OUTPUT", "-p", "tcp", "--dport", String(cfg.dport)];
+  if (cfg.bypassMark !== undefined) {
+    spec.push("-m", "mark", "!", "--mark", String(cfg.bypassMark));
+  }
+  spec.push("-j", "MARK", "--set-mark", String(cfg.mark));
+  return spec;
+}
+
+/** PREROUTING mangle TPROXY rule spec (assign marked, rerouted packets to the listener). */
+function preroutingRuleSpec(cfg: TproxyConfig): string[] {
+  return [
+    "-t", "mangle", "PREROUTING",
+    "-p", "tcp", "--dport", String(cfg.dport),
+    "-m", "mark", "--mark", String(cfg.mark),
+    "-j", "TPROXY", "--on-port", String(cfg.onPort), "--tproxy-mark", String(cfg.mark),
+  ];
+}
+
+/** Build an iptables command from a `[-t table, CHAIN, ...rest]` spec + the op flag. */
+function iptables(op: "-A" | "-D", spec: string[]): TproxyCommand {
+  const [t, table, chain, ...rest] = spec;
+  return { bin: "iptables", args: [t, table, op, chain, ...rest] };
+}
+
+/** Commands to enable TPROXY interception of local outbound traffic, in apply order. */
+export function buildTproxyApplyCommands(cfg: TproxyConfig): TproxyCommand[] {
+  return [
+    { bin: "ip", args: ["rule", "add", "fwmark", String(cfg.mark), "lookup", String(cfg.routeTable)] },
+    { bin: "ip", args: ["route", "add", "local", "0.0.0.0/0", "dev", "lo", "table", String(cfg.routeTable)] },
+    iptables("-A", outputRuleSpec(cfg)),
+    iptables("-A", preroutingRuleSpec(cfg)),
+  ];
+}
+
+/** Commands to undo TPROXY interception — exact inverse of apply, reverse order. */
+export function buildTproxyRevertCommands(cfg: TproxyConfig): TproxyCommand[] {
+  return [
+    iptables("-D", preroutingRuleSpec(cfg)),
+    iptables("-D", outputRuleSpec(cfg)),
+    { bin: "ip", args: ["route", "del", "local", "0.0.0.0/0", "dev", "lo", "table", String(cfg.routeTable)] },
+    { bin: "ip", args: ["rule", "del", "fwmark", String(cfg.mark), "lookup", String(cfg.routeTable)] },
+  ];
+}