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

package/src/posture/flow-narration.js

@@ -13,6 +13,8 @@
 //
 // Fail-closed: any LLM error → template fallback, never a missing field.
 
+import { evaluateEgress } from '../egress/policy.js';
+
 const TEMPLATES = {
   'sql-injection': (f) =>
     `An unauthenticated attacker sends a crafted request containing UNION-style SQL syntax in the ${f.source?.variable || 'tainted'} field. The server's database driver executes the injected query verbatim, returning rows from any table the connection has read access to. Typical impact: full table dump of users (emails, password hashes), bypass of authentication via boolean-blind exfiltration. If the DB role has write privileges, the attacker can also INSERT/UPDATE arbitrary rows. Recovery cost: incident response, customer notification, password reset, regulatory reporting if PII leaked.`,
@@ -60,9 +62,12 @@ function _renderTemplate(f) {
 
 // Optional LLM call. Disabled by default; opt-in via env. Falls back to the
 // template on any error.
-async function _renderLlm(f) {
+async function _renderLlm(f, scanRoot) {
   const endpoint = process.env.AGENTIC_SECURITY_LLM_ENDPOINT;
   if (!endpoint) return null;
+  // FR-601: evaluated before the prompt below is built.
+  const egressDecision = evaluateEgress({ scanRoot, purpose: 'flow-narration', endpoint });
+  if (!egressDecision.allowed) return null;
   const apiKey = process.env.AGENTIC_SECURITY_LLM_API_KEY;
   const headers = { 'Content-Type': 'application/json' };
   if (apiKey) headers['Authorization'] = `Bearer ${apiKey}`;
@@ -101,7 +106,7 @@ export async function annotateNarration(findings, opts = {}) {
       f.narration = null;
       continue;
     }
-    let text = useLlm ? await _renderLlm(f) : null;
+    let text = useLlm ? await _renderLlm(f, opts.scanRoot) : null;
     if (!text) text = _renderTemplate(f);
     f.narration = text;
   }

package/src/posture/legal-hold.js

@@ -0,0 +1,140 @@
+// FR-707 (assurance-hardening PRD): "Support legal hold and policy-
+// authorized retention exceptions | Legal hold is identity-bound, reasoned,
+// time-bounded where applicable, and auditable."
+//
+// A third instance of the recurring {owner, reason, expires_at} exception
+// shape this codebase already uses twice — `posture/suppressions.js`'s
+// pro-tier exception (scoped to a FINDING) and `posture/compliance-policy.js`'s
+// structured `not-applicable` (scoped to a COMPLIANCE CONTROL). Per D-0025,
+// these are deliberately distinct mechanisms serving different subjects, not
+// one shared module — this file is the third subject: a STATE ARTIFACT.
+//
+// Field naming matches the existing two schemas' snake_case convention
+// (`owner`, `reason`, `expires_at`) rather than inventing a fourth style.
+//
+//   identity-bound   -> `owner` (required, who placed the hold and is
+//                        accountable for lifting it)
+//   reasoned         -> `reason` (required — "we might need this later" is
+//                        not a reason; same discipline suppressions.js
+//                        already enforces for its own exceptions)
+//   time-bounded
+//     where applicable -> `expires_at` is OPTIONAL: a null/absent value is
+//                        an INDEFINITE hold, which the acceptance
+//                        criterion's own "where applicable" phrase
+//                        explicitly allows (a genuine legal matter may have
+//                        no known end date) — an ISO date value behaves
+//                        exactly like FR-506/FR-1004's own expiring
+//                        exceptions: once past, the hold is no longer
+//                        active and the artifact is exposed to its normal
+//                        retention TTL again.
+//   auditable        -> persisted as a single JSON array under
+//                        `.agentic-security/legal-holds.json` (itself
+//                        registered as operator-config — an operator/legal
+//                        team's own input, never scanner-written from scan
+//                        results), readable via `listLegalHolds`.
+//
+// Consulted from TWO places, not one: `retention-policy.js#findExpiredArtifacts`
+// (defense in depth for any caller reaching it directly) AND `cmdReset`
+// itself for its PLAIN (non-`--expired`) path, which deletes every
+// registered 'generated' artifact unconditionally and would otherwise blow
+// through a hold that only gated TTL expiry.
+
+import * as fs from 'node:fs';
+import { statePath, safeWriteState } from './state-dir.js';
+import { isRegisteredArtifact } from './artifact-registry.js';
+
+export const LEGAL_HOLD_FILE = 'legal-holds.json';
+
+function _loadRaw(scanRoot) {
+  let fp;
+  try { fp = statePath(scanRoot, LEGAL_HOLD_FILE); } catch { return []; }
+  let raw;
+  try { raw = fs.readFileSync(fp, 'utf8'); } catch { return []; }
+  try {
+    const doc = JSON.parse(raw);
+    return Array.isArray(doc) ? doc : [];
+  } catch { return []; }
+}
+
+/**
+ * All legal holds ever recorded for this project, malformed entries
+ * dropped rather than throwing. Never filters by expiry — see
+ * `isUnderHold`/`listLegalHolds` for that.
+ */
+export function loadLegalHolds(scanRoot) {
+  return _loadRaw(scanRoot).filter(h => h && typeof h === 'object' && typeof h.artifact === 'string' && typeof h.owner === 'string' && typeof h.reason === 'string');
+}
+
+/**
+ * Is `artifactName` currently protected by an active (non-expired) hold?
+ * Returns the matching hold record, or null. Multiple holds on the same
+ * artifact are permitted (e.g. two independent legal matters); the first
+ * still-active one found is returned.
+ */
+export function isUnderHold(artifactName, holds, now = Date.now()) {
+  for (const h of holds) {
+    if (h.artifact !== artifactName) continue;
+    if (!h.expires_at) return h; // indefinite hold — always active
+    const t = Date.parse(h.expires_at);
+    if (!Number.isFinite(t) || t >= now) return h;
+  }
+  return null;
+}
+
+/**
+ * Active (non-expired) holds only, unless `includeExpired`. For
+ * `legal-hold list` / auditing.
+ */
+export function listLegalHolds(scanRoot, { includeExpired = false, now = Date.now() } = {}) {
+  const holds = loadLegalHolds(scanRoot);
+  if (includeExpired) return holds;
+  return holds.filter(h => {
+    if (!h.expires_at) return true;
+    const t = Date.parse(h.expires_at);
+    return !Number.isFinite(t) || t >= now;
+  });
+}
+
+/**
+ * Add a legal hold. Validates identity-bound + reasoned up front (both
+ * required, non-empty) and that `expires_at`, if given, is a parseable
+ * date in the future — an already-expired hold would be a hold that
+ * protects nothing, which is never a legitimate request. `artifact` must
+ * name a real registered artifact (artifact-registry.js) — a hold on an
+ * unrecognised name can never protect anything and almost always means a
+ * typo. Returns `{ok:true, hold}` or `{ok:false, reason}`; never throws.
+ */
+export function addLegalHold(scanRoot, { artifact, owner, reason, expires_at } = {}) {
+  if (!artifact || typeof artifact !== 'string') return { ok: false, reason: '--artifact is required' };
+  if (!isRegisteredArtifact(artifact)) return { ok: false, reason: `"${artifact}" is not a registered state artifact` };
+  if (!owner || typeof owner !== 'string') return { ok: false, reason: '--owner is required (identity-bound)' };
+  if (!reason || typeof reason !== 'string') return { ok: false, reason: '--reason is required (reasoned)' };
+  if (expires_at) {
+    const t = Date.parse(expires_at);
+    if (!Number.isFinite(t)) return { ok: false, reason: 'expires_at must be a parseable date' };
+    if (t < Date.now()) return { ok: false, reason: 'expires_at is in the past — a hold that already expired protects nothing' };
+  }
+  const hold = { artifact, owner, reason, expires_at: expires_at || null, created_at: new Date().toISOString() };
+  const holds = _loadRaw(scanRoot);
+  holds.push(hold);
+  const fp = statePath(scanRoot, LEGAL_HOLD_FILE);
+  if (!safeWriteState(fp, JSON.stringify(holds, null, 2) + '\n')) {
+    return { ok: false, reason: 'state writes are disabled (--no-state) or this is not a safe state directory' };
+  }
+  return { ok: true, hold };
+}
+
+/**
+ * Remove every hold on `artifact` (lifting a hold, not letting it expire).
+ * Returns the number removed. A no-op (0) if none existed — never an error.
+ */
+export function removeLegalHold(scanRoot, artifact) {
+  const holds = _loadRaw(scanRoot);
+  const remaining = holds.filter(h => !(h && h.artifact === artifact));
+  const removedCount = holds.length - remaining.length;
+  if (removedCount > 0) {
+    const fp = statePath(scanRoot, LEGAL_HOLD_FILE);
+    safeWriteState(fp, JSON.stringify(remaining, null, 2) + '\n');
+  }
+  return removedCount;
+}

package/src/posture/llm-redteam.js

@@ -13,6 +13,7 @@
 // strategies (encoding/role-play/authority/etc.), severity-graded report.
 
 import { RED_TEAM_PROMPTS, ATTACK_STRATEGIES, PLUGIN_SEVERITY, categorizePrompts, pluginCoverage } from './llm-redteam-prompts.js';
+import { evaluateEgress } from '../egress/policy.js';
 
 // ─── STATIC mode ─────────────────────────────────────────────────────────
 // Scan the repo for prompt files / system-prompt strings and check whether
@@ -173,8 +174,16 @@ function judgeResponse(response, expectedRejection) {
  *  opts: { endpoint, apiKey?, categories?, strategies?, concurrency? }
  *  Returns { results: [...], summary: {...} } */
 export async function runActiveRedteam(opts = {}) {
-  const { endpoint, apiKey, categories, strategies, concurrency = 4 } = opts;
+  const { endpoint, apiKey, categories, strategies, concurrency = 4, scanRoot } = opts;
   if (!endpoint) throw new Error('endpoint URL required');
+  // FR-601: one decision for the whole batch (same endpoint for every
+  // prompt) — evaluated before any prompt in the corpus is sent, not
+  // per-prompt, since a policy verdict on an endpoint does not vary by
+  // which static red-team prompt is about to be sent to it.
+  const egressDecision = evaluateEgress({ scanRoot, purpose: 'llm-redteam', endpoint });
+  if (!egressDecision.allowed) {
+    throw new Error(`egress policy denied this call: ${egressDecision.reason}`);
+  }
 
   let prompts = RED_TEAM_PROMPTS;
   if (Array.isArray(categories) && categories.length) {

package/src/posture/material-change.js

@@ -11,6 +11,7 @@
 // or the command runner) collects the unified diff and feeds hunks into classifyHunk.
 
 import * as cp from 'node:child_process';
+import { loadPrivacyTaxonomy } from '../dataflow/privacy-taxonomy.js';
 
 // Patterns that fire on the deletion side (auth/check removed).
 const DEL_PATTERNS = [
@@ -26,6 +27,21 @@ const DEL_PATTERNS = [
     kind: 'security-middleware-removed', sev: 'medium', evidence: 'Security middleware removed' },
 ];
 
+// FR-307: a new/modified PII/PHI-shaped field is one of the named
+// high-impact categories ("PII" — see HIGH_IMPACT_CATEGORY_OF_KIND below).
+// Reuses dataflow/privacy-taxonomy.js's FR-402 field-name vocabulary
+// (built-in defaults only — this is a coarse architectural-risk signal,
+// not the authoritative privacy classification egress/redact.js and
+// dataflow/privacy-taint.js already own) rather than inventing a second,
+// parallel PII field-name list that could drift from the first.
+const _PII_FIELD_NAMES = [
+  ...(loadPrivacyTaxonomy(null).taxonomy.PII?.patterns || []),
+  ...(loadPrivacyTaxonomy(null).taxonomy.PHI?.patterns || []),
+];
+const PII_FIELD_RE = _PII_FIELD_NAMES.length
+  ? new RegExp('(?:' + _PII_FIELD_NAMES.join('|') + ')\\s*[:=]', 'i')
+  : /(?!)/; // never matches — degrades safely if the taxonomy import ever returns nothing
+
 // Patterns that fire on the addition side (new attack surface introduced).
 const ADD_PATTERNS = [
   { re: /\b(?:app|router)\s*\.\s*(?:get|post|put|patch|delete|all)\s*\(\s*['"][^'"]+['"]/,
@@ -56,8 +72,38 @@ const ADD_PATTERNS = [
     kind: 'pipeline-floating-tag', sev: 'medium', evidence: 'GitHub Actions step pinned to floating tag' },
   { re: /\bprivileged\s*:\s*true\b/i,
     kind: 'new-iac-privilege', sev: 'high', evidence: 'Container/pod marked privileged' },
+  // FR-307: crypto, PII, and schema — the three named high-impact
+  // categories the pre-existing kind taxonomy above did not yet cover.
+  { re: /\b(?:md5|sha1)\s*\(/i,
+    kind: 'weak-crypto-added', sev: 'high', evidence: 'Weak/deprecated hash primitive (MD5/SHA-1) referenced' },
+  { re: /createCipheriv\s*\(\s*['"`](?:des|des-ede3|rc4|bf|rc2)/i,
+    kind: 'weak-crypto-added', sev: 'critical', evidence: 'Weak/deprecated cipher algorithm referenced' },
+  { re: /\b(?:createCipheriv|createDecipheriv|generateKeyPair(?:Sync)?|crypto\.subtle|jwt\.sign|jsonwebtoken)\s*[.(]/,
+    kind: 'crypto-primitive-changed', sev: 'high', evidence: 'Cryptographic primitive or JWT signing usage added or changed' },
+  { re: PII_FIELD_RE,
+    kind: 'new-pii-field', sev: 'high', evidence: 'PII/PHI-shaped field introduced or modified' },
+  { re: /\b(?:ALTER\s+TABLE|CREATE\s+TABLE|DROP\s+(?:TABLE|COLUMN)|ADD\s+COLUMN)\b/i,
+    kind: 'schema-change', sev: 'medium', evidence: 'Database schema change (DDL)' },
 ];
 
+// FR-307: which `kind`s constitute one of the PRD's named high-impact
+// change classes ("Auth, authZ, crypto, PII, schema, infrastructure
+// privilege, and public API changes cannot auto-apply without approval
+// evidence"). A finding whose kind is NOT in this map is still scored for
+// severity as before, but does not by itself trigger the approval gate —
+// only these specific, named categories do.
+export const HIGH_IMPACT_CATEGORY_OF_KIND = {
+  'auth-removed': 'auth',
+  'priv-from-body': 'authZ',
+  'new-pii-field': 'pii',
+  'weak-crypto-added': 'crypto',
+  'crypto-primitive-changed': 'crypto',
+  'schema-change': 'schema',
+  'new-iac-privilege': 'infra-privilege',
+  'pipeline-perms-widened': 'infra-privilege',
+  'new-endpoint': 'public-api',
+};
+
 // Routine / low-risk patterns (NEVER classify higher than 'low').
 const ROUTINE_PATTERNS = [
   /^\+\s*\/\//,                    // adding a comment
@@ -161,3 +207,47 @@ export function classifyGitDiff(rootDir, ref) {
   }
   return classifyDiff(out);
 }
+
+/**
+ * FR-307: classify a candidate FIX (not a committed diff) for high-impact
+ * change classes. `files` is `{relPath: {before, after}}` — exactly the
+ * before/after content shape fix/apply-fix-service.js already has on hand
+ * for every candidate write, so no git invocation or unified-diff text is
+ * needed here. A crude but sufficient line-set diff (lines only in `after`
+ * are additions, lines only in `before` are deletions) is enough for
+ * PATTERN matching — classifyHunk operates per-line regardless of hunk
+ * boundaries, so an imprecise line-diff still detects the same risk
+ * signals a real diff would.
+ *
+ * Returns the same shape classifyDiff() does, plus `highImpactCategories`
+ * — the deduplicated, sorted list of named categories
+ * (auth/authZ/crypto/pii/schema/infra-privilege/public-api) any finding in
+ * this candidate belongs to. An empty list means nothing in the candidate
+ * matched one of the PRD's named high-impact classes — the approval gate
+ * in apply-fix-service.js is a no-op in that case, same
+ * restricts-nothing-until-triggered default this codebase's other policy
+ * gates (egress/policy.js, dataflow/privacy-sink-policy.js) already follow.
+ */
+export function classifyFixMaterialRisk(files) {
+  const findings = [];
+  for (const [file, pair] of Object.entries(files || {})) {
+    const before = String(pair?.before ?? '');
+    const after = String(pair?.after ?? '');
+    if (before === after) continue;
+    const beforeLines = before.split('\n');
+    const afterLines = after.split('\n');
+    const beforeSet = new Set(beforeLines);
+    const afterSet = new Set(afterLines);
+    const add = afterLines.filter(l => !beforeSet.has(l));
+    const del = beforeLines.filter(l => !afterSet.has(l));
+    if (!add.length && !del.length) continue;
+    findings.push(...classifyHunk({ file, add, del }));
+  }
+  const result = summarize(findings);
+  const categories = new Set();
+  for (const f of result.findings) {
+    const cat = HIGH_IMPACT_CATEGORY_OF_KIND[f.kind];
+    if (cat) categories.add(cat);
+  }
+  return { ...result, highImpactCategories: [...categories].sort() };
+}

package/src/posture/policy-bundle.js

@@ -0,0 +1,274 @@
+// Signed, portable policy bundles (assurance-hardening PRD FR-1001).
+//
+// "Support signed portable policy bundles with organization, repository, and
+// environment inheritance" | "Tampered or expired policy is rejected;
+// effective policy is explainable."
+//
+// WHY REUSE evidence-bundle.js's Ed25519 SCHEME, NOT integrity.js's HMAC
+// -------------------------------------------------------------------------
+// A policy bundle is authored by one party (typically a central security
+// team, "the organization") and distributed to many repositories that never
+// had the signing key. integrity.js's per-install symmetric HMAC is
+// tamper-evidence for the SAME install that wrote it — a different install
+// verifying a bundle it didn't sign is exactly the case that scheme cannot
+// serve. evidence-bundle.js already solved this for findings: Ed25519,
+// verify with only the public key. This module reuses that primitive
+// directly (canonicalisation shape, allowlist-signed-fields discipline,
+// exclusive-create key generation) rather than inventing a third signing
+// mechanism, per this session's own established "survey before building a
+// parallel primitive" practice (see D-0023/D-0025 for the same discipline
+// applied to identity and exception mechanisms respectively).
+//
+// EA-03 LESSON, APPLIED HERE FROM THE START
+// -------------------------------------------------------------------------
+// evidence-bundle.js's own history (see its EA-03 comment) is the reason
+// `canonicalPolicyBytes` signs an explicit ALLOWLIST and `verifyPolicyBundle`
+// REJECTS any top-level key outside it: a bundle with a field stapled on
+// after signing must fail verification, not silently pass with the addition
+// unverified. Getting this right on the first pass — rather than discovering
+// the gap the way evidence-bundle.js did — is the entire point of writing it
+// down here.
+//
+// SCOPE — WHAT THIS MODULE DOES NOT DO
+// -------------------------------------------------------------------------
+// It does not invent a policy SCHEMA — `policy` is an opaque object; whatever
+// keys a bundle carries (egress rules, severity floors, approved providers,
+// anything else this repo already treats as policy) are merged the same way.
+// It does not implement deep/recursive merging — inheritance is shallow,
+// top-level-key override (organization -> repository -> environment, most
+// specific wins per key), matching how every other flat policy config file
+// in this repo (egress-policy.yml, compliance-severity-policy.json, …) is
+// already shaped. A future consumer needing nested-key inheritance is new,
+// separate scope, not assumed here.
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import { ensureKeyPair as ensureKeyPairAt } from './evidence-bundle.js';
+import { statePath } from './state-dir.js';
+
+export const POLICY_BUNDLE_SCHEMA = 'agentic-security/policy-bundle@1';
+
+export const SCOPES = ['organization', 'repository', 'environment'];
+// Inheritance order — later entries override earlier ones, per top-level key.
+const INHERITANCE_ORDER = ['organization', 'repository', 'environment'];
+
+function keyDir() {
+  const xdg = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+  return path.join(xdg, 'agentic-security', 'policy-bundles');
+}
+
+/** A SEPARATE Ed25519 keypair from evidence-bundle.js's finding-attestation
+ * key — signing "this policy is authentic" and "this finding really came
+ * from a scan run by me" are different trust domains and must not share a
+ * key. Reuses evidence-bundle.js's hardened, race-safe generation logic
+ * directly (its exclusive-create collision handling is the kind of code
+ * worth NOT re-implementing) rather than duplicating it — the separation
+ * that matters is the DIRECTORY (`policy-bundles/`, isolated from
+ * evidence-bundle.js's own key dir), not the leaf filenames, which are
+ * `attest-key.pem`/`attest-key.pub.pem` regardless of caller (a
+ * evidence-bundle.js internal, not overridable here) — a readability wart,
+ * not a security one, since the directory is what prevents key reuse. */
+export function ensurePolicyKeyPair(dir = keyDir()) {
+  return ensureKeyPairAt(dir);
+}
+
+/**
+ * Deterministic JSON, keys sorted at every level — identical algorithm to
+ * evidence-bundle.js's canonicalJson (duplicated rather than imported: it is
+ * a pure, three-line function, and importing it would couple this module's
+ * signature format to evidence-bundle.js's internals for no real benefit).
+ */
+function canonicalJson(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value ?? null);
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  const keys = Object.keys(value).sort();
+  return `{${keys.map(k => `${JSON.stringify(k)}:${canonicalJson(value[k])}`).join(',')}}`;
+}
+
+// The complete set of fields a legitimately-built bundle carries, BEFORE
+// signing. This is the signed allowlist AND (in verifyPolicyBundle) the
+// complete set of keys a signed bundle is permitted to have alongside
+// `signature` — see the EA-03 note above for why both matter.
+const BUNDLE_FIELDS = ['schema', 'scope', 'policy', 'issuedAt', 'expiresAt'];
+const BUNDLE_TOP_LEVEL_KEYS = new Set([...BUNDLE_FIELDS, 'signature']);
+
+export function canonicalPolicyBytes(bundle) {
+  const signed = {};
+  for (const k of BUNDLE_FIELDS) signed[k] = bundle[k] ?? null;
+  return Buffer.from(canonicalJson(signed), 'utf8');
+}
+
+/**
+ * Build an unsigned bundle. `policy` is caller-supplied and opaque — this
+ * module does not validate its shape, only its provenance and freshness.
+ */
+export function buildPolicyBundle(scope, policy, { issuedAt, expiresAt } = {}) {
+  if (!SCOPES.includes(scope)) return null;
+  if (!policy || typeof policy !== 'object' || Array.isArray(policy)) return null;
+  return {
+    schema: POLICY_BUNDLE_SCHEMA,
+    scope,
+    policy,
+    issuedAt: issuedAt ?? new Date().toISOString(),
+    expiresAt: expiresAt ?? null,
+  };
+}
+
+/** Sign a bundle. Returns a new object; the input is not mutated. */
+export function signPolicyBundle(bundle, privateKeyPem) {
+  const sig = crypto.sign(null, canonicalPolicyBytes(bundle), privateKeyPem);
+  return {
+    ...bundle,
+    signature: { algorithm: 'ed25519', canonicalisation: POLICY_BUNDLE_SCHEMA, value: sig.toString('base64') },
+  };
+}
+
+/**
+ * Verify a bundle: signature authenticity AND freshness. Never throws — a
+ * malformed or tampered bundle from an untrusted source (a repo checking out
+ * whatever an org distributed) is an expected input, not exceptional.
+ *
+ * @returns {{ok: boolean, reason: string|null}}
+ */
+export function verifyPolicyBundle(bundle, publicKeyPem, { now = Date.now() } = {}) {
+  if (!bundle || typeof bundle !== 'object') return { ok: false, reason: 'bundle is not an object' };
+  if (bundle.schema !== POLICY_BUNDLE_SCHEMA) return { ok: false, reason: `unrecognised schema: ${bundle.schema}` };
+  if (!SCOPES.includes(bundle.scope)) return { ok: false, reason: `unrecognised scope: ${bundle.scope}` };
+  const unknownKeys = Object.keys(bundle).filter(k => !BUNDLE_TOP_LEVEL_KEYS.has(k));
+  if (unknownKeys.length) {
+    return { ok: false, reason: `unrecognised top-level key(s) not covered by the signature: ${unknownKeys.join(', ')}` };
+  }
+  const sig = bundle.signature;
+  if (!sig?.value) return { ok: false, reason: 'bundle is unsigned' };
+  if (sig.algorithm !== 'ed25519') return { ok: false, reason: `unsupported algorithm: ${sig.algorithm}` };
+  if (!publicKeyPem) return { ok: false, reason: 'no public key supplied' };
+  let sigOk = false;
+  try {
+    sigOk = crypto.verify(null, canonicalPolicyBytes(bundle), publicKeyPem, Buffer.from(sig.value, 'base64'));
+  } catch (e) {
+    return { ok: false, reason: `verification error: ${e.message}` };
+  }
+  if (!sigOk) return { ok: false, reason: 'signature does not match the bundle contents — it was modified after signing' };
+  if (bundle.expiresAt) {
+    const exp = Date.parse(bundle.expiresAt);
+    if (!Number.isFinite(exp)) return { ok: false, reason: `expiresAt is not a valid date: ${bundle.expiresAt}` };
+    if (exp < now) return { ok: false, reason: `policy expired on ${bundle.expiresAt}` };
+  }
+  return { ok: true, reason: null };
+}
+
+/**
+ * Merge verified bundles into one effective policy, in inheritance order
+ * (organization -> repository -> environment; most specific wins per key).
+ * A tampered or expired bundle is EXCLUDED from the merge (rejected, not
+ * silently dropped — its scope and reason are reported so a rejection is
+ * visible, not just absent). `provenance[key]` names which scope's bundle
+ * last set that key — the "effective policy is explainable" half of the
+ * acceptance criterion.
+ *
+ * @param {Array<{scope: string, bundle: object}>} entries
+ * @param {string} publicKeyPem
+ * @returns {{effective: object, provenance: Record<string,string>,
+ *   accepted: string[], rejected: Array<{scope:string, reason:string}>}}
+ */
+export function resolveEffectivePolicy(entries, publicKeyPem, { now = Date.now() } = {}) {
+  const byScope = new Map();
+  for (const e of entries || []) {
+    if (e && SCOPES.includes(e.scope)) byScope.set(e.scope, e.bundle);
+  }
+  const effective = {};
+  const provenance = {};
+  const accepted = [];
+  const rejected = [];
+  for (const scope of INHERITANCE_ORDER) {
+    const bundle = byScope.get(scope);
+    if (!bundle) continue;
+    const v = verifyPolicyBundle(bundle, publicKeyPem, { now });
+    if (!v.ok) { rejected.push({ scope, reason: v.reason }); continue; }
+    accepted.push(scope);
+    for (const [k, val] of Object.entries(bundle.policy)) {
+      effective[k] = val;
+      provenance[k] = scope;
+    }
+  }
+  return { effective, provenance, accepted, rejected };
+}
+
+/**
+ * Load whichever policy bundle files exist under
+ * `.agentic-security/policy-bundles/{organization,repository,environment}.json`.
+ * Degrades gracefully — a missing directory or missing/malformed individual
+ * file is simply absent from the result, never thrown. Read-first-in-try/
+ * catch throughout (no existsSync-then-readFileSync — D-0012/D-0022).
+ */
+export function loadPolicyBundles(scanRoot) {
+  if (!scanRoot) return [];
+  const entries = [];
+  for (const scope of SCOPES) {
+    let fp;
+    try { fp = statePath(scanRoot, 'policy-bundles', `${scope}.json`); } catch { continue; }
+    let raw;
+    try { raw = fs.readFileSync(fp, 'utf8'); } catch { continue; }
+    try {
+      const bundle = JSON.parse(raw);
+      if (bundle && typeof bundle === 'object') entries.push({ scope, bundle });
+    } catch { /* malformed — skip, do not throw */ }
+  }
+  return entries;
+}
+
+/**
+ * Read the operator-supplied public key an org distributes alongside its
+ * bundles, from `.agentic-security/policy-bundle-public-key.pem`. Returns
+ * null (not a throw) if absent or unreadable — resolution then rejects
+ * every bundle for lack of a key, same as any other "no public key
+ * supplied" case in verifyPolicyBundle.
+ */
+export function loadPolicyPublicKey(scanRoot) {
+  if (!scanRoot) return null;
+  let fp;
+  try { fp = statePath(scanRoot, 'policy-bundle-public-key.pem'); } catch { return null; }
+  try { return fs.readFileSync(fp, 'utf8'); } catch { return null; }
+}
+
+/**
+ * FR-1006 ("policy drift"): does this repository's LOCALLY resolved effective
+ * policy diverge from what the organization-scope bundle alone specifies —
+ * and is anything the repo is relying on actually being rejected (tampered
+ * or expired) rather than enforced? Both are GOVERNANCE gaps, distinct from
+ * risk findings, which is the exact distinction FR-1006's acceptance
+ * criterion asks fleet output to make.
+ *
+ * No bundles configured at all is a no-op (`null`), matching this session's
+ * established convention: drift can only be reported relative to a
+ * baseline, and a repo with no organization bundle has no baseline to drift
+ * from.
+ *
+ * @returns {{accepted: string[], rejected: Array<{scope,reason}>,
+ *   overrides: Array<{key, organizationValue, effectiveValue, overriddenBy}>}
+ *   | null}
+ */
+export function computePolicyDrift(scanRoot) {
+  const entries = loadPolicyBundles(scanRoot);
+  if (!entries.length) return null;
+  const publicKeyPem = loadPolicyPublicKey(scanRoot);
+  const { effective, provenance, accepted, rejected } = resolveEffectivePolicy(entries, publicKeyPem);
+
+  const overrides = [];
+  const orgEntry = entries.find(e => e.scope === 'organization');
+  if (orgEntry && accepted.includes('organization')) {
+    for (const [key, organizationValue] of Object.entries(orgEntry.bundle.policy || {})) {
+      const overriddenBy = provenance[key];
+      if (overriddenBy && overriddenBy !== 'organization' && !_deepEqual(effective[key], organizationValue)) {
+        overrides.push({ key, organizationValue, effectiveValue: effective[key], overriddenBy });
+      }
+    }
+  }
+  return { accepted, rejected, overrides };
+}
+
+function _deepEqual(a, b) {
+  return JSON.stringify(a) === JSON.stringify(b);
+}