@xaccefy/pi-casefile 0.9.4 → 0.10.1

package/src/oob-oracle.ts

@@ -0,0 +1,279 @@
+/**
+ * Operator-owned OOB oracle client — Tier 1 of docs/poc-trust-model.md.
+ *
+ * Blind/OOB classes (SSRF, blind XSS, XXE, DNS exfil) cannot be confirmed by
+ * response differentials: the effect lands on a callback channel. The trust
+ * model requires the judge to own the evidence channel and the secret:
+ *
+ * - The HARNESS generates a per-run random token and provisions a callback
+ *   domain embedding it via the operator-run oracle service. The value does
+ *   not exist when the PoC script is written, so it cannot be pre-printed.
+ * - The PoC causes the TARGET to interact with that domain; the oracle's own
+ *   interaction log — read back by the harness, never by the PoC — is the
+ *   evidence.
+ * - Differential shape: the target run gets one token, the control run a
+ *   DIFFERENT token. Proof requires target-token interactions AND zero
+ *   control-token interactions.
+ *
+ * Source separation (the PoC must not be able to fake the interaction):
+ * - Hard guarantee (three-box model): only when the operator attests the
+ *   network topology separates PoC egress from oracle reachability via
+ *   PI_OOB_SOURCE_SEPARATED=1. Without it, verification stays diagnostic
+ *   and the ledger gate refuses promotion.
+ * - Self-interaction filtering: interactions originating from PI_OOB_SELF_IPS
+ *   (the sandbox/host egress addresses) are rejected as self-caused and never
+ *   counted as target hits.
+ *
+ * Everything fails closed: no oracle configured -> OOB promotion impossible.
+ */
+
+import { randomBytes } from "node:crypto";
+
+export type OobInteraction = {
+  protocol?: string;
+  src_ip?: string;
+  ts?: string;
+  raw?: string;
+};
+
+export type OobOracleConfig = {
+  baseUrl: string;
+  bearer?: string;
+  sourceSeparated: boolean;
+  selfIps: string[];
+};
+
+/** Read the operator's oracle configuration; error text explains what's missing. */
+export function readOobOracleConfig(env: NodeJS.ProcessEnv = process.env): {
+  config?: OobOracleConfig;
+  error?: string;
+} {
+  const raw = (env.PI_OOB_ORACLE_URL ?? "").trim();
+  if (!raw) {
+    return {
+      error:
+        "no OOB oracle configured. Set PI_OOB_ORACLE_URL to an operator-run oracle service " +
+        "(POST /provision {token} -> {domain}; GET /interactions?token= -> {interactions}). " +
+        "Declare PI_OOB_SOURCE_SEPARATED=1 only when the network topology truly prevents the " +
+        "PoC sandbox from reaching the oracle directly.",
+    };
+  }
+  let baseUrl: URL;
+  try {
+    baseUrl = new URL(raw);
+  } catch {
+    return { error: `PI_OOB_ORACLE_URL is not a valid URL: ${raw}` };
+  }
+  if (baseUrl.protocol !== "http:" && baseUrl.protocol !== "https:") {
+    return { error: `PI_OOB_ORACLE_URL must be http(s), got ${baseUrl.protocol}` };
+  }
+  const selfIps = (env.PI_OOB_SELF_IPS ?? "")
+    .split(",")
+    .map((v) => v.trim())
+    .filter(Boolean);
+  return {
+    config: {
+      baseUrl: raw.replace(/\/+$/, ""),
+      bearer: env.PI_OOB_ORACLE_TOKEN?.trim() || undefined,
+      sourceSeparated: env.PI_OOB_SOURCE_SEPARATED === "1",
+      selfIps,
+    },
+  };
+}
+
+type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+
+let oracleFetchForTest: FetchLike | undefined;
+
+/** Test seam; production uses global fetch. */
+export function setOobOracleFetchForTest(impl: FetchLike | undefined): void {
+  oracleFetchForTest = impl;
+}
+
+function makeToken(): string {
+  return randomBytes(16).toString("hex");
+}
+
+async function oracleFetch(
+  config: OobOracleConfig,
+  path: string,
+  init?: RequestInit,
+): Promise<Response> {
+  const headers: Record<string, string> = {
+    accept: "application/json",
+    ...((init?.headers as Record<string, string>) ?? {}),
+  };
+  if (config.bearer) headers.authorization = `Bearer ${config.bearer}`;
+  const fetchImpl = oracleFetchForTest ?? fetch;
+  // Bounded: an unresponsive oracle must fail the run, not hang the tool.
+  return fetchImpl(`${config.baseUrl}${path}`, {
+    ...init,
+    headers,
+    signal: AbortSignal.timeout(30_000),
+  });
+}
+
+export type ProvisionedCallback = {
+  /** Harness-generated secret embedded in the provisioned domain. */
+  token: string;
+  /** Domain the payload must make the target interact with. */
+  domain: string;
+};
+
+/**
+ * Provision one callback identity. The token is generated HERE (harness owns
+ * the secret); the oracle returns a domain that embeds it.
+ */
+export async function provisionCallback(config: OobOracleConfig): Promise<ProvisionedCallback> {
+  const token = makeToken();
+  let res: Response;
+  try {
+    res = await oracleFetch(config, "/provision", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ token }),
+    });
+  } catch (e) {
+    throw new Error(`OOB oracle unreachable (${config.baseUrl}): ${(e as Error).message}`);
+  }
+  if (!res.ok) {
+    throw new Error(`OOB oracle /provision failed: HTTP ${res.status}`);
+  }
+  let body: { domain?: unknown };
+  try {
+    body = (await res.json()) as { domain?: unknown };
+  } catch {
+    throw new Error("OOB oracle /provision returned a non-JSON body");
+  }
+  if (typeof body.domain !== "string" || !body.domain.includes(token)) {
+    throw new Error(
+      "OOB oracle /provision returned a domain that does not embed the harness token — refusing an oracle that invents its own secrets",
+    );
+  }
+  return { token, domain: body.domain };
+}
+
+export type OobPollResult = {
+  interactions: OobInteraction[];
+  /** Interactions NOT counted (self-IP matches) — recorded honestly. */
+  selfInteractions: OobInteraction[];
+};
+
+/** Fetch (not wait-and-retry — callers own the polling loop) current interactions for a token. */
+export async function fetchInteractions(
+  config: OobOracleConfig,
+  token: string,
+): Promise<OobPollResult> {
+  let res: Response;
+  try {
+    res = await oracleFetch(config, `/interactions?token=${encodeURIComponent(token)}`);
+  } catch (e) {
+    throw new Error(`OOB oracle unreachable (${config.baseUrl}): ${(e as Error).message}`);
+  }
+  if (!res.ok) {
+    throw new Error(`OOB oracle /interactions failed: HTTP ${res.status}`);
+  }
+  let body: { interactions?: unknown };
+  try {
+    body = (await res.json()) as { interactions?: unknown };
+  } catch {
+    throw new Error("OOB oracle /interactions returned a non-JSON body");
+  }
+  if (!Array.isArray(body.interactions)) {
+    throw new Error("OOB oracle /interactions response missing interactions array");
+  }
+  const all = body.interactions.filter(
+    (i): i is OobInteraction => typeof i === "object" && i !== null,
+  );
+  const self = config.selfIps;
+  // Fail closed on provenance: an interaction WITHOUT a source IP cannot be
+  // attributed to the target (a PoC could fabricate one on any channel it
+  // reaches), so it is never counted as a hit — surfaced separately instead.
+  const interactions = all.filter(
+    (i) => typeof i.src_ip === "string" && i.src_ip.length > 0 && !self.includes(i.src_ip),
+  );
+  const selfInteractions = all.filter(
+    (i) => !i.src_ip || (typeof i.src_ip === "string" && self.includes(i.src_ip)),
+  );
+  return { interactions, selfInteractions };
+}
+
+/**
+ * Poll for interactions on both run tokens. Once ANY token observes an
+ * interaction, polling continues for a full settle window so a DELAYED
+ * control-token hit (the false-positive shape: target fires at t=1s, a
+ * cheating/self-caused control hit lands at t=3s after an early exit)
+ * cannot be missed. Evaluation happens after settle or at deadline.
+ */
+export async function verifyOobDifferential(
+  opts: {
+    targetToken: string;
+    controlToken: string;
+    pollMs?: number;
+    intervalMs?: number;
+    /** Keep polling this long after the first observed interaction. */
+    settleMs?: number;
+  },
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<{ verification: import("./ledger.ts").OobVerification }> {
+  const { config, error } = readOobOracleConfig(env);
+  if (!config) throw new Error(error ?? "OOB oracle not configured");
+  // Env overrides are operator tuning: clamp to sane minimums so a typo like
+  // PI_OOB_POLL_MS=-5 cannot produce an inverted deadline or a zero window.
+  const pollMs = opts.pollMs ?? Math.max(Number(env.PI_OOB_POLL_MS) || 30_000, 1_000);
+  const intervalMs = opts.intervalMs ?? Math.max(Number(env.PI_OOB_INTERVAL_MS) || 2_000, 100);
+  const settleMs =
+    opts.settleMs ?? Math.max(Number(env.PI_OOB_SETTLE_MS) || Math.max(intervalMs, 5_000), 250);
+  const deadline = Date.now() + pollMs;
+
+  let target: OobPollResult = { interactions: [], selfInteractions: [] };
+  let control: OobPollResult = { interactions: [], selfInteractions: [] };
+  let firstHitAt: number | undefined;
+  for (;;) {
+    target = await fetchInteractions(config, opts.targetToken);
+    control = await fetchInteractions(config, opts.controlToken);
+    if (target.interactions.length > 0 || control.interactions.length > 0) {
+      firstHitAt ??= Date.now();
+      // Settled: kept watching past the first hit long enough to catch
+      // trailing control hits.
+      if (Date.now() - firstHitAt >= settleMs) break;
+    }
+    const now = Date.now();
+    if (now >= deadline) break;
+    await new Promise((r) => setTimeout(r, Math.min(intervalMs, deadline - now)));
+  }
+
+  const notes: string[] = [];
+  if (target.selfInteractions.length + control.selfInteractions.length > 0) {
+    notes.push(
+      `${target.selfInteractions.length} target-run / ${control.selfInteractions.length} ` +
+        "control-run unattributed-or-self-source interaction(s) rejected (missing src_ip or PI_OOB_SELF_IPS)",
+    );
+  }
+  notes.push(
+    config.sourceSeparated
+      ? "operator attests source separation (PI_OOB_SOURCE_SEPARATED=1)"
+      : "source separation NOT attested — diagnostic only",
+  );
+  // Tokens are stored raw in the ledger (see PendingConfirmation.oobTokens);
+  // an oracle reachable without a bearer token makes those tokens pollable by
+  // anyone with ledger read access. Surface it where the operator's attention
+  // already is — the verification note.
+  if (!config.bearer) {
+    notes.push(
+      "oracle has no PI_OOB_ORACLE_TOKEN — stored run tokens are pollable by anyone with oracle network access; set a bearer token or restrict the oracle endpoint",
+    );
+  }
+
+  return {
+    verification: {
+      attempted: true,
+      targetHits: target.interactions.length,
+      controlHits: control.interactions.length,
+      sourceSeparated: config.sourceSeparated,
+      note:
+        `target-token ${target.interactions.length} interaction(s), control-token ${control.interactions.length}` +
+        (notes.length ? `; ${notes.join("; ")}` : ""),
+    },
+  };
+}

package/src/poc-runner.ts

@@ -419,6 +419,36 @@ function outputWasComplete(result: { error?: Error; signal: string | null }): bo
   return !result.error && result.signal === null;
 }
 
+/**
+ * Minimal OS env copied into local PoC spawns so interpreters still resolve
+ * and run (PATH lookup, HOME/TZ/locale/temp, Windows loader vars). Everything
+ * else — proxy URLs with embedded credentials, PI_* operator secrets — stays
+ * out; the harness contract is layered on top by the caller.
+ */
+function minimalLocalEnv(): Record<string, string> {
+  const allow = [
+    "PATH",
+    "HOME",
+    "LANG",
+    "LC_ALL",
+    "LC_CTYPE",
+    "TZ",
+    "TMPDIR",
+    "TEMP",
+    "TMP",
+    "SYSTEMROOT",
+    "WINDIR",
+    "COMSPEC",
+    "PATHEXT",
+  ];
+  const out: Record<string, string> = {};
+  for (const key of allow) {
+    const value = process.env[key];
+    if (value !== undefined) out[key] = value;
+  }
+  return out;
+}
+
 /** Reject control characters in harness-supplied PoC env values. */
 function sanitizePocEnv(env: Record<string, string>): Record<string, string> {
   const out: Record<string, string> = {};
@@ -661,11 +691,15 @@ function runLocal(pocPath: string, language: PocLanguage, env?: Record<string, s
       encoding: "utf8",
       timeout: TIMEOUT_MS,
       maxBuffer: MAX_BUFFER,
-      // Host runs get the harness env contract merged over the operator env;
-      // the spawn env is explicitly provided so PI_POC_MODE / PI_POC_TARGET
-      // reach the script without leaking through a shell. Same control-char
-      // rejection as the sandboxed path.
-      env: { ...process.env, ...sanitizePocEnv(runEnv) },
+      // Host runs get a MINIMAL env: OS locale/temp vars so interpreters
+      // resolve and run, plus the harness env contract — never the operator's
+      // ambient process env. Proxy URLs can embed credentials and PI_*
+      // carries operator secrets (e.g. PI_OOB_ORACLE_TOKEN bearer), and the
+      // PoC script is untrusted agent-authored code. An operator who needs a
+      // specific non-secret value for a local run injects it explicitly via
+      // the run env. The sandboxed path was already minimal (explicit -e
+      // args only).
+      env: { ...minimalLocalEnv(), ...sanitizePocEnv(runEnv) },
     });
 
     // Local runs stay shell-free (space-containing paths stay single args), so
@@ -727,19 +761,24 @@ export function runPoc(pocPath: string, options?: PocRunOptions): PocRun {
 
   const opts: PocRunOptions = options ?? {};
 
+  // Operator/test-harness escape: PI_POC_FORCE_LOCAL=1 together with the
+  // operator opt-in PI_POC_ALLOW_LOCAL=1 runs EVERY PoC on the host, skipping
+  // Docker entirely — including default (network:"none") and OOB runs, not just
+  // local:true ones. Both flags are operator env (never agent-supplied), so this
+  // cannot be triggered by a finding. Without them, execution falls through to
+  // the isolated sandbox as before.
+  if (process.env.PI_POC_FORCE_LOCAL === "1" && process.env[LOCAL_EXEC_ENV] === "1") {
+    return runLocal(normalized, language, opts.env);
+  }
+
   // Host execution is gated by the OPERATOR, never by an agent-supplied flag.
   // `local: true` means "network access needed":
   //   1. Prefer a host-network Docker sandbox (isolation retained).
   //   2. Fall back to bare host ONLY when Docker/image is unavailable AND the
-  //      operator set PI_POC_ALLOW_LOCAL=1.
-  //   3. PI_POC_FORCE_LOCAL=1 + ALLOW lets the operator (or test harness)
-  //      skip Docker and run on the host deliberately — still never agent-only.
+  //      operator set PI_POC_ALLOW_LOCAL=1. (FORCE_LOCAL+ALLOW never reaches
+  //      here — the operator escape above returns before the sandbox path.)
   if (opts.local === true) {
     const allowLocal = process.env[LOCAL_EXEC_ENV] === "1";
-    const forceLocal = process.env.PI_POC_FORCE_LOCAL === "1";
-    if (forceLocal && allowLocal) {
-      return runLocal(normalized, language, opts.env);
-    }
     const sandboxed = runSandboxed(normalized, language, "host", opts.env);
     if (!sandboxed.infraError) {
       return sandboxed;