@xaccefy/pi-casefile 0.9.3 → 0.10.0

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

@@ -727,6 +727,16 @@ 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).

package/src/scratchpad.ts

@@ -1,12 +1,11 @@
 /**
- * Scratchpad — intermediate artifact store for pipeline runs.
+ * Scratchpad — intermediate working-notes store for a run.
  *
  * The casefile owns state transitions; the scratchpad owns artifacts.
- * Agents write their outputs here (recon maps, trace outputs, verification
- * logs) instead of stuffing everything into casefile text fields or relying
- * on each other's output streams (which creates an echo chamber).
+ * The agent writes its outputs here (recon maps, trace outputs, verification
+ * logs) instead of stuffing everything into casefile text fields.
  *
- * Directory layout per pipeline run (one subdir per phase — see PHASE_DIRS):
+ * Directory layout per run (one subdir per phase — see PHASE_DIRS):
  *   {project_root}/.scratchpad/{run_id}/
  *     recon/      — fingerprints, tech detection, surface maps
  *     hunt/       — per-class findings
@@ -74,7 +73,7 @@ export interface ScratchpadResume {
 // ── Constants ────────────────────────────────────────────────────────
 
 // All accepted artifact buckets. Some are legacy/manual-only and should not be
-// scheduled by ScratchpadResume for new swarm runs.
+// scheduled by ScratchpadResume for new runs.
 export const SCRATCHPAD_PHASES: ScratchpadPhase[] = [
   "recon",
   "hunt",