@clear-capabilities/agentic-security-scanner 0.143.0 → 0.145.0

package/src/dataflow/privacy-taxonomy.js

@@ -0,0 +1,233 @@
+// Privacy data-classification taxonomy (assurance-hardening PRD FR-402).
+//
+// `privacy-taint.js` used to carry a single hardcoded PII_PATTERNS const
+// with exactly four buckets (PII/PHI/PCI/FIN) and no version — extending it
+// (a new regulated-data class, a missed field-name pattern for an existing
+// class) meant editing this package's source. FR-402's acceptance criterion
+// is specifically that the taxonomy is versioned AND customizable without a
+// source change, so this module splits the taxonomy out as data:
+//
+//   - DEFAULT_TAXONOMY ships the seven classes the PRD names by name (PII,
+//     PHI, PCI, FIN, CREDENTIALS, GEOLOCATION, DEVICE_ID), each carrying a
+//     default severity and a list of field-name regex patterns.
+//   - loadPrivacyTaxonomy(scanRoot) reads an OPTIONAL operator config at
+//     .agentic-security/privacy-taxonomy.json and merges it over the
+//     defaults: a class name that already exists gets its patterns
+//     APPENDED (mode:'extend', the default) or REPLACED (mode:'replace');
+//     a class name that doesn't exist is added as a brand-new
+//     organization-defined class. No scanner source file is touched by
+//     either path.
+//
+// Degrades the same way every other operator-config reader in this
+// codebase does (see posture/network-policy-import.js, custom-rules.js):
+// a missing file returns the built-in taxonomy unchanged; a malformed one
+// logs a warning and falls back to the built-in taxonomy rather than
+// throwing and aborting the scan.
+
+import * as fs from 'node:fs';
+import { statePath } from '../posture/state-dir.js';
+
+export const BUILTIN_TAXONOMY_VERSION = '1.0.0';
+
+// Severity ranking used to pick the worst-case severity when a single
+// field/finding matches more than one class (e.g. a "ssn_and_password"
+// field matching both PII and CREDENTIALS).
+export const SEVERITY_RANK = { critical: 4, high: 3, medium: 2, low: 1 };
+
+export const DEFAULT_TAXONOMY = Object.freeze({
+  PII: {
+    severity: 'medium',
+    patterns: [
+      '\\bfirst[_-]?name\\b', '\\blast[_-]?name\\b', '\\bfull[_-]?name\\b',
+      '\\bemail([_-]?address)?\\b', '\\bphone([_-]?number)?\\b', '\\bmobile\\b',
+      '\\baddress(?:_?(?:line|street|city|zip|postal))?\\b',
+      '\\bdob\\b', '\\bdate[_-]?of[_-]?birth\\b', '\\bbirthday\\b', '\\bbirthdate\\b',
+      '\\bage\\b', '\\bgender\\b', '\\bethnicity\\b', '\\brace\\b', '\\bnationality\\b',
+      '\\bssn\\b', '\\bsocial[_-]?security', '\\bnational[_-]?id', '\\bpassport\\b',
+      '\\bdriver[_-]?license\\b', '\\btax[_-]?id\\b', '\\bgovernment[_-]?id\\b',
+      '\\bip[_-]?address\\b',
+    ],
+  },
+  PHI: {
+    severity: 'high',
+    patterns: [
+      '\\b(?:medical|patient|health)[_-]?record\\b',
+      '\\bdiagnosis\\b', '\\bcondition\\b', '\\bsymptom\\b', '\\btreatment\\b',
+      '\\bmedication\\b', '\\bprescription\\b', '\\bdosage\\b',
+      '\\bicd[_-]?(?:9|10|11)\\b', '\\bcpt[_-]?code\\b', '\\bmrn\\b',
+      '\\bmedical[_-]?record[_-]?number\\b', '\\bdoctor[_-]?name\\b',
+      '\\bphysician\\b', '\\binsurance[_-]?id\\b', '\\bhealth[_-]?plan\\b',
+    ],
+  },
+  PCI: {
+    severity: 'high',
+    patterns: [
+      '\\bcredit[_-]?card[_-]?(?:number|num|no)?\\b',
+      '\\bcard[_-]?(?:number|num|no)\\b',
+      '\\b(?:cvc|cvv)2?\\b', '\\bcvc[_-]?code\\b',
+      '\\bexp(?:iry|iration)?(?:_?date)?\\b',
+      '\\bcardholder[_-]?name\\b', '\\bpan\\b',
+      '\\biban\\b', '\\brouting[_-]?number\\b',
+      '\\baccount[_-]?number\\b',
+    ],
+  },
+  FIN: {
+    severity: 'medium',
+    patterns: [
+      '\\bsalary\\b', '\\bincome\\b', '\\bbalance\\b', '\\btransaction[_-]?amount\\b',
+      '\\bbank[_-]?account\\b',
+      '\\bcredit[_-]?score\\b', '\\bnet[_-]?worth\\b',
+    ],
+  },
+  CREDENTIALS: {
+    severity: 'critical',
+    patterns: [
+      '\\bpassword\\b', '\\bpasswd\\b', '\\bapi[_-]?key\\b', '\\bsecret[_-]?key\\b',
+      '\\baccess[_-]?token\\b', '\\brefresh[_-]?token\\b', '\\bauth[_-]?token\\b',
+      '\\bprivate[_-]?key\\b', '\\bclient[_-]?secret\\b', '\\bsession[_-]?token\\b',
+      '\\bsecurity[_-]?answer\\b', '\\bpin[_-]?code\\b',
+    ],
+  },
+  GEOLOCATION: {
+    severity: 'medium',
+    patterns: [
+      '\\bgeo[_-]?location\\b', '\\blatitude\\b', '\\blongitude\\b',
+      '\\bgps[_-]?coord(?:inates?)?\\b', '\\bprecise[_-]?location\\b',
+      '\\bcurrent[_-]?location\\b',
+    ],
+  },
+  DEVICE_ID: {
+    severity: 'low',
+    patterns: [
+      '\\bdevice[_-]?id\\b', '\\bimei\\b', '\\budid\\b', '\\bmac[_-]?address\\b',
+      '\\badvertising[_-]?id\\b', '\\bidfa\\b', '\\bandroid[_-]?id\\b',
+    ],
+  },
+});
+
+function _taxonomyStatePath(scanRoot) {
+  return statePath(scanRoot, 'privacy-taxonomy.json');
+}
+
+/**
+ * Compile a taxonomy (class -> {severity, patterns: string[]}) into
+ * class -> {severity, regexes: RegExp[]} for repeated use across a scan.
+ */
+export function compileTaxonomy(taxonomy) {
+  const compiled = {};
+  for (const [cls, def] of Object.entries(taxonomy || {})) {
+    const patterns = Array.isArray(def?.patterns) ? def.patterns : [];
+    const regexes = [];
+    for (const p of patterns) {
+      try { regexes.push(new RegExp(p, 'i')); } catch { /* skip an invalid operator-supplied pattern */ }
+    }
+    compiled[cls] = { severity: def?.severity || 'medium', regexes };
+  }
+  return compiled;
+}
+
+const _BUILTIN_COMPILED = compileTaxonomy(DEFAULT_TAXONOMY);
+
+/**
+ * Merge an operator-supplied taxonomy config over DEFAULT_TAXONOMY.
+ * Never mutates DEFAULT_TAXONOMY. `raw.classes[name].mode` controls how an
+ * existing class is merged: 'extend' (default) appends patterns to the
+ * built-in list; 'replace' discards the built-in patterns for that class.
+ * A class name not present in DEFAULT_TAXONOMY is added as-is (a new
+ * organization-defined class) and defaults to severity 'medium' if unset.
+ */
+function _mergeTaxonomy(raw) {
+  const merged = {};
+  for (const [cls, def] of Object.entries(DEFAULT_TAXONOMY)) {
+    merged[cls] = { severity: def.severity, patterns: [...def.patterns] };
+  }
+  const classes = raw && typeof raw.classes === 'object' && raw.classes ? raw.classes : {};
+  let customized = false;
+  for (const [cls, def] of Object.entries(classes)) {
+    const patterns = Array.isArray(def?.patterns) ? def.patterns.filter(p => typeof p === 'string') : [];
+    if (!patterns.length) continue;
+    customized = true;
+    const existing = merged[cls];
+    if (existing && def?.mode !== 'replace') {
+      merged[cls] = {
+        severity: typeof def?.severity === 'string' ? def.severity : existing.severity,
+        patterns: [...existing.patterns, ...patterns],
+      };
+    } else {
+      merged[cls] = {
+        severity: typeof def?.severity === 'string' ? def.severity : (existing?.severity || 'medium'),
+        patterns,
+      };
+    }
+  }
+  return { taxonomy: merged, customized };
+}
+
+/**
+ * Load the effective privacy taxonomy for a scan: the built-in defaults,
+ * merged with .agentic-security/privacy-taxonomy.json when present. Never
+ * throws — a missing file returns the built-in taxonomy; a malformed one
+ * logs a warning and falls back to the built-in taxonomy untouched.
+ *
+ * Returns { version, taxonomy, compiled, customized }.
+ */
+export function loadPrivacyTaxonomy(scanRoot) {
+  if (!scanRoot) {
+    return { version: BUILTIN_TAXONOMY_VERSION, taxonomy: DEFAULT_TAXONOMY, compiled: _BUILTIN_COMPILED, customized: false };
+  }
+  const fp = _taxonomyStatePath(scanRoot);
+  // Read-first, not existsSync()-then-readFileSync() — the file can vanish
+  // between those two calls (TOCTOU). ENOENT is the expected "no config"
+  // case and degrades silently; anything else (bad JSON, permission
+  // denied) logs a warning and falls back the same way.
+  let raw = null;
+  try {
+    raw = JSON.parse(fs.readFileSync(fp, 'utf8'));
+  } catch (e) {
+    if (e.code !== 'ENOENT') {
+      console.error(`agentic-security: bad JSON in privacy-taxonomy.json — falling back to the built-in taxonomy (${e.message})`);
+    }
+    raw = null;
+  }
+  if (!raw) {
+    return { version: BUILTIN_TAXONOMY_VERSION, taxonomy: DEFAULT_TAXONOMY, compiled: _BUILTIN_COMPILED, customized: false };
+  }
+  const { taxonomy, customized } = _mergeTaxonomy(raw);
+  const version = typeof raw.taxonomyVersion === 'string' && raw.taxonomyVersion
+    ? raw.taxonomyVersion
+    : (customized ? `${BUILTIN_TAXONOMY_VERSION}+custom` : BUILTIN_TAXONOMY_VERSION);
+  return { version, taxonomy, compiled: compileTaxonomy(taxonomy), customized };
+}
+
+/**
+ * Classify a field/variable name against a compiled taxonomy (see
+ * compileTaxonomy). Returns an array of matched class names, in the
+ * taxonomy's own key order — defaults to the built-in taxonomy when none
+ * is supplied, so existing callers with a single argument are unaffected.
+ */
+export function classifyFieldAgainst(name, compiled) {
+  if (!name) return [];
+  const out = [];
+  for (const [cls, def] of Object.entries(compiled || _BUILTIN_COMPILED)) {
+    for (const re of def.regexes) {
+      if (re.test(name)) { out.push(cls); break; }
+    }
+  }
+  return out;
+}
+
+/**
+ * Worst-case (highest) severity among a set of matched class names, per
+ * the given compiled taxonomy. Falls back to 'medium' for an empty or
+ * unrecognized class list — same default the pre-FR-402 code used.
+ */
+export function severityForClasses(classes, compiled) {
+  const table = compiled || _BUILTIN_COMPILED;
+  let best = null;
+  for (const cls of classes || []) {
+    const sev = table[cls]?.severity;
+    if (!sev) continue;
+    if (!best || (SEVERITY_RANK[sev] || 0) > (SEVERITY_RANK[best] || 0)) best = sev;
+  }
+  return best || 'medium';
+}

package/src/discovery/disprove.js

@@ -13,7 +13,7 @@
 // not vote, and is excluded from the denominator rather than counted as
 // agreement. If nobody votes the panel is `undecided` and the candidate
 // SURVIVES — an outage must not quietly delete findings.
-import { resolveLlmInvoke } from './llm-invoke.js';
+import { resolveLlmInvokeWithDecision } from './llm-invoke.js';
 
 const DEFAULT_ANGLES = ['reachability', 'preconditions', 'sanitization'];
 export const REFUTE_ANGLES = Object.freeze([...DEFAULT_ANGLES]);
@@ -51,7 +51,11 @@ function parseVote(raw) {
 
 export async function disproveCandidate(candidate, opts = {}) {
   const angles = Array.isArray(opts.angles) && opts.angles.length ? opts.angles : DEFAULT_ANGLES;
-  const llmInvoke = resolveLlmInvoke(opts);
+  // FR-601: an egress-policy denial resolves llmInvoke to null the same way a
+  // missing endpoint always has, so it falls straight into this module's own
+  // pre-existing rule — "silence never refutes" — with zero votes cast and no
+  // prompt ever built for a denied endpoint.
+  const { invoke: llmInvoke, decision: egressDecision } = resolveLlmInvokeWithDecision({ ...opts, purpose: 'discovery-disprove' });
 
   const votes = [];
   if (typeof llmInvoke === 'function') {
@@ -66,7 +70,7 @@ export async function disproveCandidate(candidate, opts = {}) {
   const refuteCount = votes.filter(v => v.refuted).length;
   const undecided = voterCount === 0;
   const refuted = !undecided && refuteCount * 2 > voterCount;
-  return { ...candidate, refutation: { votes, voterCount, refuteCount, refuted, undecided } };
+  return { ...candidate, refutation: { votes, voterCount, refuteCount, refuted, undecided, egressDecision: egressDecision || undefined } };
 }
 
 export async function disprovePanel(candidates, opts = {}) {

package/src/discovery/hunter.js

@@ -11,7 +11,7 @@
 // discovery pass that cannot run must leave the rest of the scan intact.
 import * as crypto from 'node:crypto';
 import { buildHunterPrompt } from './lenses.js';
-import { resolveLlmInvoke } from './llm-invoke.js';
+import { resolveLlmInvokeWithDecision } from './llm-invoke.js';
 
 function appendEntry(transcript, entry) {
   const prev = transcript.length ? transcript[transcript.length - 1].hash : null;
@@ -75,12 +75,16 @@ export async function runHunter(focusArea, lens, ctx = {}, opts = {}) {
   const transcript = [];
   const lensKey = lens?.key || 'unknown';
   const base = { focusAreaId: focusArea.id, lens: lensKey, transcript };
-  const llmInvoke = resolveLlmInvoke(opts);
+  const { invoke: llmInvoke, decision: egressDecision } = resolveLlmInvokeWithDecision({ ...opts, purpose: 'discovery-hunter' });
 
   if (typeof llmInvoke !== 'function') {
-    const reason = 'no llmInvoke supplied and AGENTIC_SECURITY_LLM_ENDPOINT not set';
-    appendEntry(transcript, { phase: 'init', reason });
-    return { ...base, candidates: [], degraded: true, reason };
+    // FR-601: distinguish "policy denied a configured endpoint" from "nothing
+    // was configured at all" — the reason must reflect which actually happened.
+    const reason = egressDecision
+      ? `egress policy denied this call: ${egressDecision.reason}`
+      : 'no llmInvoke supplied and AGENTIC_SECURITY_LLM_ENDPOINT not set';
+    appendEntry(transcript, { phase: 'init', reason, egressDecision: egressDecision || undefined });
+    return { ...base, candidates: [], degraded: true, reason, egressDecision };
   }
 
   let prompt;

package/src/discovery/index.js

@@ -169,7 +169,7 @@ export async function runDiscovery(ctx = {}, opts = {}) {
   for (const area of areas) {
     let areaDegradedCount = 0;
     for (const lens of lenses) {
-      const run = await runHunter(area, lens, { fileContents: ctx.fileContents || {} }, { llmInvoke });
+      const run = await runHunter(area, lens, { fileContents: ctx.fileContents || {} }, { llmInvoke, scanRoot: opts.scanRoot });
       runs.push({ focusAreaId: run.focusAreaId, lens: run.lens, degraded: run.degraded, reason: run.reason, candidateCount: run.candidates.length });
       if (run.degraded && run.reason) reasons.push(`${area.label} × ${lens.key}: ${run.reason}`);
       if (run.degraded) areaDegradedCount += 1;
@@ -231,7 +231,7 @@ export async function runDiscovery(ctx = {}, opts = {}) {
       'every candidate is reported unconfirmed and severity is not evidence-derived');
   }
   const confirmed = await confirmAll(candidates, { taintProbe });
-  const { survivors, refuted } = await disprovePanel(confirmed, { llmInvoke });
+  const { survivors, refuted } = await disprovePanel(confirmed, { llmInvoke, scanRoot: opts.scanRoot });
   const { fresh, duplicates, suppressed } = judgeCandidates(survivors, ctx.priorScan, ctx.triageFeedback);
 
   // A spent budget is a coverage gap, stated once at the top level rather than

package/src/discovery/llm-invoke.js

@@ -5,6 +5,8 @@
 // other does not, the bug stays buried in one direction.
 //
 
+import { evaluateEgress } from '../egress/policy.js';
+
 const DEFAULT_TIMEOUT_MS = 60000;
 
 export async function defaultLlmInvoke(prompt, opts = {}) {
@@ -88,12 +90,27 @@ export function consensusOf(responses) {
  * An llmInvoke that queries several endpoints and returns the consensus answer.
  * Returns null when no endpoint answered — the callers already treat a null or
  * a throw as degradation, so an all-providers-down run degrades honestly.
+ *
+ * FR-605 (assurance-hardening PRD): each endpoint gets its OWN egress
+ * decision before being included — `mode: local-only` / `deniedProviders`
+ * must not be smuggled past just because the SINGLE-endpoint path already
+ * checks it. A policy-denied endpoint is EXCLUDED from the vote, the exact
+ * same treatment an unreachable endpoint already gets a few lines below
+ * (never counted as dissent) — the module's own established pattern
+ * extended to a second exclusion reason. Returns `{invoke, decisions}`:
+ * `invoke` is null only when EVERY endpoint was denied (the all-down
+ * equivalent); `decisions` is the full per-endpoint array for a caller
+ * that wants it, kept alongside the single aggregate `decision` the
+ * pre-existing callers already read.
  */
-function makeConsensusInvoke(endpoints, { timeoutMs } = {}) {
+function makeConsensusInvoke(endpoints, { timeoutMs, scanRoot, purpose } = {}) {
   const list = parseEndpoints(endpoints);
-  if (list.length === 0) return null;
-  return async (prompt) => {
-    const answers = await Promise.all(list.map(async (url) => {
+  if (list.length === 0) return { invoke: null, decisions: [] };
+  const decisions = list.map(url => evaluateEgress({ scanRoot, purpose: purpose || 'discovery-consensus', endpoint: url }));
+  const allowedList = list.filter((_, i) => decisions[i].allowed);
+  if (allowedList.length === 0) return { invoke: null, decisions };
+  const invoke = async (prompt) => {
+    const answers = await Promise.all(allowedList.map(async (url) => {
       try { return await defaultLlmInvoke(prompt, { timeoutMs, endpoint: url }); }
       catch { return null; } // excluded from the vote, never counted as dissent
     }));
@@ -101,20 +118,59 @@ function makeConsensusInvoke(endpoints, { timeoutMs } = {}) {
     if (value === null) throw new Error('no LLM endpoint answered');
     return value;
   };
+  return { invoke, decisions };
 }
 
-export function resolveLlmInvoke(opts = {}) {
-  // Precedence, most explicit first: an injected callback beats configuration,
-  // and a multi-endpoint list beats a single endpoint. A caller who supplied
-  // their own function must always get exactly that function.
-  if (opts.llmInvoke) return opts.llmInvoke;
+// FR-601: egress policy is evaluated here, BEFORE returning a callable and
+// therefore before either caller (hunter.js, disprove.js) builds a prompt —
+// a denied decision makes this resolve to `invoke: null`, which both callers
+// already treat as "nothing to call" via their existing degrade path, so a
+// denial produces no network request through the exact same code path a
+// missing endpoint always has. `decision` carries the machine-readable
+// reason so callers can distinguish "not configured" from "configured but
+// policy-denied" in their own degrade message, rather than reporting a
+// generic "not set" that would be actively wrong once policy is what
+// blocked the call.
+//
+// FR-605 (assurance-hardening PRD): consensus mode (multiple endpoints) is
+// now egress-filtered per endpoint, same as the single-endpoint path below —
+// this is what closes the actual "a remote URL cannot be smuggled into
+// local-only configuration" gap the paragraph below used to describe as
+// open. Per-endpoint CONSTRAINT dimensions beyond allow/deny/local-only
+// (role/region/repository/path/data-class — one provider allowed, another
+// denied for a REASON beyond the deny-list) remain FR-602's separate scope;
+// what changed here is that the single allow/deny/local-only gate FR-601
+// already built is no longer bypassable just by using multiple endpoints
+// instead of one.
+export function resolveLlmInvokeWithDecision(opts = {}) {
+  // An injected callback is a test/consumer-controlled escape hatch — it
+  // bypasses egress the same way it already bypasses endpoint resolution,
+  // because there is no real endpoint here for a policy to evaluate.
+  if (opts.llmInvoke) return { invoke: opts.llmInvoke, decision: null };
 
   const multi = opts.endpoints || process.env[DEFAULT_CONSENSUS_ENV];
   if (multi) {
-    const consensus = makeConsensusInvoke(multi, { timeoutMs: opts.timeoutMs });
-    if (consensus) return consensus;
+    const { invoke, decisions } = makeConsensusInvoke(multi, { timeoutMs: opts.timeoutMs, scanRoot: opts.scanRoot, purpose: opts.purpose });
+    // A single aggregate `decision` for the pre-existing callers (hunter.js,
+    // disprove.js), which only ever read `.reason` when `invoke` is null —
+    // the all-denied case. The full per-endpoint detail is on `decisions`
+    // for a caller that wants it.
+    const decision = decisions.find(d => !d.allowed) || decisions[0] || null;
+    return { invoke, decision, decisions };
   }
 
-  if (!process.env.AGENTIC_SECURITY_LLM_ENDPOINT) return null;
-  return (prompt) => defaultLlmInvoke(prompt, { timeoutMs: opts.timeoutMs });
+  const endpoint = process.env.AGENTIC_SECURITY_LLM_ENDPOINT;
+  if (!endpoint) return { invoke: null, decision: null };
+
+  const decision = evaluateEgress({ scanRoot: opts.scanRoot, purpose: opts.purpose || 'discovery', endpoint });
+  if (!decision.allowed) return { invoke: null, decision };
+
+  return { invoke: (prompt) => defaultLlmInvoke(prompt, { timeoutMs: opts.timeoutMs }), decision };
+}
+
+export function resolveLlmInvoke(opts = {}) {
+  // Precedence, most explicit first: an injected callback beats configuration,
+  // and a multi-endpoint list beats a single endpoint. A caller who supplied
+  // their own function must always get exactly that function.
+  return resolveLlmInvokeWithDecision(opts).invoke;
 }

package/src/egress/audit.js

@@ -0,0 +1,147 @@
+// Per-call egress audit log (assurance-hardening PRD FR-604).
+//
+// FR-601 gives every outbound LLM call a machine-readable in-memory
+// decision object. FR-604's acceptance criterion asks for more than that:
+// a PERSISTED, per-call audit record — "purpose, provider, model, region if
+// known, byte/token counts, policy, hashes, and outcome" — WITHOUT ever
+// retaining the prohibited prompt content itself. This module is that
+// record.
+//
+// Design: intentionally mirrors mcp/audit.js's proven OWASP-MCP08
+// technique (append-only NDJSON, each entry's `prev` is the SHA-256 of the
+// previous line, so tampering breaks the chain from that point forward) —
+// same shape of guarantee this codebase already ships and tests for MCP
+// tool calls, now for egress calls. Deliberately a SEPARATE, self-contained
+// implementation rather than an import from mcp/audit.js: that module's
+// public surface (`auditCall`) is shaped around {tool, args}, not
+// {purpose, provider, model, region, policy, hashes}, and its hash-chain
+// helpers are private (`_sha`/`_readLastEntryHash`/`_postRemote`, not
+// exported) — reshaping that already-tested, security-relevant module to
+// export shared primitives is a real, separate refactor, not something to
+// fold into one FR cycle. The ~15 lines of hash-chaining logic duplicated
+// here are a well-understood idiom (one sha256 call), not a place where
+// drift risk between the two copies matters in practice.
+//
+// CONTENT NEVER RETAINED: this module accepts a byte count, a token
+// estimate, and a content HASH — never the text itself. A caller that
+// passes raw prompt text here has misused the API; there is no parameter
+// that accepts it.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import { stateDir } from '../posture/state-dir.js';
+
+const GENESIS = 'GENESIS';
+const LOG_FILE_NAME = 'egress-audit.log';
+const SESSION_ID = `${process.pid}-${Date.now().toString(36).slice(-6)}`;
+
+function _sha(s) { return crypto.createHash('sha256').update(s).digest('hex'); }
+
+function _hasProjectMarker(sessionRoot) {
+  const MARKERS = ['.git', 'package.json', 'pyproject.toml', 'go.mod', 'Cargo.toml', 'pom.xml', 'composer.json', 'Gemfile'];
+  for (const m of MARKERS) {
+    try { if (fs.existsSync(path.join(sessionRoot, m))) return true; } catch { /* keep checking */ }
+  }
+  return false;
+}
+
+// Read-first, not existsSync()-then-readFileSync() — ENOENT is the expected
+// "no prior log" case (see this session's D-0012: every optional-file
+// reader in this codebase follows this shape from the start).
+function _readLastEntryHash(logFile) {
+  let all;
+  try {
+    all = fs.readFileSync(logFile, 'utf8');
+  } catch {
+    return GENESIS;
+  }
+  const lines = all.split('\n').filter(Boolean);
+  if (!lines.length) return GENESIS;
+  return _sha(lines[lines.length - 1]);
+}
+
+/**
+ * Compute the {byteCount, tokenCount, contentHash} triple for an outbound
+ * payload WITHOUT the caller having to hash/measure it inline at every call
+ * site. Never returns or logs the text itself.
+ */
+export function payloadMetrics(text) {
+  if (typeof text !== 'string' || text.length === 0) {
+    return { byteCount: 0, tokenCount: 0, contentHash: null };
+  }
+  return {
+    byteCount: Buffer.byteLength(text, 'utf8'),
+    tokenCount: Math.ceil(text.length / 4), // same rough estimate llm-validator/index.js's own R12 ceiling uses
+    contentHash: _sha(text),
+  };
+}
+
+/**
+ * Append one audit entry for an evaluateEgress() decision.
+ *
+ * @param {object} opts
+ * @param {string} opts.scanRoot - project root; entries are only written
+ *   when it looks like a real project (same safety check mcp/audit.js
+ *   uses) so a scratch/temp scanRoot never accumulates an audit file.
+ * @param {object} opts.decision - the object evaluateEgress() returned:
+ *   { allowed, decision, reason?, provider, policySource, purpose }.
+ * @param {object} [opts.ctx] - the SAME ctx object passed to evaluateEgress
+ *   — only `model` and `region` are read from it (if present); nothing
+ *   else is retained.
+ * @param {object} [opts.metrics] - the result of payloadMetrics(text), or
+ *   omitted entirely for a denied call where no payload was ever built.
+ */
+export function recordEgressCall({ scanRoot, decision, ctx = {}, metrics = null } = {}) {
+  if (!scanRoot || !decision) return;
+  try {
+    if (!_hasProjectMarker(scanRoot)) return;
+    const dir = stateDir(scanRoot);
+    fs.mkdirSync(dir, { recursive: true });
+    const logFile = path.join(dir, LOG_FILE_NAME);
+    const entry = {
+      ts: new Date().toISOString(),
+      sessionId: SESSION_ID,
+      purpose: decision.purpose || ctx.purpose || 'unknown',
+      provider: decision.provider || 'unknown',
+      model: typeof ctx.model === 'string' ? ctx.model : null,
+      region: typeof ctx.region === 'string' ? ctx.region : null,
+      policy: { policySource: decision.policySource || 'default' },
+      outcome: decision.decision || (decision.allowed ? 'allow' : 'deny'),
+      ...(decision.reason ? { reason: decision.reason } : {}),
+      byteCount: metrics ? metrics.byteCount : null,
+      tokenCount: metrics ? metrics.tokenCount : null,
+      contentHash: metrics ? metrics.contentHash : null,
+      prev: _readLastEntryHash(logFile),
+    };
+    fs.appendFileSync(logFile, JSON.stringify(entry) + '\n');
+  } catch { /* audit failure must never break the call it is auditing */ }
+}
+
+// Verify the chain from start to end — same contract as mcp/audit.js's
+// verifyAuditLog: { ok: true, entries: N } if intact, or
+// { ok: false, brokenAt, expected, got } at the first broken link.
+export function verifyEgressAuditLog(logFile) {
+  // Read-first, not existsSync()-then-readFileSync() (D-0012) — the file can
+  // vanish between those two calls; ENOENT is the expected "no log yet" case.
+  let text;
+  try {
+    text = fs.readFileSync(logFile, 'utf8');
+  } catch {
+    return { ok: true, entries: 0 };
+  }
+  const lines = text.split('\n').filter(Boolean);
+  let expectedPrev = GENESIS;
+  for (let i = 0; i < lines.length; i++) {
+    let entry;
+    try { entry = JSON.parse(lines[i]); }
+    catch { return { ok: false, brokenAt: i, reason: 'not JSON' }; }
+    if (entry.prev !== expectedPrev) {
+      return { ok: false, brokenAt: i, expected: expectedPrev, got: entry.prev };
+    }
+    expectedPrev = _sha(lines[i]);
+  }
+  return { ok: true, entries: lines.length };
+}
+
+export const _internals = { LOG_FILE_NAME, GENESIS, _hasProjectMarker, _readLastEntryHash };