argusqa-os 9.8.1 → 10.0.0

package/src/orchestration/report-processor.js

@@ -15,6 +15,9 @@ import { applyOverrides }                                                  from
 import { loadBaseline, saveBaseline, applyBaseline, appendTrend, getCurrentBranch } from '../utils/baseline-manager.js';
 import { loadRunHistory, recordRunHistory, applyNoiseFilter }              from '../utils/noise-filter.js';
 import { getRecentChanges, linkRootCauses }                                from '../utils/root-cause-linker.js';
+import { classifySensitivity, summarizeRedaction }                        from '../utils/sensitivity-classifier.js';
+import { effectivePolicyOpts, governanceOptOutClamped }                   from '../utils/redaction-policy.js';
+import { ensureGovernancePolicy, postRedactionAggregate, governanceActive } from '../utils/governance-seam.js';
 
 const logger = childLogger('report-processor');
 
@@ -66,6 +69,24 @@ export function rebuildSummary(report) {
   }
 }
 
+/**
+ * Flatten every finding in a report (route errors, flow findings, codebase) into
+ * one array — used to compute the secret-free governance aggregate. Read-only.
+ * @param {object} report
+ * @returns {object[]}
+ */
+export function collectAllFindings(report) {
+  const out = [];
+  for (const routeResult of (report.routes ?? [])) {
+    for (const err of (routeResult.errors ?? [])) out.push(err);
+  }
+  for (const flowResult of (report.flows ?? [])) {
+    for (const finding of (flowResult.findings ?? [])) out.push(finding);
+  }
+  for (const finding of (report.codebase ?? [])) out.push(finding);
+  return out;
+}
+
 // ── Main Post-Crawl Processor ─────────────────────────────────────────────────
 
 /**
@@ -78,6 +99,13 @@ export function rebuildSummary(report) {
  * @returns {{ reportPath: string, diff: object }}
  */
 export async function processReport(report, { outputDir, severityOverrides }) {
+  // 0. Aegis governance seam (opt-in, AEGIS_FOR_TEAMS §9): if a gov token is set,
+  //    fetch + Ed25519-verify the org's central policy BEFORE any classification so
+  //    every downstream redaction enforces it. Best-effort + fail-closed internally
+  //    (a fetch/verify error leaves the engine on its strict floor). No token ⇒ no
+  //    network, byte-identical.
+  await ensureGovernancePolicy();
+
   // 1. Apply severity overrides (suppress or reclassify findings)
   const { overriddenCount, suppressedCount } = applyOverrides(report, severityOverrides);
   if (overriddenCount > 0 || suppressedCount > 0) {
@@ -129,9 +157,45 @@ export async function processReport(report, { outputDir, severityOverrides }) {
     }
   }
 
-  // 4. Write JSON report
+  // reportPath is computed here (ahead of the write) so step 3c can point each
+  // finding's localRef at the on-disk report file it will be written to.
   const timestamp  = new Date().toISOString().replace(/[:.]/g, '-');
   const reportPath = path.join(outputDir, `error-report-${timestamp}.json`);
+
+  // 3c. Aegis sensitivity classification — tag findings for the egress guards
+  //     (REDACTION_BOUNDARY_MAX_PLAN.md §6 Step 3). Tagging happens on shallow
+  //     CLONES, so the LOCAL report below keeps 100% fidelity — Aegis only ever
+  //     removes detail at an external sink, never on disk.
+  //     SECURITY-CRITICAL: this is the ONE post-processor that fails CLOSED. On
+  //     any error the egress guards must redact everything, so we set the
+  //     _aegisFailClosed flag rather than swallowing-and-continuing.
+  //     A gov token clamps the ARGUS_REDACT_SENSITIVE=0 opt-out (§4.3) so tagging
+  //     still runs under an org policy — a dev can't disable it locally.
+  if (process.env.ARGUS_REDACT_SENSITIVE !== '0' || governanceOptOutClamped()) {
+    try {
+      const { sensitiveCount } = classifySensitivity(report, { reportRef: path.basename(reportPath) });
+      if (sensitiveCount > 0) logger.info(`[ARGUS] Aegis: ${sensitiveCount} finding(s) tagged sensitive`);
+    } catch (err) {
+      logger.error(`[ARGUS] Aegis classify failed — egress guards will fail closed: ${err.message}`);
+      report._aegisFailClosed = true; // sinks read this and redact everything
+    }
+
+    // 3d. Governance audit trail (opt-in): post a SECRET-FREE redaction aggregate
+    //     (byReason label counts only) to the org's audit sink. Best-effort — never
+    //     blocks or fails the run, never sends a secret. No-op unless a gov token +
+    //     ARGUS_REDACT_AUDIT_URL are set.
+    if (governanceActive() && process.env.ARGUS_REDACT_AUDIT_URL) {
+      try {
+        const all = collectAllFindings(report);
+        const summary = summarizeRedaction(all, effectivePolicyOpts({}));
+        await postRedactionAggregate(summary, { meta: { runRef: path.basename(reportPath) } });
+      } catch (err) {
+        logger.debug(`[ARGUS] Aegis governance aggregate skipped: ${err.message}`);
+      }
+    }
+  }
+
+  // 4. Write JSON report
   try {
     fs.writeFileSync(reportPath, JSON.stringify(report, null, 2)); // lgtm[js/network-data-to-file] — intentional: Argus persists crawl findings to a local JSON report file by design
   } catch (err) {

package/src/utils/aegis-vault.js

@@ -0,0 +1,251 @@
+/**
+ * Aegis — local re-hydration vault (Step 8 of REDACTION_BOUNDARY_MAX_PLAN.md).
+ *
+ * OPTIONAL, default OFF (ARGUS_REDACT_VAULT=1 to enable). Implements the enterprise
+ * "smart redaction" reversible-tokenization pattern (plan §5.3): a sensitive span is
+ * replaced on egress (scrubText's `token` mode) by a deterministic, information-free
+ * token (`AEGIS_<hmac16>`), and the token→original mapping is written to a LOCAL,
+ * gitignored, 0600 vault file. The token that crosses the trust boundary reveals
+ * NOTHING; only an operator on THIS machine — who holds the per-machine key and the
+ * vault files — can re-hydrate via `npm run report:rehydrate`.
+ *
+ * SECURITY POSTURE — fail CLOSED (consistent with the rest of Aegis):
+ *   - The token is an HMAC tag → it cannot contain the secret. A leak of the egress
+ *     artifact discloses no plaintext.
+ *   - If the vault is NOT enabled / wired, scrubText's `token` mode falls back to
+ *     MASK (never the raw value) — see secret-patterns.js maskValue.
+ *   - The vault key + mapping files are written 0600 and live under
+ *     reports/.aegis-vault/ (gitignored). The audit trail is secret-free (token only).
+ *
+ * Crypto note (plan §5.3 / §13.6): the default token is HMAC-SHA256 — NOT
+ * format-preserving, so it needs no cipher. If a shape-preserving token is ever
+ * required, use NIST FF1 (SP 800-38G); FF3/FF3-1 were WITHDRAWN by NIST in Feb 2025
+ * and must not be used.
+ *
+ * This module is the ONLY place Aegis does filesystem I/O. secret-patterns.js stays
+ * pure — it receives `tokenFor` through the setVaultTokenizer injection seam.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+import { childLogger } from './logger.js';
+import { getCurrentBranch } from './baseline-manager.js';
+import { setVaultTokenizer } from './secret-patterns.js';
+
+const logger = childLogger('aegis-vault');
+
+const TOKEN_PREFIX = 'AEGIS_';
+const TOKEN_HEX_LEN = 16;                  // 64-bit HMAC tag
+// Matches exactly what computeToken emits — used by rehydrate to find tokens.
+const TOKEN_RE = /AEGIS_[0-9a-f]{16}/g;
+
+let _key = null;        // cached per-machine key (Buffer)
+let _branch = null;     // cached branch name (avoid repeated git calls)
+let _wired = false;     // setVaultTokenizer registered?
+const _seen = new Set(); // tokens persisted this process (in-run dedup)
+
+/** True when the operator opted into the reversible vault. */
+export function vaultEnabled() {
+  return process.env.ARGUS_REDACT_VAULT === '1';
+}
+
+/** Base vault dir (overridable for tests/operators via ARGUS_REDACT_VAULT_DIR). */
+function vaultDir() {
+  return process.env.ARGUS_REDACT_VAULT_DIR || path.join('reports', '.aegis-vault');
+}
+
+/** Secret-free provenance/audit dir (sibling of the vault). */
+function auditDir() {
+  return process.env.ARGUS_REDACT_AUDIT_DIR || path.join('reports', '.aegis-audit');
+}
+
+function keyFile() {
+  return path.join(vaultDir(), 'key');
+}
+
+function ensureDir(dir) {
+  try { fs.mkdirSync(dir, { recursive: true, mode: 0o700 }); } catch { /* best-effort */ }
+}
+
+/**
+ * Per-machine HMAC key. Read from reports/.aegis-vault/key if present, else
+ * generated (32 random bytes) and persisted 0600. Cached in-process. On a write
+ * failure an ephemeral key is used (tokens stay valid within the run).
+ * @returns {Buffer}
+ */
+export function getKey() {
+  if (_key) return _key;
+  const file = keyFile();
+  try {
+    if (fs.existsSync(file)) {
+      const hex = fs.readFileSync(file, 'utf8').trim();
+      if (/^[0-9a-f]{64}$/i.test(hex)) { _key = Buffer.from(hex, 'hex'); return _key; }
+    }
+  } catch { /* fall through and regenerate */ }
+
+  ensureDir(vaultDir());
+  const key = crypto.randomBytes(32);
+  try {
+    // Owner-only (0600) — the key seeds every reversible token. chmod after write is
+    // best-effort (no-op on Windows, where access is ACL-based, not POSIX mode bits).
+    fs.writeFileSync(file, key.toString('hex'), { encoding: 'utf8', mode: 0o600 });
+    try { fs.chmodSync(file, 0o600); } catch { /* mode bits unsupported on this platform */ }
+  } catch (err) {
+    logger.warn(`[ARGUS] Aegis vault: could not persist key — using an ephemeral key: ${err.message}`);
+  }
+  _key = key;
+  return _key;
+}
+
+function currentBranch() {
+  if (_branch) return _branch;
+  try { _branch = getCurrentBranch() || 'default'; } catch { _branch = 'default'; }
+  return _branch;
+}
+
+function vaultFile() {
+  return path.join(vaultDir(), `${currentBranch()}.jsonl`);
+}
+
+/**
+ * Deterministic, information-free token for a value (HMAC-SHA256 tag). Same value ⇒
+ * same token on this machine, so the external artifact stays diff-stable. Does NOT
+ * persist a mapping — use tokenFor for that.
+ * @param {*} value
+ * @returns {string}
+ */
+export function computeToken(value) {
+  const v = String(value ?? '');
+  const tag = crypto.createHmac('sha256', getKey()).update(v).digest('hex').slice(0, TOKEN_HEX_LEN);
+  return TOKEN_PREFIX + tag;
+}
+
+/**
+ * Append a secret-free provenance line for an egress action. The audit trail
+ * records WHAT token was minted, never the plaintext (the token is information-free).
+ * Gives the NIST-RMF "traceability" trail without itself storing a secret.
+ * @param {object} entry
+ */
+export function appendAudit(entry) {
+  ensureDir(auditDir());
+  const file = path.join(auditDir(), `${currentBranch()}.jsonl`);
+  const line = JSON.stringify({ ts: new Date().toISOString(), ...entry }) + '\n';
+  try {
+    fs.appendFileSync(file, line, { encoding: 'utf8', mode: 0o600 });
+    try { fs.chmodSync(file, 0o600); } catch { /* unsupported on Windows */ }
+  } catch { /* audit is best-effort; never break egress */ }
+}
+
+/**
+ * Persist a token→value mapping to the vault file (0600). In-run dedup keeps the
+ * file from growing per duplicate span within a single process.
+ * @param {string} token
+ * @param {*} value
+ */
+export function storeMapping(token, value) {
+  if (_seen.has(token)) return;
+  _seen.add(token);
+  ensureDir(vaultDir());
+  const line = JSON.stringify({ token, value: String(value ?? ''), ts: new Date().toISOString() }) + '\n';
+  try {
+    fs.appendFileSync(vaultFile(), line, { encoding: 'utf8', mode: 0o600 });
+    try { fs.chmodSync(vaultFile(), 0o600); } catch { /* unsupported on Windows */ }
+  } catch (err) {
+    logger.warn(`[ARGUS] Aegis vault: mapping write failed: ${err.message}`);
+  }
+  // Secret-free provenance (the token, not the value).
+  appendAudit({ action: 'tokenize', token });
+}
+
+/**
+ * Token for a value: compute the deterministic token AND persist its mapping. This
+ * is the function wired into scrubText's `token` mode (via setVaultTokenizer).
+ * @param {*} value
+ * @returns {string}
+ */
+export function tokenFor(value) {
+  const token = computeToken(value);
+  storeMapping(token, value);
+  return token;
+}
+
+/**
+ * Load every token→value mapping from the vault dir (all *.jsonl, merged) into a
+ * Map. Branch-agnostic so rehydrate works regardless of which branch minted a token.
+ * @returns {Map<string,string>}
+ */
+export function loadVault() {
+  const map = new Map();
+  const dir = vaultDir();
+  let files = [];
+  try { files = fs.readdirSync(dir).filter((f) => f.endsWith('.jsonl')); } catch { return map; }
+  for (const f of files) {
+    let raw;
+    try { raw = fs.readFileSync(path.join(dir, f), 'utf8'); } catch { continue; }
+    for (const line of raw.split('\n')) {
+      const s = line.trim();
+      if (!s) continue;
+      try {
+        const { token, value } = JSON.parse(s);
+        if (typeof token === 'string') map.set(token, value);
+      } catch { /* skip a malformed line */ }
+    }
+  }
+  return map;
+}
+
+/**
+ * Re-inflate a redacted object/string by swapping every AEGIS_ token back to its
+ * original from the vault. Unknown tokens (no mapping) are left untouched. Returns a
+ * BRAND-NEW value — never mutates the input.
+ * @param {*} obj
+ * @param {Map<string,string>} [vault]
+ * @returns {*}
+ */
+export function rehydrate(obj, vault) {
+  const map = vault || loadVault();
+  const walk = (v) => {
+    if (typeof v === 'string') {
+      return v.replace(TOKEN_RE, (tok) => (map.has(tok) ? map.get(tok) : tok));
+    }
+    if (Array.isArray(v)) return v.map(walk);
+    if (v && typeof v === 'object') {
+      const out = {};
+      for (const k of Object.keys(v)) out[k] = walk(v[k]);
+      return out;
+    }
+    return v;
+  };
+  return walk(obj);
+}
+
+/**
+ * Wire (or un-wire) the scrubText `token` mode seam. When the vault is enabled,
+ * registers tokenFor as the tokenizer; otherwise ensures the seam is OFF so token
+ * mode falls back to mask (fail-closed). Idempotent + cheap — the egress path calls
+ * this before redacting in token mode.
+ * @returns {boolean} whether the vault is now wired
+ */
+export function ensureVaultWired() {
+  if (vaultEnabled()) {
+    if (!_wired) { setVaultTokenizer(tokenFor); _wired = true; }
+    return true;
+  }
+  if (_wired) { setVaultTokenizer(null); _wired = false; }
+  return false;
+}
+
+/** Test seam — clears cached key/branch/dedup/wiring. NOT for production use. */
+export function _resetVaultForTests() {
+  _key = null;
+  _branch = null;
+  _wired = false;
+  _seen.clear();
+  setVaultTokenizer(null);
+}
+
+// Wire on import when the env var is already set (the production case, where the
+// process is launched with ARGUS_REDACT_VAULT=1). The egress path additionally calls
+// ensureVaultWired() lazily, so an env var set after import is still honoured.
+ensureVaultWired();

package/src/utils/github-reporter.js

@@ -29,6 +29,7 @@
 import { childLogger } from './logger.js';
 import { parsePrUrl } from './pr-diff-analyzer.js';
 import { githubFetch } from './github-api.js';
+import { redactForEgress, redactReport, buildRedactionRider } from './sensitivity-classifier.js';
 
 const logger = childLogger('github-reporter');
 
@@ -130,6 +131,12 @@ export function formatPrComment(report, diff) {
     `**Base URL**: ${baseUrl}  `,
     `**Run time**: ${runDate}  `,
     '',
+    // Aegis (Step 6): when findings were redacted at the egress boundary, say so — the
+    // reader sees titles/types, never the raw exploit detail. Additive + gated, so a report
+    // that carries no `redaction` rider (every pre-Aegis caller / opt-out) renders unchanged.
+    ...(report.redaction && report.redaction.redacted > 0
+      ? [`> 🔒 ${report.redaction.redacted} finding(s) redacted at the boundary — full detail in the local report`, '']
+      : []),
     ...(report.prValidation ? prValidationBanner(report.prValidation) : []),
     '| | 🔴 Critical | 🟡 Warning | 🔵 Info | Total |',
     '|---|---|---|---|---|',
@@ -524,9 +531,20 @@ export function isGitHubConfigured() {
 export async function reportToGitHub(report, diff) {
   const tasks = [];
 
+  // Aegis egress guard (Step 6): GitHub (PR comment, Check Run, commit status) is a
+  // third-party sink read by anyone with repo access (A2). Project the WHOLE report once
+  // through redactReport — every finding array reduced to the deny-by-default allowlist, a
+  // `redaction` rider attached (drives the comment's 🔒 notice), metadata + severity counts
+  // preserved (so buildStatusPayload's merge gate is unchanged). The findings are already
+  // step-3c-tagged in the runCrawl path, so redactReport honours each finding's `sensitive`
+  // flag + the report-level `_aegisFailClosed`. ARGUS_REDACT_SENSITIVE=0 ⇒ raw passthrough.
+  const guarded = process.env.ARGUS_REDACT_SENSITIVE === '0'
+    ? report
+    : redactReport(report, { localReportPath: process.env.ARGUS_REPORT_URL || null });
+
   if (process.env.GITHUB_PR_NUMBER) {
     tasks.push(
-      postPrComment(report, diff).catch(err =>
+      postPrComment(guarded, diff).catch(err =>
         logger.warn(`[ARGUS] C2: PR comment failed — ${err.message}`)
       )
     );
@@ -535,7 +553,7 @@ export async function reportToGitHub(report, diff) {
   if (process.env.GITHUB_SHA) {
     // Commit status (fast, minimal)
     tasks.push(
-      setCommitStatus(report, diff).catch(err =>
+      setCommitStatus(guarded, diff).catch(err =>
         logger.warn(`[ARGUS] C2: Commit status failed — ${err.message}`)
       )
     );
@@ -543,7 +561,7 @@ export async function reportToGitHub(report, diff) {
     // Check Run (rich output — created and completed in sequence)
     tasks.push(
       createCheckRun(undefined, process.env.GITHUB_SHA)
-        .then(id => completeCheckRun(id, report, diff))
+        .then(id => completeCheckRun(id, guarded, diff))
         .catch(err =>
           logger.warn(`[ARGUS] C2: Check run failed — ${err.message}`)
         )
@@ -690,7 +708,18 @@ export async function reportPrValidation(result, { prUrl } = {}) {
     return { posted: false, checked: false, skipped: true, reason: 'no resolvable repo / PR number — PR reporting skipped' };
   }
 
-  const report = prResultToReport(result);
+  // Aegis egress guard (Step 6): the PR-Validator path reaches here with RAW findings (it does
+  // not run report-processor step 3c). Project them through redactForEgress BEFORE prResultToReport
+  // builds the comment, so the posted PR comment / Check Run carry titles + scrubbed messages, never
+  // exploit detail (A1/A2). The block decision was already computed upstream on the RAW findings.
+  // Attach a `redaction` rider so formatPrComment renders the 🔒 notice. Opt-out ⇒ raw passthrough.
+  const guardedResult = process.env.ARGUS_REDACT_SENSITIVE === '0'
+    ? result
+    : { ...result, findings: redactForEgress(result?.findings ?? []) };
+  const report = prResultToReport(guardedResult);
+  if (process.env.ARGUS_REDACT_SENSITIVE !== '0') {
+    report.redaction = buildRedactionRider(result?.findings ?? [], { localReportPath: null });
+  }
   // Non-first diff so findings render (not treated as a baseline-establishing first run). The
   // new/persisting split rides on each finding's `isNew` tag (set in the PR-validate paths via
   // tagFindingNovelty); `resolvedCount` comes from the head-vs-base diff (Phase B2) so the

package/src/utils/governance-seam.js

@@ -0,0 +1,237 @@
+/**
+ * Aegis — governance seam (the opt-in, self-hosted central-policy bridge).
+ *
+ * The shipped engine applies a structured redaction policy locally via the
+ * `policy` param / ARGUS_REDACT_POLICY env (redaction-policy.js). This module is
+ * the THIN, OPT-IN network wrapper that lets a self-hosted laptop / CI run
+ * *participate in central governance*: it fetches the org's signed policy from the
+ * closed control plane, VERIFIES it (Ed25519, MITM-resistant), applies it through
+ * the existing `policy` param, caches it with a TTL, and posts SECRET-FREE
+ * redaction aggregates back for the compliance trail.
+ *
+ * OPEN-CORE DISCIPLINE (AEGIS_FOR_TEAMS_PLAN.md §9 — re-read before editing):
+ *   • Inert without a governance token. `ARGUS_GOV_TOKEN` unset ⇒ this module wires
+ *     a source that returns null ⇒ the engine is BYTE-IDENTICAL to v9.9.0. No
+ *     phone-home, no fetch, no new required dependency, no perf cost by default.
+ *   • Fail-CLOSED everywhere. Any fetch / parse / signature error ⇒ the engine
+ *     falls back to the STRICT floor (redact MORE, never less). A verify failure
+ *     NEVER loosens redaction — it is treated exactly as "no policy fetched".
+ *   • Ed25519-signed policy, verified before use. The control plane signs; the
+ *     engine verifies with the org's PUBLIC key (ARGUS_REDACT_POLICY_PUBKEY, pinned
+ *     out-of-band). A bad signature / wrong key / tampered body is rejected → floor.
+ *   • Secret-free aggregates only. What posts to ARGUS_REDACT_AUDIT_URL is the
+ *     `byReason` LABEL stream (secret:* / pii:* / category:* counts) — never a
+ *     secret, token, or raw value. Best-effort: posting never blocks or fails a run.
+ *   • Strict enforcement clamps the local opt-out. When a gov token is present a
+ *     dev cannot set ARGUS_REDACT_SENSITIVE=0 to escape the org policy — that clamp
+ *     is exposed to the classifier via redaction-policy.js governanceOptOutClamped().
+ *
+ * Uses only node:crypto + the global fetch (both built-in on the supported Node) —
+ * NO new dependency. The pure policy resolver stays in redaction-policy.js (I/O-
+ * free); this module does the I/O and injects a sync source into it, mirroring the
+ * aegis-vault.js ⇄ secret-patterns.js setVaultTokenizer seam.
+ *
+ * DEFERRED (needs the central control plane's team-vault endpoint): routing
+ * `mode=token` vault writes/reads to the team endpoint when a gov token is present.
+ * Today `mode=token` without a wired vault degrades to mask in-engine (unchanged).
+ */
+
+import { verify as edVerify, createPublicKey } from 'node:crypto';
+import { childLogger } from './logger.js';
+import { scrubText } from './secret-patterns.js';
+import { resolvePolicy, STRICT_DEFAULT, setGovernanceSource } from './redaction-policy.js';
+
+const logger = childLogger('aegis');
+
+const DEFAULT_TTL_MS = 5 * 60 * 1000; // 5 min — a policy is re-fetched at most this often
+
+// Module-level policy cache. `ok` distinguishes a verified policy (apply the
+// resolved config) from a fetch/verify failure (fail-closed to the strict floor).
+let _cache = { resolved: STRICT_DEFAULT, fetchedAt: null, ok: false, version: null, error: null };
+
+/** True iff a governance token is provisioned — the master switch for the seam. */
+export function governanceActive() {
+  return !!process.env.ARGUS_GOV_TOKEN;
+}
+
+function ttlMs() {
+  const raw = Number(process.env.ARGUS_REDACT_POLICY_TTL_MS);
+  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_TTL_MS;
+}
+
+function pubKeyPem() {
+  return process.env.ARGUS_REDACT_POLICY_PUBKEY || '';
+}
+
+/**
+ * The sync source injected into redaction-policy.js. Returns:
+ *   • null            — governance inactive (no token)  ⇒ engine keeps env/default
+ *   • resolved config — active + a fresh verified policy ⇒ apply it
+ *   • STRICT_DEFAULT  — active but cold / expired / failed ⇒ fail-CLOSED strict floor
+ * Never throws.
+ */
+function governanceSource() {
+  if (!governanceActive()) return null;
+  if (_cache.ok && _cache.fetchedAt !== null && (Date.now() - _cache.fetchedAt) < ttlMs()) {
+    return _cache.resolved;
+  }
+  return STRICT_DEFAULT; // active but no valid policy in force ⇒ strict floor
+}
+
+// Register the source at module load: merely importing this module makes the
+// engine governance-aware (inert until a token is set). Mirrors setVaultTokenizer.
+setGovernanceSource(governanceSource);
+
+/** Key-sorted JSON — the exact bytes the control plane signs over. Must match the
+ *  cloud signer's canonicalize() so a policy signed there verifies here. */
+export function canonicalPolicyBytes(policy) {
+  return JSON.stringify(sortKeys(policy));
+}
+function sortKeys(value) {
+  if (Array.isArray(value)) return value.map(sortKeys);
+  if (value && typeof value === 'object') {
+    const out = {};
+    for (const k of Object.keys(value).sort()) out[k] = sortKeys(value[k]);
+    return out;
+  }
+  return value;
+}
+
+/** Decode an Ed25519 signature that may arrive hex or base64/base64url. */
+function decodeSignature(sig) {
+  if (/^[0-9a-fA-F]+$/.test(sig) && sig.length % 2 === 0) return Buffer.from(sig, 'hex');
+  return Buffer.from(sig.replace(/-/g, '+').replace(/_/g, '/'), 'base64');
+}
+
+/**
+ * Verify a signed-policy payload against the pinned org public key. Returns the
+ * inner policy doc on success; THROWS on any problem (missing fields, no pubkey,
+ * bad signature, wrong key) so the caller fails closed. Exported for unit proof.
+ * @param {{policy?:object, signature?:string}} payload
+ * @param {string} [publicKeyPem]
+ * @returns {object} the verified policy doc
+ */
+export function verifySignedPolicy(payload, publicKeyPem = pubKeyPem()) {
+  if (!payload || typeof payload !== 'object') throw new Error('governance policy payload is not an object');
+  const { policy, signature } = payload;
+  if (!policy || typeof policy !== 'object') throw new Error('governance policy payload missing "policy"');
+  if (typeof signature !== 'string' || signature.length === 0) throw new Error('governance policy payload missing "signature"');
+  if (!publicKeyPem) throw new Error('ARGUS_REDACT_POLICY_PUBKEY is not set — cannot verify a signed policy');
+
+  const key = createPublicKey({ key: publicKeyPem, format: 'pem' });
+  const ok = edVerify(null, Buffer.from(canonicalPolicyBytes(policy), 'utf8'), key, decodeSignature(signature));
+  if (!ok) throw new Error('governance policy signature verification failed');
+  return policy;
+}
+
+async function fetchSignedPolicy(fetchImpl) {
+  const url = process.env.ARGUS_REDACT_POLICY_URL;
+  const token = process.env.ARGUS_GOV_TOKEN;
+  if (!url) throw new Error('ARGUS_REDACT_POLICY_URL is not set');
+  if (!token) throw new Error('ARGUS_GOV_TOKEN is not set');
+  const res = await fetchImpl(url, {
+    headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
+  });
+  if (!res || res.ok !== true) throw new Error(`governance policy fetch HTTP ${res && res.status}`);
+  return res.json();
+}
+
+/**
+ * Fetch + Ed25519-verify + cache the org policy. Idempotent + TTL-gated: at most
+ * one fetch per TTL window. Best-effort and NEVER throws — on any error it caches
+ * the STRICT floor (fail-closed) and returns it. Call once at run start (before the
+ * first redaction); the verified config then feeds every redaction via the source.
+ *
+ * @param {{ fetchImpl?: Function, now?: () => number }} [deps]  test seams
+ * @returns {Promise<typeof STRICT_DEFAULT | null>} null when inactive
+ */
+export async function ensureGovernancePolicy(deps = {}) {
+  if (!governanceActive()) return null; // opt-in: no token ⇒ nothing fetched, byte-identical
+  const now = (deps.now || Date.now)();
+  // Fresh cache (success OR recent failure) ⇒ don't re-hit the endpoint every run.
+  if (_cache.fetchedAt !== null && (now - _cache.fetchedAt) < ttlMs()) {
+    return _cache.ok ? _cache.resolved : STRICT_DEFAULT;
+  }
+  const fetchImpl = deps.fetchImpl || globalThis.fetch;
+  try {
+    if (typeof fetchImpl !== 'function') throw new Error('no fetch implementation available');
+    const payload = await fetchSignedPolicy(fetchImpl);
+    const doc = verifySignedPolicy(payload); // throws on bad sig / wrong key / missing pubkey
+    _cache = { resolved: resolvePolicy(doc), fetchedAt: now, ok: true, version: typeof doc.version === 'number' ? doc.version : null, error: null };
+    logger.info(`[ARGUS] Aegis governance: applied org policy v${_cache.version ?? '?'} (verified)`);
+    return _cache.resolved;
+  } catch (err) {
+    _cache = { resolved: STRICT_DEFAULT, fetchedAt: now, ok: false, version: null, error: String((err && err.message) || err) };
+    logger.warn(`[ARGUS] Aegis governance: policy fetch/verify failed — failing closed to strict floor: ${_cache.error}`);
+    return STRICT_DEFAULT;
+  }
+}
+
+/** Coerce a byReason map into a SECRET-FREE {label:int}. Each label is scrubbed
+ *  (defence in depth — reason labels are structural, but a tainted one dies here)
+ *  and length-capped; each value is a non-negative integer. */
+function safeByReason(byReason) {
+  const out = {};
+  if (!byReason || typeof byReason !== 'object') return out;
+  for (const [rawKey, rawVal] of Object.entries(byReason)) {
+    const label = scrubText(String(rawKey)).slice(0, 64);
+    const n = Number(rawVal);
+    if (label && Number.isFinite(n) && n >= 0) out[label] = Math.floor(n);
+  }
+  return out;
+}
+
+function safeInt(v) {
+  const n = Number(v);
+  return Number.isFinite(n) && n >= 0 ? Math.floor(n) : 0;
+}
+
+/**
+ * POST a SECRET-FREE redaction aggregate to ARGUS_REDACT_AUDIT_URL (the compliance
+ * trail). Best-effort: never blocks, never throws, never sends a secret. The body
+ * carries only label counts + coarse non-secret meta + the enforced policy version.
+ * No-op (not-configured) unless a gov token AND an audit URL are set.
+ *
+ * @param {{ total?:number, redacted?:number, byReason?:object }} summary  from summarizeRedaction
+ * @param {{ fetchImpl?: Function, meta?: object }} [deps]
+ * @returns {Promise<{posted:boolean, reason?:string, body?:object}>}
+ */
+export async function postRedactionAggregate(summary, deps = {}) {
+  const url = process.env.ARGUS_REDACT_AUDIT_URL;
+  const token = process.env.ARGUS_GOV_TOKEN;
+  if (!url || !token) return { posted: false, reason: 'not-configured' };
+
+  const meta = deps.meta && typeof deps.meta === 'object' ? deps.meta : {};
+  const body = {
+    total: safeInt(summary && summary.total),
+    redacted: safeInt(summary && summary.redacted),
+    byReason: safeByReason(summary && summary.byReason),
+    policyVersion: _cache.version,
+    // Coarse, non-secret provenance only — every string is scrubbed.
+    runRef: typeof meta.runRef === 'string' ? scrubText(meta.runRef).slice(0, 128) : null,
+    at: new Date().toISOString(),
+  };
+  try {
+    const fetchImpl = deps.fetchImpl || globalThis.fetch;
+    if (typeof fetchImpl !== 'function') throw new Error('no fetch implementation available');
+    await fetchImpl(url, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    return { posted: true, body };
+  } catch (err) {
+    logger.debug(`[ARGUS] Aegis governance: aggregate POST failed (best-effort, ignored): ${String((err && err.message) || err)}`);
+    return { posted: false, reason: String((err && err.message) || err), body };
+  }
+}
+
+/** The policy version currently in force (for callers/telemetry). null when none. */
+export function governancePolicyVersion() {
+  return governanceActive() && _cache.ok ? _cache.version : null;
+}
+
+/** Test seam: reset the module cache to the cold fail-closed state. */
+export function _resetGovernanceForTests() {
+  _cache = { resolved: STRICT_DEFAULT, fetchedAt: null, ok: false, version: null, error: null };
+}