@xaccefy/pi-casefile 0.9.0 → 0.9.2

package/src/pipeline-submit.ts

@@ -18,8 +18,15 @@
  */
 
 import { createHash } from "node:crypto";
-import { existsSync, readFileSync, realpathSync, renameSync, writeFileSync } from "node:fs";
-import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { existsSync, realpathSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { KILL_REASON_VALUES } from "./ledger.ts";
+import {
+  assertSafeRegularFile,
+  assertSafeStateDirectory,
+  readSafeFile,
+  writeSafeFileAtomic,
+} from "./safe-state.ts";
 import { getRunDir, getScratchpadRoot, scratchpad_write } from "./scratchpad.ts";
 
 // ── Types ────────────────────────────────────────────────────────────
@@ -45,6 +52,8 @@ export type SubmitResult = {
 };
 
 type StageSpec = {
+  /** Exact top-level field allowlist; mirrors additionalProperties:false. */
+  allowed: readonly string[];
   /** Fields that must be present and non-empty. */
   required: {
     name: string;
@@ -60,34 +69,25 @@ type StageSpec = {
 
 // ── Stage specs (mirror of schemas/*.json semantics) ─────────────────
 
-const VULN_CLASSES = [
-  "injection",
-  "xss",
-  "idor",
-  "bola",
-  "path-traversal",
-  "ssrf",
-  "command-injection",
-  "deserialization",
-  "auth-bypass",
-  "privilege-escalation",
-  "business-logic",
-  "race-condition",
-  "xxe",
-  "ssti",
-  "open-redirect",
-  "information-disclosure",
-  "crypto-weakness",
-  "other",
-] as const;
-
 // Exported for test/pipeline-submit-schema-parity.test.ts (drift guard
 // against schemas/*.json — the two are kept as mirrors of each other).
 export const SPECS: Record<SubmitStage, StageSpec> = {
   // schemas/stage-finding.json
   hunt: {
+    allowed: [
+      "vuln_class",
+      "file",
+      "line",
+      "endpoint",
+      "sink",
+      "entry_point",
+      "confidence",
+      "evidence",
+      "attacker_model",
+      "subsystem",
+    ],
     required: [
-      { name: "vuln_class", type: "string", enum: VULN_CLASSES },
+      { name: "vuln_class", type: "string" },
       { name: "sink", type: "string" },
       { name: "entry_point", type: "string" },
       { name: "confidence", type: "string", enum: ["low", "medium", "high"] },
@@ -98,8 +98,18 @@ export const SPECS: Record<SubmitStage, StageSpec> = {
   },
   // schemas/stage-trace.json
   trace: {
+    allowed: [
+      "trace_result",
+      "entry_point",
+      "call_chain",
+      "defenses_checked",
+      "attacker_model",
+      "impact_if_reachable",
+      "unreachable_reason",
+      "uncertainty_reason",
+    ],
     required: [
-      { name: "trace_result", type: "string", enum: ["REACHABLE", "UNREACHABLE"] },
+      { name: "trace_result", type: "string", enum: ["REACHABLE", "UNREACHABLE", "UNDETERMINED"] },
       { name: "entry_point", type: "string" },
       { name: "call_chain", type: "array", minItems: 1 },
       { name: "defenses_checked", type: "array" },
@@ -108,13 +118,23 @@ export const SPECS: Record<SubmitStage, StageSpec> = {
     conditional: [
       { when: { field: "trace_result", equals: "REACHABLE" }, require: ["impact_if_reachable"] },
       { when: { field: "trace_result", equals: "UNREACHABLE" }, require: ["unreachable_reason"] },
+      { when: { field: "trace_result", equals: "UNDETERMINED" }, require: ["uncertainty_reason"] },
     ],
   },
   // schemas/stage-skeptic.json
   skeptic: {
+    allowed: [
+      "finding_id",
+      "verdict",
+      "reasoning",
+      "evidence_reviewed",
+      "disconfirmation_attempt",
+      "disproval_reason",
+      "uncertainty_reason",
+    ],
     required: [
       { name: "finding_id", type: "string" },
-      { name: "verdict", type: "string", enum: ["CONFIRMED", "DISPROVEN"] },
+      { name: "verdict", type: "string", enum: ["CONFIRMED", "DISPROVEN", "UNDETERMINED"] },
       { name: "reasoning", type: "string" },
       { name: "evidence_reviewed", type: "array", minItems: 1 },
     ],
@@ -127,19 +147,35 @@ export const SPECS: Record<SubmitStage, StageSpec> = {
         when: { field: "verdict", equals: "CONFIRMED" },
         require: ["disconfirmation_attempt"],
       },
+      { when: { field: "verdict", equals: "UNDETERMINED" }, require: ["uncertainty_reason"] },
     ],
   },
   // schemas/stage-validation.json
   validate: {
+    allowed: [
+      "finding_id",
+      "status",
+      "technique_used",
+      "detection_method",
+      "poc_path",
+      "run_log",
+      "evidence_extracted",
+      "kill_reason",
+      "refinement_attempts",
+    ],
     required: [
       { name: "finding_id", type: "string" },
-      { name: "status", type: "string", enum: ["confirmed", "killed", "reported"] },
+      {
+        name: "status",
+        type: "string",
+        enum: ["pending_confirmation", "killed", "reported"],
+      },
       { name: "technique_used", type: "string" },
       { name: "detection_method", type: "string" },
     ],
     conditional: [
       {
-        when: { field: "status", equals: "confirmed" },
+        when: { field: "status", equals: "pending_confirmation" },
         require: ["poc_path", "run_log", "evidence_extracted"],
       },
       { when: { field: "status", equals: "killed" }, require: ["kill_reason"] },
@@ -147,6 +183,7 @@ export const SPECS: Record<SubmitStage, StageSpec> = {
   },
   // schemas/stage-chain.json
   chain: {
+    allowed: ["chains", "summary", "tokens_input", "tokens_output"],
     required: [
       { name: "chains", type: "array" },
       { name: "summary", type: "string" },
@@ -154,6 +191,16 @@ export const SPECS: Record<SubmitStage, StageSpec> = {
   },
   // schemas/stage-report.json
   report: {
+    allowed: [
+      "target",
+      "pipeline_status",
+      "total_tokens",
+      "findings",
+      "chains",
+      "coverage",
+      "summary",
+      "patches_applied",
+    ],
     required: [
       { name: "target", type: "string" },
       { name: "pipeline_status", type: "string", enum: ["complete", "partial", "aborted"] },
@@ -183,7 +230,7 @@ const CHAIN_SEVERITIES = ["low", "medium", "high", "critical"] as const;
 /**
  * Test/mock/example paths carry no real findings (mirrors VVAH S5). Exception
  * from VVAH deliberately not copied: hardcoded-creds-in-test-files — the
- * auditor can submit those under vuln_class "other"+bugClass documentation;
+ * auditor can submit those under the precise class it decides fits the issue;
  * the gate errs on filtering noise.
  */
 
@@ -212,7 +259,11 @@ function statePath(runId: string): string {
 function readState(runId: string): SubmitState {
   const p = statePath(runId);
   if (!existsSync(p)) return { repairs: {}, accepted_findings: [] };
-  const raw = JSON.parse(readFileSync(p, "utf8")) as Partial<SubmitState>;
+  assertSafeStateDirectory(projectRoot(), [".scratchpad", basename(dirname(p))]);
+  assertSafeRegularFile(p, "Pipeline state");
+  const raw = JSON.parse(
+    readSafeFile(p, "Pipeline state").toString("utf8"),
+  ) as Partial<SubmitState>;
   if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
     throw new Error(`Corrupt pipeline-submit state for ${runId}: root must be an object`);
   }
@@ -246,9 +297,8 @@ function readState(runId: string): SubmitState {
 
 function writeState(runId: string, state: SubmitState): void {
   const p = statePath(runId);
-  const tmp = `${p}.${process.pid}.${Date.now()}.tmp`;
-  writeFileSync(tmp, JSON.stringify(state, null, 2), "utf8");
-  renameSync(tmp, p);
+  assertSafeStateDirectory(projectRoot(), [".scratchpad", basename(dirname(p))]);
+  writeSafeFileAtomic(p, JSON.stringify(state, null, 2));
 }
 
 /** Project root containing the scratchpad (file-existence checks resolve here). */
@@ -352,7 +402,7 @@ function validateReport(errors: string[], obj: Record<string, unknown>): void {
   if (coverage) {
     const allowed = ["COVERED", "SKIPPED", "NOT_FOUND", "INCOMPLETE"];
     for (const [key, value] of Object.entries(coverage)) {
-      if (!/^[a-z-]+$/.test(key)) errors.push(`coverage.${key}: invalid class key`);
+      if (!key.trim() || /[\r\n]/.test(key)) errors.push(`coverage.${key}: invalid class key`);
       if (typeof value !== "string" || !allowed.includes(value)) {
         errors.push(`coverage.${key}: must be one of { ${allowed.join(" | ")} }`);
       }
@@ -407,10 +457,23 @@ function validateReport(errors: string[], obj: Record<string, unknown>): void {
   }
 }
 
+function resolveProjectPath(input: string): { abs: string; rel: string } {
+  const root = projectRoot();
+  const trimmed = input.trim();
+  const relativeInput = trimmed.replace(/^\.\//, "");
+  const abs = isAbsolute(trimmed) ? resolve(trimmed) : resolve(root, relativeInput);
+  return { abs, rel: relative(root, abs) };
+}
+
 function validateStage(stage: SubmitStage, obj: Record<string, unknown>): string[] {
   const spec = SPECS[stage];
   const errors: string[] = [];
 
+  const allowedFields = new Set(spec.allowed);
+  for (const name of Object.keys(obj)) {
+    if (!allowedFields.has(name)) errors.push(`${name}: unknown top-level field`);
+  }
+
   for (const field of spec.required) {
     const v = obj[field.name];
     if (field.type === "string") {
@@ -495,43 +558,24 @@ function validateStage(stage: SubmitStage, obj: Record<string, unknown>): string
   if (stage === "skeptic") {
     requireStringArray(errors, "evidence_reviewed", obj.evidence_reviewed, 1);
     if (obj.verdict === "DISPROVEN" && isNonEmptyString(obj.disproval_reason)) {
-      const allowed = [
-        "unreachable",
-        "framework_protection",
-        "input_validation_blocks",
-        "requires_privilege_attacker_lacks",
-        "intended_behavior",
-        "overstated_impact",
-        "duplicate",
-        "test_artifact",
-        "out_of_scope",
-      ];
-      if (!allowed.includes(obj.disproval_reason)) errors.push("disproval_reason: invalid value");
+      if (!(KILL_REASON_VALUES as readonly string[]).includes(obj.disproval_reason)) {
+        errors.push("disproval_reason: invalid value");
+      }
     }
   }
 
   if (stage === "validate") {
     if (obj.status === "killed" && isNonEmptyString(obj.kill_reason)) {
-      const allowed = [
-        "unreachable",
-        "framework_protection",
-        "input_validation_blocks",
-        "requires_privilege_attacker_lacks",
-        "poc_failed_3x",
-        "no_real_impact",
-        "intended_behavior",
-        "duplicate",
-      ];
-      if (!allowed.includes(obj.kill_reason)) errors.push("kill_reason: invalid value");
+      if (!(KILL_REASON_VALUES as readonly string[]).includes(obj.kill_reason)) {
+        errors.push("kill_reason: invalid value");
+      }
     }
-    if (obj.status === "confirmed" && isNonEmptyString(obj.poc_path)) {
-      // A validate submission asserting "confirmed" must point at a PoC file
+    if (obj.status === "pending_confirmation" && isNonEmptyString(obj.poc_path)) {
+      // A phase-1 validation submission must point at a PoC file
       // that actually exists in the project — same file-existence filter hunt
       // findings get. Otherwise fabricated run logs pass the stage gate.
       const raw = obj.poc_path as string;
-      const normalized = raw.replace(/^\.?\//, "");
-      const abs = isAbsolute(normalized) ? resolve(normalized) : resolve(projectRoot(), normalized);
-      const rel = relative(projectRoot(), abs);
+      const { abs, rel } = resolveProjectPath(raw);
       if (rel.startsWith("..") || isAbsolute(rel)) {
         errors.push("poc_path: must resolve inside the project root");
       } else if (!existsSync(abs)) {
@@ -581,26 +625,24 @@ function validateStage(stage: SubmitStage, obj: Record<string, unknown>): string
 function prefilterHunt(obj: Record<string, unknown>): string | null {
   const file = typeof obj.file === "string" ? obj.file : undefined;
   if (!file) return null; // live target: endpoint locator, nothing to filter
-  const normalized = file.replace(/^\.?\//, "");
-  const segments = normalized.split("/");
-  if (segments.some((s) => TEST_SEGMENT_RE.test(s)) || TEST_FILE_RE.test(normalized)) {
-    return (
-      `test-path filter: "${file}" matches test/fixture/mock paths — findings in ` +
-      `test code are noise. If this is a deliberately-shipped test credential, ` +
-      `re-submit documenting why it ships to production.`
-    );
-  }
   const root = projectRoot();
-  const abs = isAbsolute(normalized) ? resolve(normalized) : resolve(root, normalized);
+  const { abs, rel } = resolveProjectPath(file);
   // Containment: resolved path must stay inside the project, otherwise a
   // "finding" can point at ../ or absolute files outside the target repo.
-  const rel = relative(root, abs);
   if (rel.startsWith("..") || isAbsolute(rel)) {
     return (
       `containment filter: "${file}" resolves outside the project root (${root}). ` +
       `Findings must reference files inside the target repository.`
     );
   }
+  const segments = rel.split("/");
+  if (segments.some((s) => TEST_SEGMENT_RE.test(s)) || TEST_FILE_RE.test(rel)) {
+    return (
+      `test-path filter: "${file}" matches test/fixture/mock paths — findings in ` +
+      `test code are noise. If this is a deliberately-shipped test credential, ` +
+      `re-submit documenting why it ships to production.`
+    );
+  }
   // Symlink containment (same defense as the PoC runner): resolve() is
   // lexical, and existsSync() dereferences symlinks — a workspace symlink to
   // /etc (ln -s /etc etc-link) would otherwise pass both checks and let a
@@ -628,7 +670,10 @@ function prefilterHunt(obj: Record<string, unknown>): string | null {
 }
 
 function dedupHunt(state: SubmitState, obj: Record<string, unknown>): { duplicateOf?: string } {
-  const file = typeof obj.file === "string" ? obj.file.replace(/^\.?\//, "") : undefined;
+  const file =
+    typeof obj.file === "string"
+      ? resolveProjectPath(obj.file).rel.replace(/^\.\//, "")
+      : undefined;
   const endpoint = typeof obj.endpoint === "string" ? obj.endpoint.trim() : undefined;
   const vulnClass = typeof obj.vuln_class === "string" ? obj.vuln_class : undefined;
   const line = typeof obj.line === "number" ? obj.line : undefined;
@@ -724,7 +769,9 @@ export function pipeline_submit(runId: string, stage: SubmitStage, output: unkno
       if (isFileFinding || isEndpointFinding) {
         state.accepted_findings.push({
           key,
-          file: isFileFinding ? (obj.file as string).replace(/^\.?\//, "") : "",
+          file: isFileFinding
+            ? resolveProjectPath(obj.file as string).rel.replace(/^\.\//, "")
+            : "",
           line: typeof obj.line === "number" ? obj.line : undefined,
           endpoint: isEndpointFinding ? (obj.endpoint as string).trim() : undefined,
           vuln_class: obj.vuln_class,

package/src/poc-runner.ts

@@ -1,8 +1,9 @@
 import { spawnSync } from "node:child_process";
-import { createHash } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import {
   copyFileSync,
   existsSync,
+  lstatSync,
   mkdirSync,
   mkdtempSync,
   readFileSync,
@@ -14,6 +15,7 @@ import { tmpdir } from "node:os";
 import { basename, extname, isAbsolute, join, relative, resolve } from "node:path";
 
 import { evidenceNonceMatches, type PoCEvidence, parsePoCEvidence } from "./evidence.ts";
+import { ensureSafeStateDirectory, writeSafeFileExclusive } from "./safe-state.ts";
 import { findWorkspaceRoot } from "./scratchpad.ts";
 
 export type PocRun = {
@@ -84,6 +86,7 @@ export type PocRunOptions = {
 
 /** Operator-only opt-in for host execution (never agent-supplied). */
 const LOCAL_EXEC_ENV = "PI_POC_ALLOW_LOCAL";
+const EVIDENCE_MAX_BYTES = 256 * 1024;
 
 export type PocLanguage = {
   /** Docker image used when running inside the sandbox. */
@@ -128,11 +131,11 @@ const OUTPUT_MAX_CHARS = 4000;
 const TIMEOUT_MS = 30_000;
 /** Completion sentinel echoed after the PoC command inside the sandbox shell. */
 function makeSentinel(): string {
-  return `__PI_POC_DONE_${Math.random().toString(36).slice(2, 12)}__`;
+  return `__PI_POC_DONE_${randomBytes(16).toString("hex")}__`;
 }
 /** Per-run random nonce the PoC must echo in evidence.json (binds evidence to its run). */
 function makeNonce(): string {
-  return `poc_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 12)}`;
+  return `poc_${randomBytes(24).toString("hex")}`;
 }
 /** First-use image downloads are slow — pull outside the run timeout. */
 const PULL_TIMEOUT_MS = 300_000;
@@ -311,16 +314,37 @@ function splitOutput(raw: string): { rawOutput: string; output: string; truncate
 function readEvidence(
   evidenceDir: string,
   nonce: string,
-): { evidence?: PoCEvidence; evidenceSha256?: string; evidenceError?: string } {
+): {
+  evidence?: PoCEvidence;
+  evidenceSha256?: string;
+  evidenceBytes?: Buffer;
+  evidenceError?: string;
+} {
   const p = join(evidenceDir, "evidence.json");
   if (!existsSync(p)) {
     return {
       evidenceError: `evidence.json missing in ${evidenceDir} — the PoC must write it to $PI_POC_EVIDENCE_DIR ({"nonce", "claim", "verify", "observations"})`,
     };
   }
+  const file = lstatSync(p);
+  if (file.isSymbolicLink() || !file.isFile()) {
+    return { evidenceError: "evidence.json must be a regular, non-symlink file" };
+  }
+  if (file.size > EVIDENCE_MAX_BYTES) {
+    return {
+      evidenceError: `evidence.json too large (${file.size} bytes; max ${EVIDENCE_MAX_BYTES})`,
+    };
+  }
+  let bytes: Buffer;
   let raw: unknown;
   try {
-    raw = JSON.parse(readFileSync(p, "utf8"));
+    bytes = readFileSync(p);
+    if (bytes.byteLength > EVIDENCE_MAX_BYTES) {
+      return {
+        evidenceError: `evidence.json too large (${bytes.byteLength} bytes; max ${EVIDENCE_MAX_BYTES})`,
+      };
+    }
+    raw = JSON.parse(bytes.toString("utf8"));
   } catch (e) {
     return { evidenceError: `evidence.json unparseable: ${(e as Error).message}` };
   }
@@ -334,7 +358,8 @@ function readEvidence(
   }
   return {
     evidence: parsed.evidence,
-    evidenceSha256: createHash("sha256").update(readFileSync(p)).digest("hex"),
+    evidenceSha256: createHash("sha256").update(bytes).digest("hex"),
+    evidenceBytes: bytes,
   };
 }
 
@@ -349,21 +374,47 @@ function runProvenance(env?: Record<string, string>): Pick<PocRun, "mode" | "tar
  * "artifact-backed" evidence item hashes a file that no longer exists.
  * Returns the preserved path, or undefined when the file is missing.
  */
-function preserveEvidence(evidenceDir: string, nonce: string): string | undefined {
-  const source = join(evidenceDir, "evidence.json");
-  if (!existsSync(source)) return undefined;
+function preserveEvidence(bytes: Buffer, nonce: string): string | undefined {
   try {
-    const durableDir = join(getProjectRoot(), ".pi", "poc-evidence");
-    mkdirSync(durableDir, { recursive: true });
+    const projectRoot = getProjectRoot();
+    const durableDir = ensureSafeStateDirectory(projectRoot, [".pi", "poc-evidence"]);
     const dest = join(durableDir, `${nonce}.evidence.json`);
-    copyFileSync(source, dest);
+    writeSafeFileExclusive(dest, bytes);
     return dest;
   } catch {
-    // Best-effort: a preserved copy is an audit-trail improvement, not a gate.
+    // Preservation is part of the gate: readAndPreserveEvidence surfaces this
+    // as evidenceError, so confirmation cannot depend on an ephemeral file.
     return undefined;
   }
 }
 
+function readAndPreserveEvidence(
+  evidenceDir: string,
+  nonce: string,
+): {
+  evidence?: PoCEvidence;
+  evidenceSha256?: string;
+  evidencePath?: string;
+  evidenceError?: string;
+} {
+  const read = readEvidence(evidenceDir, nonce);
+  if (!read.evidence || !read.evidenceSha256 || !read.evidenceBytes) {
+    return { evidenceError: read.evidenceError ?? "evidence.json validation failed" };
+  }
+  const evidencePath = preserveEvidence(read.evidenceBytes, nonce);
+  if (!evidencePath) {
+    return {
+      evidenceError:
+        "evidence.json was valid but could not be preserved in the durable evidence store",
+    };
+  }
+  return {
+    evidence: read.evidence,
+    evidenceSha256: read.evidenceSha256,
+    evidencePath,
+  };
+}
+
 function outputWasComplete(result: { error?: Error; signal: string | null }): boolean {
   return !result.error && result.signal === null;
 }
@@ -496,7 +547,7 @@ function runSandboxed(
   const workspaceDir = mkdtempSync(resolve(tmpdir(), "poc-runner-"));
   // Named container so a timed-out / killed client can still be cleaned up —
   // `--rm` alone leaks the container when the CLI dies before the child exits.
-  const containerName = `poc-runner-${process.pid}-${Math.random().toString(36).slice(2, 10)}`;
+  const containerName = `poc-runner-${process.pid}-${randomBytes(8).toString("hex")}`;
   // Evidence contract: harness-owned dir + per-run nonce. The PoC writes
   // evidence.json into $PI_POC_EVIDENCE_DIR (/workspace/evidence inside the
   // container); the nonce binds the file to this run.
@@ -554,8 +605,7 @@ function runSandboxed(
     const raw = (result.stdout ?? "") + (result.stderr ?? "") + spawnErr;
     const completed = raw.includes(sentinel);
     const { rawOutput, output, truncated } = splitOutput(sanitizeOutput(raw.replace(sentinel, "")));
-    const preserved = preserveEvidence(evidenceDir, nonce);
-    const evidence = readEvidence(evidenceDir, nonce);
+    const evidence = readAndPreserveEvidence(evidenceDir, nonce);
     return {
       path: pocPath,
       exitCode: spawnExitCode(result),
@@ -568,7 +618,6 @@ function runSandboxed(
       outputComplete: outputWasComplete(result),
       nonce,
       ...evidence,
-      evidencePath: evidence.evidence ? preserved : undefined,
       ...runProvenance(env),
     };
   } finally {
@@ -628,8 +677,7 @@ function runLocal(pocPath: string, language: PocLanguage, env?: Record<string, s
     const { rawOutput, output, truncated } = splitOutput(
       sanitizeOutput((result.stdout ?? "") + (result.stderr ?? "") + spawnErr),
     );
-    const preserved = preserveEvidence(evidenceDir, nonce);
-    const evidence = readEvidence(evidenceDir, nonce);
+    const evidence = readAndPreserveEvidence(evidenceDir, nonce);
     return {
       path: pocPath,
       exitCode: spawnExitCode(result),
@@ -642,7 +690,6 @@ function runLocal(pocPath: string, language: PocLanguage, env?: Record<string, s
       outputComplete: outputWasComplete(result),
       nonce,
       ...evidence,
-      evidencePath: evidence.evidence ? preserved : undefined,
       ...runProvenance(env),
     };
   } finally {

package/src/safe-state.ts

@@ -0,0 +1,108 @@
+import { randomUUID } from "node:crypto";
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+
+function isWithin(root: string, candidate: string): boolean {
+  const rel = relative(root, candidate);
+  return rel === "" || (!isAbsolute(rel) && rel !== ".." && !rel.startsWith(`..${sep}`));
+}
+
+function validateComponent(component: string): void {
+  if (!component || component === "." || component === ".." || basename(component) !== component) {
+    throw new Error(`Unsafe state path component: ${component}`);
+  }
+}
+
+function verifyDirectory(path: string, canonicalRoot: string): void {
+  const stat = lstatSync(path);
+  if (stat.isSymbolicLink() || !stat.isDirectory()) {
+    throw new Error(`State directory must be a real directory, not a symlink: ${path}`);
+  }
+  const canonical = realpathSync(path);
+  if (!isWithin(canonicalRoot, canonical)) {
+    throw new Error(`State directory resolves outside its workspace: ${path}`);
+  }
+}
+
+/**
+ * Create and verify a state-directory chain beneath a trusted workspace root.
+ * Every child component is checked with lstat so a pre-planted symlink cannot
+ * redirect ledger, evidence, or scratchpad writes outside the workspace.
+ */
+export function ensureSafeStateDirectory(root: string, components: string[]): string {
+  const canonicalRoot = realpathSync(root);
+  let current = resolve(root);
+  for (const component of components) {
+    validateComponent(component);
+    current = join(current, component);
+    if (!existsSync(current)) {
+      try {
+        mkdirSync(current, { mode: 0o700 });
+      } catch (error) {
+        // A concurrent creator is acceptable only if the postcondition below
+        // proves it created a real in-workspace directory.
+        if (!existsSync(current)) throw error;
+      }
+    }
+    verifyDirectory(current, canonicalRoot);
+  }
+  return current;
+}
+
+/** Verify an existing state-directory chain without creating anything. */
+export function assertSafeStateDirectory(root: string, components: string[]): string {
+  const canonicalRoot = realpathSync(root);
+  let current = resolve(root);
+  for (const component of components) {
+    validateComponent(component);
+    current = join(current, component);
+    if (!existsSync(current)) throw new Error(`State directory does not exist: ${current}`);
+    verifyDirectory(current, canonicalRoot);
+  }
+  return current;
+}
+
+/** Return false for a missing file; reject symlinks and special files. */
+export function assertSafeRegularFile(path: string, label = "State file"): boolean {
+  if (!existsSync(path)) return false;
+  const stat = lstatSync(path);
+  if (stat.isSymbolicLink() || !stat.isFile()) {
+    throw new Error(`${label} must be a regular, non-symlink file: ${path}`);
+  }
+  return true;
+}
+
+export function readSafeFile(path: string, label = "State file"): Buffer {
+  if (!assertSafeRegularFile(path, label)) throw new Error(`${label} does not exist: ${path}`);
+  return readFileSync(path);
+}
+
+/**
+ * Write through an exclusive temporary file and atomically rename it into
+ * place. An existing symlink is rejected, and rename replaces the directory
+ * entry rather than following a destination changed after the check.
+ */
+export function writeSafeFileAtomic(path: string, data: string | Buffer): void {
+  assertSafeRegularFile(path);
+  const tmp = join(dirname(path), `.${basename(path)}.${process.pid}.${randomUUID()}.tmp`);
+  try {
+    writeFileSync(tmp, data, { flag: "wx", mode: 0o600 });
+    renameSync(tmp, path);
+  } finally {
+    if (existsSync(tmp)) rmSync(tmp, { force: true });
+  }
+}
+
+/** Create a new immutable state file; collisions and symlinks fail closed. */
+export function writeSafeFileExclusive(path: string, data: string | Buffer): void {
+  writeFileSync(path, data, { flag: "wx", mode: 0o600 });
+}