@crewhaus/compliance-controls 0.1.3 → 0.1.5

package/dist/index.d.ts

@@ -0,0 +1,108 @@
+import { type AuditKind, type AuditRecord } from "@crewhaus/audit-log";
+import { CrewhausError } from "@crewhaus/errors";
+/**
+ * Catalog R17 `compliance-controls` — Section 39 SOC 2 / ISO 27001 /
+ * HIPAA evidence collection.
+ *
+ * A `ControlDefinition` declares which audit-log records prove a
+ * given control is operating. The collector walks the audit log per
+ * control, gathers matching records into an `EvidenceBundle`, signs
+ * the bundle with HMAC-SHA256, and writes it to
+ *   `.crewhaus/compliance/<framework>/<controlId>/<period>.json`.
+ *
+ * Built-in framework definitions (SOC 2 Type II CC6.x + CC7.x, ISO
+ * 27001 A.12.4, HIPAA §164.312(b)) are exported at module load so
+ * callers don't have to author the filter shapes themselves.
+ *
+ * Layer R17. Pairs with `audit-log` (R-infra — primary record source),
+ * `data-retention-engine` (§39 — adds an audit window so the records
+ * referenced by an in-progress evidence collection are not purged
+ * mid-run).
+ */
+export declare class ComplianceControlsError extends CrewhausError {
+    readonly name = "ComplianceControlsError";
+    constructor(message: string, cause?: unknown);
+}
+export type AuditEventFilter = {
+    /** Match the audit record's `kind` field. */
+    readonly kind?: AuditKind;
+    /** Match a specific top-level field within `payload`. */
+    readonly payloadField?: string;
+    /** Substring match on a serialized payload field — e.g. action="rotate". */
+    readonly payloadFieldEquals?: string;
+    /** Inclusive lower bound on `ts`. */
+    readonly tsAfter?: number;
+    /** Exclusive upper bound on `ts`. */
+    readonly tsBefore?: number;
+};
+export type ControlDefinition = {
+    readonly frameworkId: string;
+    readonly controlId: string;
+    /** Short description shown in the evidence bundle for auditors. */
+    readonly description: string;
+    /** OR-merged: a record matching any filter is evidence for this control. */
+    readonly evidenceQueries: ReadonlyArray<AuditEventFilter>;
+};
+export type EvidenceBundle = {
+    readonly frameworkId: string;
+    readonly controlId: string;
+    readonly description: string;
+    readonly period: string;
+    readonly generatedAt: number;
+    readonly recordCount: number;
+    readonly records: ReadonlyArray<AuditRecord>;
+    /** Hex SHA-256 of the canonical record list, with HMAC signature when keyed. */
+    readonly digest: string;
+    readonly signature: string | null;
+};
+export interface AuditRecordSource {
+    /** Yield every record across all days. */
+    read(): AsyncIterable<AuditRecord>;
+}
+export type CollectOptions = {
+    /** Period label (e.g. "2026-Q2"). Used in the output path. */
+    readonly period: string;
+    /** Optional HMAC key for signing the bundle. */
+    readonly signingKey?: string;
+    /** Optional clock for tests. */
+    readonly now?: () => number;
+};
+export type CollectorOptions = {
+    readonly auditSource: AuditRecordSource;
+    readonly outputDir?: string;
+    readonly controls?: ReadonlyArray<ControlDefinition>;
+};
+export interface ComplianceCollector {
+    registerControl(def: ControlDefinition): void;
+    listControls(filter?: {
+        frameworkId?: string;
+    }): ReadonlyArray<ControlDefinition>;
+    collect(framework: string, controlId: string, opts: CollectOptions): Promise<EvidenceBundle>;
+    collectAll(framework: string, opts: CollectOptions): Promise<ReadonlyArray<EvidenceBundle>>;
+    /** Test seam — write the bundle to disk under the configured outputDir. */
+    writeBundle(bundle: EvidenceBundle): string;
+}
+export declare const SOC2_CONTROLS: ReadonlyArray<ControlDefinition>;
+export declare const ISO27001_CONTROLS: ReadonlyArray<ControlDefinition>;
+export declare const HIPAA_CONTROLS: ReadonlyArray<ControlDefinition>;
+export declare const BUILT_IN_CONTROLS: ReadonlyArray<ControlDefinition>;
+declare function matches(record: AuditRecord, filter: AuditEventFilter): boolean;
+declare function matchesAny(record: AuditRecord, queries: ReadonlyArray<AuditEventFilter>): boolean;
+declare function canonicalDigest(records: ReadonlyArray<AuditRecord>): string;
+declare function signDigest(digest: string, key: string): string;
+export type BundleVerification = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * Re-verify an EvidenceBundle on read. Recomputes the digest over the bundle's
+ * records (so a post-signing payload rewrite is detected), re-checks each
+ * record's body↔hash consistency, and — when a signing key is supplied —
+ * re-derives the HMAC and compares it in constant time. Bundles MUST be
+ * verified with this before being trusted as authoritative evidence.
+ */
+export declare function verifyBundle(bundle: EvidenceBundle, signingKey?: string): BundleVerification;
+export declare function createComplianceCollector(opts: CollectorOptions): ComplianceCollector;
+export { matches as _matchesForTest, matchesAny as _matchesAnyForTest, canonicalDigest as _canonicalDigestForTest, signDigest as _signDigestForTest, };

package/dist/index.js

@@ -0,0 +1,316 @@
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { recomputeRecordHash } from "@crewhaus/audit-log";
+import { CrewhausError } from "@crewhaus/errors";
+/**
+ * Catalog R17 `compliance-controls` — Section 39 SOC 2 / ISO 27001 /
+ * HIPAA evidence collection.
+ *
+ * A `ControlDefinition` declares which audit-log records prove a
+ * given control is operating. The collector walks the audit log per
+ * control, gathers matching records into an `EvidenceBundle`, signs
+ * the bundle with HMAC-SHA256, and writes it to
+ *   `.crewhaus/compliance/<framework>/<controlId>/<period>.json`.
+ *
+ * Built-in framework definitions (SOC 2 Type II CC6.x + CC7.x, ISO
+ * 27001 A.12.4, HIPAA §164.312(b)) are exported at module load so
+ * callers don't have to author the filter shapes themselves.
+ *
+ * Layer R17. Pairs with `audit-log` (R-infra — primary record source),
+ * `data-retention-engine` (§39 — adds an audit window so the records
+ * referenced by an in-progress evidence collection are not purged
+ * mid-run).
+ */
+export class ComplianceControlsError extends CrewhausError {
+    name = "ComplianceControlsError";
+    constructor(message, cause) {
+        super("config", message, cause);
+    }
+}
+// --------------------------------------------------------------------
+// Built-in framework definitions
+// --------------------------------------------------------------------
+export const SOC2_CONTROLS = [
+    {
+        frameworkId: "soc2",
+        controlId: "CC6.1",
+        description: "Logical and physical access controls — every policy decision is audit-logged.",
+        evidenceQueries: [{ kind: "policy_decision" }],
+    },
+    {
+        frameworkId: "soc2",
+        controlId: "CC6.7",
+        description: "Restricted access to system functions — secrets-manager rotation + access events captured.",
+        evidenceQueries: [{ kind: "secrets_rotation" }, { kind: "secrets_access" }],
+    },
+    {
+        frameworkId: "soc2",
+        controlId: "CC7.2",
+        description: "System monitoring — model invocations and tool classifications are captured.",
+        evidenceQueries: [{ kind: "model_call" }, { kind: "tool_classification" }],
+    },
+    {
+        frameworkId: "soc2",
+        controlId: "CC7.3",
+        description: "Detection of incidents — gateway requests captured for replay/replay analysis.",
+        evidenceQueries: [{ kind: "gateway_request" }],
+    },
+];
+export const ISO27001_CONTROLS = [
+    {
+        frameworkId: "iso27001",
+        controlId: "A.12.4",
+        description: "Logging and monitoring — append-only hash-chained audit trail across every privileged operation.",
+        evidenceQueries: [
+            { kind: "policy_decision" },
+            { kind: "model_call" },
+            { kind: "secrets_rotation" },
+            { kind: "deployment_action" },
+        ],
+    },
+];
+export const HIPAA_CONTROLS = [
+    {
+        frameworkId: "hipaa",
+        controlId: "164.312(b)",
+        description: "Audit controls — every access to or decision involving protected data appears in the audit log.",
+        evidenceQueries: [
+            { kind: "policy_decision" },
+            { kind: "secrets_access" },
+            { kind: "tenancy_context" },
+        ],
+    },
+];
+export const BUILT_IN_CONTROLS = [
+    ...SOC2_CONTROLS,
+    ...ISO27001_CONTROLS,
+    ...HIPAA_CONTROLS,
+];
+// --------------------------------------------------------------------
+// Match logic
+// --------------------------------------------------------------------
+function matches(record, filter) {
+    if (filter.kind !== undefined && record.kind !== filter.kind)
+        return false;
+    if (filter.tsAfter !== undefined && record.ts < filter.tsAfter)
+        return false;
+    if (filter.tsBefore !== undefined && record.ts >= filter.tsBefore)
+        return false;
+    if (filter.payloadField !== undefined) {
+        const payload = record.payload;
+        if (payload === null || typeof payload !== "object")
+            return false;
+        // Own-property check only: a filter targets a "top-level field within
+        // payload" (see AuditEventFilter.payloadField). The `in` operator would
+        // also walk the prototype chain, so e.g. `payloadField: "toString"` or
+        // "constructor" would spuriously match every object payload.
+        if (!Object.hasOwn(payload, filter.payloadField))
+            return false;
+        if (filter.payloadFieldEquals !== undefined) {
+            const value = payload[filter.payloadField];
+            if (typeof value === "string") {
+                if (value !== filter.payloadFieldEquals)
+                    return false;
+            }
+            else if (String(value) !== filter.payloadFieldEquals) {
+                return false;
+            }
+        }
+    }
+    return true;
+}
+function matchesAny(record, queries) {
+    if (queries.length === 0)
+        return false;
+    for (const q of queries) {
+        if (matches(record, q))
+            return true;
+    }
+    return false;
+}
+/** Canonical serialization of a record — the bytes the digest must commit to. */
+function canonicalRecord(r) {
+    return JSON.stringify({
+        ts: r.ts,
+        version: r.version,
+        kind: r.kind,
+        seq: r.seq,
+        payload: r.payload,
+        prevHash: r.prevHash,
+        hash: r.hash,
+    });
+}
+function canonicalDigest(records) {
+    // Commit to the FULL record (the payload/kind/ts the auditor actually reads),
+    // not just `r.hash`. Hashing only `r.hash` let an attacker rewrite a written
+    // bundle's payload while leaving its hash field untouched, so digest + HMAC
+    // still validated against content that no longer matched.
+    const text = records.map(canonicalRecord).join("\n");
+    return createHash("sha256").update(text).digest("hex");
+}
+function signDigest(digest, key) {
+    return createHmac("sha256", key).update(digest).digest("hex");
+}
+function constantTimeEqualHex(a, b) {
+    const ab = Buffer.from(a, "utf8");
+    const bb = Buffer.from(b, "utf8");
+    if (ab.length !== bb.length)
+        return false;
+    return timingSafeEqual(ab, bb);
+}
+/**
+ * Re-verify an EvidenceBundle on read. Recomputes the digest over the bundle's
+ * records (so a post-signing payload rewrite is detected), re-checks each
+ * record's body↔hash consistency, and — when a signing key is supplied —
+ * re-derives the HMAC and compares it in constant time. Bundles MUST be
+ * verified with this before being trusted as authoritative evidence.
+ */
+export function verifyBundle(bundle, signingKey) {
+    if (!constantTimeEqualHex(canonicalDigest(bundle.records), bundle.digest)) {
+        return {
+            ok: false,
+            reason: "digest does not match bundle.records (records altered after signing)",
+        };
+    }
+    for (const r of bundle.records) {
+        if (r.hash !== recomputeRecordHash(r)) {
+            return { ok: false, reason: `record seq ${r.seq} body does not hash to its stored hash` };
+        }
+    }
+    if (signingKey !== undefined) {
+        if (bundle.signature === null)
+            return { ok: false, reason: "bundle is unsigned" };
+        if (!constantTimeEqualHex(signDigest(bundle.digest, signingKey), bundle.signature)) {
+            return { ok: false, reason: "HMAC signature mismatch" };
+        }
+    }
+    return { ok: true };
+}
+/**
+ * Reject any path component that could escape the output directory. Each of
+ * `frameworkId` / `controlId` / `period` becomes one path segment in the
+ * evidence-bundle path; a segment containing a path separator (`/` or `\`),
+ * a `..` traversal token, or a NUL byte could redirect the write to an
+ * arbitrary location on disk. Returns true when the component is unsafe.
+ */
+function isUnsafePathComponent(component) {
+    return (component.includes("/") ||
+        component.includes("\\") ||
+        component.includes("\0") ||
+        component === ".." ||
+        component === ".");
+}
+// --------------------------------------------------------------------
+// Collector
+// --------------------------------------------------------------------
+export function createComplianceCollector(opts) {
+    if (opts.auditSource === undefined) {
+        throw new ComplianceControlsError("auditSource is required");
+    }
+    const outputDir = opts.outputDir ?? join(process.cwd(), ".crewhaus", "compliance");
+    const controls = new Map();
+    const seedControls = opts.controls ?? BUILT_IN_CONTROLS;
+    for (const c of seedControls) {
+        controls.set(`${c.frameworkId}::${c.controlId}`, c);
+    }
+    function key(framework, controlId) {
+        return `${framework}::${controlId}`;
+    }
+    return {
+        registerControl(def) {
+            if (typeof def.frameworkId !== "string" || def.frameworkId === "") {
+                throw new ComplianceControlsError("registerControl: frameworkId required");
+            }
+            if (typeof def.controlId !== "string" || def.controlId === "") {
+                throw new ComplianceControlsError("registerControl: controlId required");
+            }
+            controls.set(key(def.frameworkId, def.controlId), def);
+        },
+        listControls(filter) {
+            const items = [...controls.values()];
+            const filtered = filter?.frameworkId !== undefined
+                ? items.filter((c) => c.frameworkId === filter.frameworkId)
+                : items;
+            return filtered.sort((a, b) => a.frameworkId.localeCompare(b.frameworkId) || a.controlId.localeCompare(b.controlId));
+        },
+        async collect(framework, controlId, collectOpts) {
+            const def = controls.get(key(framework, controlId));
+            if (def === undefined) {
+                throw new ComplianceControlsError(`collect: control "${framework}/${controlId}" not registered`);
+            }
+            // Verify the audit chain BEFORE accepting records as evidence — the
+            // plain `read()` iterator does no validation, so a record whose payload
+            // was rewritten (without repairing its hash), or a record deleted from
+            // the middle of the chain, would otherwise flow straight into a signed
+            // bundle presented to auditors as authoritative. We re-check every
+            // record's body↔hash, and the link + gapless-seq contiguity of the
+            // sequence `read()` yields, then filter the verified records.
+            const matched = [];
+            let prev;
+            for await (const record of opts.auditSource.read()) {
+                if (record.hash !== recomputeRecordHash(record)) {
+                    throw new ComplianceControlsError(`collect: audit record at seq ${record.seq} fails hash integrity — its body was modified after signing; refusing to bundle tampered evidence`);
+                }
+                if (prev !== undefined) {
+                    if (record.prevHash !== prev.hash) {
+                        throw new ComplianceControlsError(`collect: audit chain broken at seq ${record.seq} — prevHash does not link to the prior record (a record was reordered or removed)`);
+                    }
+                    if (record.seq !== prev.seq + 1) {
+                        throw new ComplianceControlsError(`collect: audit chain has a seq gap before seq ${record.seq} (expected ${prev.seq + 1}) — a record was removed`);
+                    }
+                }
+                prev = record;
+                if (matchesAny(record, def.evidenceQueries)) {
+                    matched.push(record);
+                }
+            }
+            const digest = canonicalDigest(matched);
+            const signature = collectOpts.signingKey ? signDigest(digest, collectOpts.signingKey) : null;
+            const now = collectOpts.now?.() ?? Date.now();
+            return {
+                frameworkId: def.frameworkId,
+                controlId: def.controlId,
+                description: def.description,
+                period: collectOpts.period,
+                generatedAt: now,
+                recordCount: matched.length,
+                records: matched,
+                digest,
+                signature,
+            };
+        },
+        async collectAll(framework, collectOpts) {
+            const matchingControls = [...controls.values()]
+                .filter((c) => c.frameworkId === framework)
+                .sort((a, b) => a.controlId.localeCompare(b.controlId));
+            if (matchingControls.length === 0) {
+                throw new ComplianceControlsError(`collectAll: no controls registered for framework "${framework}"`);
+            }
+            const bundles = [];
+            for (const c of matchingControls) {
+                bundles.push(await this.collect(c.frameworkId, c.controlId, collectOpts));
+            }
+            return bundles;
+        },
+        writeBundle(bundle) {
+            // All three components are interpolated into the on-disk path; validate
+            // each so a caller-supplied id or period label cannot traverse out of
+            // outputDir (e.g. period "../../etc/cron.d/x" or an absolute path).
+            for (const [field, value] of [
+                ["frameworkId", bundle.frameworkId],
+                ["controlId", bundle.controlId],
+                ["period", bundle.period],
+            ]) {
+                if (isUnsafePathComponent(value)) {
+                    throw new ComplianceControlsError(`writeBundle: ${field} may not contain a path separator or ".." segment (got "${value}")`);
+                }
+            }
+            const path = join(outputDir, bundle.frameworkId, bundle.controlId, `${bundle.period}.json`);
+            mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+            writeFileSync(path, `${JSON.stringify(bundle, null, 2)}\n`, { mode: 0o600 });
+            return path;
+        },
+    };
+}
+export { matches as _matchesForTest, matchesAny as _matchesAnyForTest, canonicalDigest as _canonicalDigestForTest, signDigest as _signDigestForTest, };

package/package.json

@@ -1,19 +1,22 @@
 {
   "name": "@crewhaus/compliance-controls",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "description": "SOC 2 / ISO 27001 / HIPAA control-evidence collection. Walks audit-log per control, writes signed evidence bundles (Section 39)",
-  "main": "src/index.ts",
-  "types": "src/index.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
   "scripts": {
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/audit-log": "0.1.3",
-    "@crewhaus/errors": "0.1.3"
+    "@crewhaus/audit-log": "0.1.5",
+    "@crewhaus/errors": "0.1.5"
   },
   "license": "Apache-2.0",
   "author": {
@@ -33,5 +36,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": ["src", "README.md", "LICENSE", "NOTICE"]
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
 }

package/src/index.test.ts

@@ -1,442 +0,0 @@
-import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { type AuditRecord, recomputeRecordHash } from "@crewhaus/audit-log";
-import {
-  type AuditRecordSource,
-  BUILT_IN_CONTROLS,
-  ComplianceControlsError,
-  HIPAA_CONTROLS,
-  ISO27001_CONTROLS,
-  SOC2_CONTROLS,
-  _canonicalDigestForTest,
-  _matchesAnyForTest,
-  _matchesForTest,
-  _signDigestForTest,
-  createComplianceCollector,
-  verifyBundle,
-} from "./index";
-
-function makeRecord(
-  partial: Pick<AuditRecord, "kind" | "payload"> & Partial<AuditRecord>,
-): AuditRecord {
-  return {
-    ts: partial.ts ?? Date.now(),
-    version: 1,
-    seq: partial.seq ?? 0,
-    kind: partial.kind,
-    payload: partial.payload,
-    prevHash: partial.prevHash ?? "GENESIS",
-    hash: partial.hash ?? `hash-${Math.random()}`,
-  };
-}
-
-// Build a properly hash-chained, valid sequence (seq 0,1,…; prevHash links;
-// real hashes) — collect() now verifies the chain, so its evidence must be
-// genuine. The first record links to GENESIS.
-function chainOf(partials: ReadonlyArray<Pick<AuditRecord, "kind" | "payload">>): AuditRecord[] {
-  const out: AuditRecord[] = [];
-  let prevHash = "GENESIS";
-  partials.forEach((p, seq) => {
-    const base = {
-      ts: 1000 + seq,
-      version: 1 as const,
-      kind: p.kind,
-      seq,
-      payload: p.payload,
-      prevHash,
-    };
-    const hash = recomputeRecordHash({ ...base, hash: "" });
-    out.push({ ...base, hash });
-    prevHash = hash;
-  });
-  return out;
-}
-
-function source(records: ReadonlyArray<AuditRecord>): AuditRecordSource {
-  return {
-    async *read() {
-      for (const r of records) yield r;
-    },
-  };
-}
-
-describe("Built-in framework definitions", () => {
-  test("SOC2 controls cover CC6.x + CC7.x families", () => {
-    const ids = SOC2_CONTROLS.map((c) => c.controlId);
-    expect(ids).toContain("CC6.1");
-    expect(ids).toContain("CC6.7");
-    expect(ids).toContain("CC7.2");
-    expect(ids).toContain("CC7.3");
-  });
-
-  test("ISO27001 covers A.12.4", () => {
-    const ids = ISO27001_CONTROLS.map((c) => c.controlId);
-    expect(ids).toContain("A.12.4");
-  });
-
-  test("HIPAA covers 164.312(b)", () => {
-    const ids = HIPAA_CONTROLS.map((c) => c.controlId);
-    expect(ids).toContain("164.312(b)");
-  });
-
-  test("BUILT_IN_CONTROLS aggregates all frameworks", () => {
-    const frameworks = new Set(BUILT_IN_CONTROLS.map((c) => c.frameworkId));
-    expect(frameworks.has("soc2")).toBe(true);
-    expect(frameworks.has("iso27001")).toBe(true);
-    expect(frameworks.has("hipaa")).toBe(true);
-  });
-});
-
-describe("Match logic (T1)", () => {
-  test("kind filter", () => {
-    const r = makeRecord({ kind: "policy_decision", payload: {} });
-    expect(_matchesForTest(r, { kind: "policy_decision" })).toBe(true);
-    expect(_matchesForTest(r, { kind: "model_call" })).toBe(false);
-  });
-
-  test("ts range filters (inclusive lower, exclusive upper)", () => {
-    const r = makeRecord({ kind: "policy_decision", payload: {}, ts: 1000 });
-    expect(_matchesForTest(r, { kind: "policy_decision", tsAfter: 999 })).toBe(true);
-    expect(_matchesForTest(r, { kind: "policy_decision", tsAfter: 1000 })).toBe(true);
-    expect(_matchesForTest(r, { kind: "policy_decision", tsAfter: 1001 })).toBe(false);
-    expect(_matchesForTest(r, { kind: "policy_decision", tsBefore: 1001 })).toBe(true);
-    expect(_matchesForTest(r, { kind: "policy_decision", tsBefore: 1000 })).toBe(false);
-  });
-
-  test("payloadField filter", () => {
-    const r = makeRecord({
-      kind: "policy_decision",
-      payload: { action: "allow", risk: 0.1 },
-    });
-    expect(_matchesForTest(r, { kind: "policy_decision", payloadField: "action" })).toBe(true);
-    expect(_matchesForTest(r, { kind: "policy_decision", payloadField: "missing" })).toBe(false);
-  });
-
-  test("payloadFieldEquals filter", () => {
-    const r = makeRecord({
-      kind: "policy_decision",
-      payload: { action: "allow" },
-    });
-    expect(
-      _matchesForTest(r, {
-        kind: "policy_decision",
-        payloadField: "action",
-        payloadFieldEquals: "allow",
-      }),
-    ).toBe(true);
-    expect(
-      _matchesForTest(r, {
-        kind: "policy_decision",
-        payloadField: "action",
-        payloadFieldEquals: "deny",
-      }),
-    ).toBe(false);
-  });
-
-  test("matchesAny is OR-merged", () => {
-    const r = makeRecord({ kind: "policy_decision", payload: {} });
-    const queries = [{ kind: "model_call" as const }, { kind: "policy_decision" as const }];
-    expect(_matchesAnyForTest(r, queries)).toBe(true);
-  });
-
-  test("matchesAny returns false for empty queries", () => {
-    const r = makeRecord({ kind: "policy_decision", payload: {} });
-    expect(_matchesAnyForTest(r, [])).toBe(false);
-  });
-
-  test("payloadField does not match inherited Object.prototype keys", () => {
-    // Regression: `in` would walk the prototype chain so a filter targeting
-    // "toString" / "constructor" spuriously matched every object payload.
-    // payloadField is documented as a *top-level* (own) field.
-    const r = makeRecord({ kind: "policy_decision", payload: { action: "allow" } });
-    expect(_matchesForTest(r, { kind: "policy_decision", payloadField: "toString" })).toBe(false);
-    expect(_matchesForTest(r, { kind: "policy_decision", payloadField: "constructor" })).toBe(
-      false,
-    );
-    expect(_matchesForTest(r, { kind: "policy_decision", payloadField: "hasOwnProperty" })).toBe(
-      false,
-    );
-    // An own field by the same name still matches.
-    const r2 = makeRecord({
-      kind: "policy_decision",
-      payload: Object.assign(Object.create(null), { toString: "shadowed" }),
-    });
-    expect(_matchesForTest(r2, { kind: "policy_decision", payloadField: "toString" })).toBe(true);
-  });
-});
-
-describe("Digest + signature helpers (T1)", () => {
-  test("canonicalDigest is deterministic", () => {
-    const r1 = makeRecord({ kind: "policy_decision", payload: {}, hash: "h1" });
-    const r2 = makeRecord({ kind: "policy_decision", payload: {}, hash: "h2" });
-    expect(_canonicalDigestForTest([r1, r2])).toBe(_canonicalDigestForTest([r1, r2]));
-    expect(_canonicalDigestForTest([r1, r2])).not.toBe(_canonicalDigestForTest([r2, r1]));
-  });
-
-  test("signDigest produces a stable HMAC-SHA256", () => {
-    expect(_signDigestForTest("abc", "k1")).toBe(_signDigestForTest("abc", "k1"));
-    expect(_signDigestForTest("abc", "k1")).not.toBe(_signDigestForTest("abc", "k2"));
-  });
-});
-
-describe("createComplianceCollector (T1 + T3)", () => {
-  test("requires auditSource", () => {
-    expect(() =>
-      createComplianceCollector({ auditSource: undefined as unknown as AuditRecordSource }),
-    ).toThrow(ComplianceControlsError);
-  });
-
-  test("listControls returns built-ins by default, sorted", () => {
-    const collector = createComplianceCollector({ auditSource: source([]) });
-    const list = collector.listControls();
-    expect(list.length).toBe(BUILT_IN_CONTROLS.length);
-    // Sorted by framework first, then control.
-    const frameworks = list.map((c) => c.frameworkId);
-    expect([...frameworks].sort()).toEqual(frameworks);
-  });
-
-  test("listControls with frameworkId filter narrows the result", () => {
-    const collector = createComplianceCollector({ auditSource: source([]) });
-    const soc2 = collector.listControls({ frameworkId: "soc2" });
-    expect(soc2.every((c) => c.frameworkId === "soc2")).toBe(true);
-    expect(soc2.length).toBe(SOC2_CONTROLS.length);
-  });
-
-  test("registerControl adds custom controls", () => {
-    const collector = createComplianceCollector({ auditSource: source([]) });
-    collector.registerControl({
-      frameworkId: "internal",
-      controlId: "X-1",
-      description: "internal control",
-      evidenceQueries: [{ kind: "policy_decision" }],
-    });
-    expect(collector.listControls({ frameworkId: "internal" })).toHaveLength(1);
-  });
-
-  test("collect builds evidence bundle for a single control", async () => {
-    const records = chainOf([
-      { kind: "policy_decision", payload: { action: "allow" } },
-      { kind: "model_call", payload: { model: "claude" } },
-      { kind: "policy_decision", payload: { action: "deny" } },
-    ]);
-    const collector = createComplianceCollector({ auditSource: source(records) });
-    const bundle = await collector.collect("soc2", "CC6.1", { period: "2026-Q2" });
-    expect(bundle.frameworkId).toBe("soc2");
-    expect(bundle.controlId).toBe("CC6.1");
-    expect(bundle.recordCount).toBe(2);
-    expect(bundle.records.map((r) => (r.payload as { action: string }).action)).toEqual([
-      "allow",
-      "deny",
-    ]);
-    expect(bundle.signature).toBeNull();
-    expect(bundle.digest).toMatch(/^[a-f0-9]{64}$/);
-  });
-
-  test("collect with signingKey produces a non-null HMAC signature", async () => {
-    const records = chainOf([{ kind: "policy_decision", payload: {} }]);
-    const collector = createComplianceCollector({ auditSource: source(records) });
-    const bundle = await collector.collect("soc2", "CC6.1", {
-      period: "2026-Q2",
-      signingKey: "k1",
-    });
-    expect(bundle.signature).toMatch(/^[a-f0-9]{64}$/);
-    expect(bundle.signature).toBe(_signDigestForTest(bundle.digest, "k1"));
-  });
-
-  test("collect with unknown control throws", async () => {
-    const collector = createComplianceCollector({ auditSource: source([]) });
-    await expect(collector.collect("ghost", "X", { period: "2026-Q2" })).rejects.toThrow(
-      /not registered/,
-    );
-  });
-
-  test("collectAll returns one bundle per control in the framework", async () => {
-    const records = chainOf([
-      { kind: "policy_decision", payload: {} },
-      { kind: "secrets_rotation", payload: {} },
-    ]);
-    const collector = createComplianceCollector({ auditSource: source(records) });
-    const bundles = await collector.collectAll("soc2", { period: "2026-Q2" });
-    expect(bundles.length).toBe(SOC2_CONTROLS.length);
-    expect(bundles.every((b) => b.frameworkId === "soc2")).toBe(true);
-  });
-
-  // SECURITY: the collector must NOT sign tampered or incomplete evidence.
-  test("collect rejects a record whose payload was rewritten (hash no longer matches)", async () => {
-    const [original] = chainOf([{ kind: "policy_decision", payload: { action: "deny" } }]);
-    if (original === undefined) throw new Error("fixture");
-    // Attacker flips deny→allow but leaves the stored hash untouched.
-    const tampered: AuditRecord = { ...original, payload: { action: "allow" } };
-    const collector = createComplianceCollector({ auditSource: source([tampered]) });
-    await expect(collector.collect("soc2", "CC6.1", { period: "2026-Q2" })).rejects.toThrow(
-      /hash integrity/,
-    );
-  });
-
-  test("collect rejects a chain with a deleted middle record (seq gap)", async () => {
-    const [first, , third] = chainOf([
-      { kind: "policy_decision", payload: { action: "deny" } },
-      { kind: "policy_decision", payload: { action: "deny" } },
-      { kind: "policy_decision", payload: { action: "allow" } },
-    ]);
-    if (first === undefined || third === undefined) throw new Error("fixture");
-    // Drop the middle record — the survivors no longer link / are gapless.
-    const collector = createComplianceCollector({ auditSource: source([first, third]) });
-    await expect(collector.collect("soc2", "CC6.1", { period: "2026-Q2" })).rejects.toThrow(
-      /chain (broken|has a seq gap)/,
-    );
-  });
-});
-
-describe("verifyBundle (evidence integrity)", () => {
-  test("accepts a freshly collected + signed bundle", async () => {
-    const records = chainOf([{ kind: "policy_decision", payload: { action: "deny" } }]);
-    const collector = createComplianceCollector({ auditSource: source(records) });
-    const bundle = await collector.collect("soc2", "CC6.1", {
-      period: "2026-Q2",
-      signingKey: "k1",
-    });
-    expect(verifyBundle(bundle, "k1")).toEqual({ ok: true });
-    expect(verifyBundle(bundle)).toEqual({ ok: true });
-  });
-
-  test("rejects a bundle whose record payload was rewritten after signing", async () => {
-    const records = chainOf([{ kind: "policy_decision", payload: { action: "deny" } }]);
-    const collector = createComplianceCollector({ auditSource: source(records) });
-    const bundle = await collector.collect("soc2", "CC6.1", {
-      period: "2026-Q2",
-      signingKey: "k1",
-    });
-    // Rewrite a payload in the written bundle, leaving digest + signature as-is.
-    const [rec0] = bundle.records;
-    if (rec0 === undefined) throw new Error("fixture");
-    const forged = { ...bundle, records: [{ ...rec0, payload: { action: "allow" } }] };
-    const result = verifyBundle(forged, "k1");
-    expect(result.ok).toBe(false);
-  });
-
-  test("rejects a wrong HMAC key", async () => {
-    const records = chainOf([{ kind: "policy_decision", payload: {} }]);
-    const collector = createComplianceCollector({ auditSource: source(records) });
-    const bundle = await collector.collect("soc2", "CC6.1", {
-      period: "2026-Q2",
-      signingKey: "k1",
-    });
-    const result = verifyBundle(bundle, "wrong-key");
-    expect(result.ok).toBe(false);
-  });
-});
-
-describe("writeBundle (T3 — disk persistence)", () => {
-  let tmp: string;
-  beforeEach(() => {
-    tmp = mkdtempSync(join(tmpdir(), "compliance-controls-test-"));
-  });
-  afterEach(() => {
-    rmSync(tmp, { recursive: true, force: true });
-  });
-
-  test("writes bundle to <outputDir>/<framework>/<control>/<period>.json", async () => {
-    const records = chainOf([{ kind: "policy_decision", payload: {} }]);
-    const collector = createComplianceCollector({
-      auditSource: source(records),
-      outputDir: tmp,
-    });
-    const bundle = await collector.collect("soc2", "CC6.1", { period: "2026-Q2" });
-    const path = collector.writeBundle(bundle);
-    expect(path).toBe(join(tmp, "soc2", "CC6.1", "2026-Q2.json"));
-    expect(existsSync(path)).toBe(true);
-    const content = JSON.parse(readFileSync(path, "utf8"));
-    expect(content.recordCount).toBe(1);
-    expect(content.digest).toBe(bundle.digest);
-  });
-
-  test("writeBundle refuses path-traversal in framework/control id", () => {
-    const collector = createComplianceCollector({
-      auditSource: source([]),
-      outputDir: tmp,
-    });
-    const bundle = {
-      frameworkId: "../etc",
-      controlId: "passwd",
-      description: "x",
-      period: "2026",
-      generatedAt: 1,
-      recordCount: 0,
-      records: [],
-      digest: "x",
-      signature: null,
-    };
-    expect(() => collector.writeBundle(bundle)).toThrow(/may not contain/);
-  });
-
-  test("writeBundle refuses path-traversal in the period label", () => {
-    // Regression: `period` was previously interpolated into the path with no
-    // validation, so a "../../.." period escaped outputDir entirely and wrote
-    // the bundle to an arbitrary location on disk.
-    const collector = createComplianceCollector({
-      auditSource: source([]),
-      outputDir: tmp,
-    });
-    const base = {
-      frameworkId: "soc2",
-      controlId: "CC6.1",
-      description: "x",
-      generatedAt: 1,
-      recordCount: 0,
-      records: [],
-      digest: "x",
-      signature: null,
-    };
-    const escapeTarget = join(tmp, "..", "pwned");
-    expect(() => collector.writeBundle({ ...base, period: "../../../../pwned" })).toThrow(
-      /period may not contain/,
-    );
-    // Absolute-path period is likewise rejected (contains a separator).
-    expect(() => collector.writeBundle({ ...base, period: "/etc/passwd" })).toThrow(
-      /period may not contain/,
-    );
-    // Backslash separator (Windows-style) is rejected too.
-    expect(() => collector.writeBundle({ ...base, period: "..\\win" })).toThrow(
-      /period may not contain/,
-    );
-    // The traversal target must never have been created.
-    expect(existsSync(`${escapeTarget}.json`)).toBe(false);
-  });
-
-  test("writeBundle rejects backslash / dot-segment in framework and control ids", () => {
-    const collector = createComplianceCollector({
-      auditSource: source([]),
-      outputDir: tmp,
-    });
-    const base = {
-      description: "x",
-      period: "2026",
-      generatedAt: 1,
-      recordCount: 0,
-      records: [],
-      digest: "x",
-      signature: null,
-    };
-    expect(() =>
-      collector.writeBundle({ ...base, frameworkId: "..\\evil", controlId: "c" }),
-    ).toThrow(/frameworkId may not contain/);
-    expect(() => collector.writeBundle({ ...base, frameworkId: "soc2", controlId: ".." })).toThrow(
-      /controlId may not contain/,
-    );
-  });
-
-  test("writeBundle still writes a legitimately-labelled period", async () => {
-    const records = chainOf([{ kind: "policy_decision", payload: {} }]);
-    const collector = createComplianceCollector({
-      auditSource: source(records),
-      outputDir: tmp,
-    });
-    const bundle = await collector.collect("soc2", "CC6.1", { period: "2026-Q2" });
-    const path = collector.writeBundle(bundle);
-    expect(existsSync(path)).toBe(true);
-    expect(path).toBe(join(tmp, "soc2", "CC6.1", "2026-Q2.json"));
-  });
-});

package/src/index.ts

@@ -1,424 +0,0 @@
-import { createHash, createHmac, timingSafeEqual } from "node:crypto";
-import { mkdirSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { type AuditKind, type AuditRecord, recomputeRecordHash } from "@crewhaus/audit-log";
-import { CrewhausError } from "@crewhaus/errors";
-
-/**
- * Catalog R17 `compliance-controls` — Section 39 SOC 2 / ISO 27001 /
- * HIPAA evidence collection.
- *
- * A `ControlDefinition` declares which audit-log records prove a
- * given control is operating. The collector walks the audit log per
- * control, gathers matching records into an `EvidenceBundle`, signs
- * the bundle with HMAC-SHA256, and writes it to
- *   `.crewhaus/compliance/<framework>/<controlId>/<period>.json`.
- *
- * Built-in framework definitions (SOC 2 Type II CC6.x + CC7.x, ISO
- * 27001 A.12.4, HIPAA §164.312(b)) are exported at module load so
- * callers don't have to author the filter shapes themselves.
- *
- * Layer R17. Pairs with `audit-log` (R-infra — primary record source),
- * `data-retention-engine` (§39 — adds an audit window so the records
- * referenced by an in-progress evidence collection are not purged
- * mid-run).
- */
-
-export class ComplianceControlsError extends CrewhausError {
-  override readonly name = "ComplianceControlsError";
-  constructor(message: string, cause?: unknown) {
-    super("config", message, cause);
-  }
-}
-
-export type AuditEventFilter = {
-  /** Match the audit record's `kind` field. */
-  readonly kind?: AuditKind;
-  /** Match a specific top-level field within `payload`. */
-  readonly payloadField?: string;
-  /** Substring match on a serialized payload field — e.g. action="rotate". */
-  readonly payloadFieldEquals?: string;
-  /** Inclusive lower bound on `ts`. */
-  readonly tsAfter?: number;
-  /** Exclusive upper bound on `ts`. */
-  readonly tsBefore?: number;
-};
-
-export type ControlDefinition = {
-  readonly frameworkId: string;
-  readonly controlId: string;
-  /** Short description shown in the evidence bundle for auditors. */
-  readonly description: string;
-  /** OR-merged: a record matching any filter is evidence for this control. */
-  readonly evidenceQueries: ReadonlyArray<AuditEventFilter>;
-};
-
-export type EvidenceBundle = {
-  readonly frameworkId: string;
-  readonly controlId: string;
-  readonly description: string;
-  readonly period: string;
-  readonly generatedAt: number;
-  readonly recordCount: number;
-  readonly records: ReadonlyArray<AuditRecord>;
-  /** Hex SHA-256 of the canonical record list, with HMAC signature when keyed. */
-  readonly digest: string;
-  readonly signature: string | null;
-};
-
-export interface AuditRecordSource {
-  /** Yield every record across all days. */
-  read(): AsyncIterable<AuditRecord>;
-}
-
-export type CollectOptions = {
-  /** Period label (e.g. "2026-Q2"). Used in the output path. */
-  readonly period: string;
-  /** Optional HMAC key for signing the bundle. */
-  readonly signingKey?: string;
-  /** Optional clock for tests. */
-  readonly now?: () => number;
-};
-
-export type CollectorOptions = {
-  readonly auditSource: AuditRecordSource;
-  readonly outputDir?: string;
-  readonly controls?: ReadonlyArray<ControlDefinition>;
-};
-
-export interface ComplianceCollector {
-  registerControl(def: ControlDefinition): void;
-  listControls(filter?: { frameworkId?: string }): ReadonlyArray<ControlDefinition>;
-  collect(framework: string, controlId: string, opts: CollectOptions): Promise<EvidenceBundle>;
-  collectAll(framework: string, opts: CollectOptions): Promise<ReadonlyArray<EvidenceBundle>>;
-  /** Test seam — write the bundle to disk under the configured outputDir. */
-  writeBundle(bundle: EvidenceBundle): string;
-}
-
-// --------------------------------------------------------------------
-// Built-in framework definitions
-// --------------------------------------------------------------------
-
-export const SOC2_CONTROLS: ReadonlyArray<ControlDefinition> = [
-  {
-    frameworkId: "soc2",
-    controlId: "CC6.1",
-    description: "Logical and physical access controls — every policy decision is audit-logged.",
-    evidenceQueries: [{ kind: "policy_decision" }],
-  },
-  {
-    frameworkId: "soc2",
-    controlId: "CC6.7",
-    description:
-      "Restricted access to system functions — secrets-manager rotation + access events captured.",
-    evidenceQueries: [{ kind: "secrets_rotation" }, { kind: "secrets_access" }],
-  },
-  {
-    frameworkId: "soc2",
-    controlId: "CC7.2",
-    description: "System monitoring — model invocations and tool classifications are captured.",
-    evidenceQueries: [{ kind: "model_call" }, { kind: "tool_classification" }],
-  },
-  {
-    frameworkId: "soc2",
-    controlId: "CC7.3",
-    description: "Detection of incidents — gateway requests captured for replay/replay analysis.",
-    evidenceQueries: [{ kind: "gateway_request" }],
-  },
-];
-
-export const ISO27001_CONTROLS: ReadonlyArray<ControlDefinition> = [
-  {
-    frameworkId: "iso27001",
-    controlId: "A.12.4",
-    description:
-      "Logging and monitoring — append-only hash-chained audit trail across every privileged operation.",
-    evidenceQueries: [
-      { kind: "policy_decision" },
-      { kind: "model_call" },
-      { kind: "secrets_rotation" },
-      { kind: "deployment_action" },
-    ],
-  },
-];
-
-export const HIPAA_CONTROLS: ReadonlyArray<ControlDefinition> = [
-  {
-    frameworkId: "hipaa",
-    controlId: "164.312(b)",
-    description:
-      "Audit controls — every access to or decision involving protected data appears in the audit log.",
-    evidenceQueries: [
-      { kind: "policy_decision" },
-      { kind: "secrets_access" },
-      { kind: "tenancy_context" },
-    ],
-  },
-];
-
-export const BUILT_IN_CONTROLS: ReadonlyArray<ControlDefinition> = [
-  ...SOC2_CONTROLS,
-  ...ISO27001_CONTROLS,
-  ...HIPAA_CONTROLS,
-];
-
-// --------------------------------------------------------------------
-// Match logic
-// --------------------------------------------------------------------
-
-function matches(record: AuditRecord, filter: AuditEventFilter): boolean {
-  if (filter.kind !== undefined && record.kind !== filter.kind) return false;
-  if (filter.tsAfter !== undefined && record.ts < filter.tsAfter) return false;
-  if (filter.tsBefore !== undefined && record.ts >= filter.tsBefore) return false;
-  if (filter.payloadField !== undefined) {
-    const payload = record.payload as Record<string, unknown> | null;
-    if (payload === null || typeof payload !== "object") return false;
-    // Own-property check only: a filter targets a "top-level field within
-    // payload" (see AuditEventFilter.payloadField). The `in` operator would
-    // also walk the prototype chain, so e.g. `payloadField: "toString"` or
-    // "constructor" would spuriously match every object payload.
-    if (!Object.hasOwn(payload, filter.payloadField)) return false;
-    if (filter.payloadFieldEquals !== undefined) {
-      const value = payload[filter.payloadField];
-      if (typeof value === "string") {
-        if (value !== filter.payloadFieldEquals) return false;
-      } else if (String(value) !== filter.payloadFieldEquals) {
-        return false;
-      }
-    }
-  }
-  return true;
-}
-
-function matchesAny(record: AuditRecord, queries: ReadonlyArray<AuditEventFilter>): boolean {
-  if (queries.length === 0) return false;
-  for (const q of queries) {
-    if (matches(record, q)) return true;
-  }
-  return false;
-}
-
-/** Canonical serialization of a record — the bytes the digest must commit to. */
-function canonicalRecord(r: AuditRecord): string {
-  return JSON.stringify({
-    ts: r.ts,
-    version: r.version,
-    kind: r.kind,
-    seq: r.seq,
-    payload: r.payload,
-    prevHash: r.prevHash,
-    hash: r.hash,
-  });
-}
-
-function canonicalDigest(records: ReadonlyArray<AuditRecord>): string {
-  // Commit to the FULL record (the payload/kind/ts the auditor actually reads),
-  // not just `r.hash`. Hashing only `r.hash` let an attacker rewrite a written
-  // bundle's payload while leaving its hash field untouched, so digest + HMAC
-  // still validated against content that no longer matched.
-  const text = records.map(canonicalRecord).join("\n");
-  return createHash("sha256").update(text).digest("hex");
-}
-
-function signDigest(digest: string, key: string): string {
-  return createHmac("sha256", key).update(digest).digest("hex");
-}
-
-function constantTimeEqualHex(a: string, b: string): boolean {
-  const ab = Buffer.from(a, "utf8");
-  const bb = Buffer.from(b, "utf8");
-  if (ab.length !== bb.length) return false;
-  return timingSafeEqual(ab, bb);
-}
-
-export type BundleVerification =
-  | { readonly ok: true }
-  | { readonly ok: false; readonly reason: string };
-
-/**
- * Re-verify an EvidenceBundle on read. Recomputes the digest over the bundle's
- * records (so a post-signing payload rewrite is detected), re-checks each
- * record's body↔hash consistency, and — when a signing key is supplied —
- * re-derives the HMAC and compares it in constant time. Bundles MUST be
- * verified with this before being trusted as authoritative evidence.
- */
-export function verifyBundle(bundle: EvidenceBundle, signingKey?: string): BundleVerification {
-  if (!constantTimeEqualHex(canonicalDigest(bundle.records), bundle.digest)) {
-    return {
-      ok: false,
-      reason: "digest does not match bundle.records (records altered after signing)",
-    };
-  }
-  for (const r of bundle.records) {
-    if (r.hash !== recomputeRecordHash(r)) {
-      return { ok: false, reason: `record seq ${r.seq} body does not hash to its stored hash` };
-    }
-  }
-  if (signingKey !== undefined) {
-    if (bundle.signature === null) return { ok: false, reason: "bundle is unsigned" };
-    if (!constantTimeEqualHex(signDigest(bundle.digest, signingKey), bundle.signature)) {
-      return { ok: false, reason: "HMAC signature mismatch" };
-    }
-  }
-  return { ok: true };
-}
-
-/**
- * Reject any path component that could escape the output directory. Each of
- * `frameworkId` / `controlId` / `period` becomes one path segment in the
- * evidence-bundle path; a segment containing a path separator (`/` or `\`),
- * a `..` traversal token, or a NUL byte could redirect the write to an
- * arbitrary location on disk. Returns true when the component is unsafe.
- */
-function isUnsafePathComponent(component: string): boolean {
-  return (
-    component.includes("/") ||
-    component.includes("\\") ||
-    component.includes("\0") ||
-    component === ".." ||
-    component === "."
-  );
-}
-
-// --------------------------------------------------------------------
-// Collector
-// --------------------------------------------------------------------
-
-export function createComplianceCollector(opts: CollectorOptions): ComplianceCollector {
-  if (opts.auditSource === undefined) {
-    throw new ComplianceControlsError("auditSource is required");
-  }
-  const outputDir = opts.outputDir ?? join(process.cwd(), ".crewhaus", "compliance");
-  const controls = new Map<string, ControlDefinition>();
-  const seedControls = opts.controls ?? BUILT_IN_CONTROLS;
-  for (const c of seedControls) {
-    controls.set(`${c.frameworkId}::${c.controlId}`, c);
-  }
-
-  function key(framework: string, controlId: string): string {
-    return `${framework}::${controlId}`;
-  }
-
-  return {
-    registerControl(def: ControlDefinition): void {
-      if (typeof def.frameworkId !== "string" || def.frameworkId === "") {
-        throw new ComplianceControlsError("registerControl: frameworkId required");
-      }
-      if (typeof def.controlId !== "string" || def.controlId === "") {
-        throw new ComplianceControlsError("registerControl: controlId required");
-      }
-      controls.set(key(def.frameworkId, def.controlId), def);
-    },
-
-    listControls(filter?: { frameworkId?: string }): ReadonlyArray<ControlDefinition> {
-      const items = [...controls.values()];
-      const filtered =
-        filter?.frameworkId !== undefined
-          ? items.filter((c) => c.frameworkId === filter.frameworkId)
-          : items;
-      return filtered.sort(
-        (a, b) =>
-          a.frameworkId.localeCompare(b.frameworkId) || a.controlId.localeCompare(b.controlId),
-      );
-    },
-
-    async collect(framework, controlId, collectOpts): Promise<EvidenceBundle> {
-      const def = controls.get(key(framework, controlId));
-      if (def === undefined) {
-        throw new ComplianceControlsError(
-          `collect: control "${framework}/${controlId}" not registered`,
-        );
-      }
-      // Verify the audit chain BEFORE accepting records as evidence — the
-      // plain `read()` iterator does no validation, so a record whose payload
-      // was rewritten (without repairing its hash), or a record deleted from
-      // the middle of the chain, would otherwise flow straight into a signed
-      // bundle presented to auditors as authoritative. We re-check every
-      // record's body↔hash, and the link + gapless-seq contiguity of the
-      // sequence `read()` yields, then filter the verified records.
-      const matched: AuditRecord[] = [];
-      let prev: AuditRecord | undefined;
-      for await (const record of opts.auditSource.read()) {
-        if (record.hash !== recomputeRecordHash(record)) {
-          throw new ComplianceControlsError(
-            `collect: audit record at seq ${record.seq} fails hash integrity — its body was modified after signing; refusing to bundle tampered evidence`,
-          );
-        }
-        if (prev !== undefined) {
-          if (record.prevHash !== prev.hash) {
-            throw new ComplianceControlsError(
-              `collect: audit chain broken at seq ${record.seq} — prevHash does not link to the prior record (a record was reordered or removed)`,
-            );
-          }
-          if (record.seq !== prev.seq + 1) {
-            throw new ComplianceControlsError(
-              `collect: audit chain has a seq gap before seq ${record.seq} (expected ${prev.seq + 1}) — a record was removed`,
-            );
-          }
-        }
-        prev = record;
-        if (matchesAny(record, def.evidenceQueries)) {
-          matched.push(record);
-        }
-      }
-      const digest = canonicalDigest(matched);
-      const signature = collectOpts.signingKey ? signDigest(digest, collectOpts.signingKey) : null;
-      const now = collectOpts.now?.() ?? Date.now();
-      return {
-        frameworkId: def.frameworkId,
-        controlId: def.controlId,
-        description: def.description,
-        period: collectOpts.period,
-        generatedAt: now,
-        recordCount: matched.length,
-        records: matched,
-        digest,
-        signature,
-      };
-    },
-
-    async collectAll(framework, collectOpts): Promise<ReadonlyArray<EvidenceBundle>> {
-      const matchingControls = [...controls.values()]
-        .filter((c) => c.frameworkId === framework)
-        .sort((a, b) => a.controlId.localeCompare(b.controlId));
-      if (matchingControls.length === 0) {
-        throw new ComplianceControlsError(
-          `collectAll: no controls registered for framework "${framework}"`,
-        );
-      }
-      const bundles: EvidenceBundle[] = [];
-      for (const c of matchingControls) {
-        bundles.push(await this.collect(c.frameworkId, c.controlId, collectOpts));
-      }
-      return bundles;
-    },
-
-    writeBundle(bundle: EvidenceBundle): string {
-      // All three components are interpolated into the on-disk path; validate
-      // each so a caller-supplied id or period label cannot traverse out of
-      // outputDir (e.g. period "../../etc/cron.d/x" or an absolute path).
-      for (const [field, value] of [
-        ["frameworkId", bundle.frameworkId],
-        ["controlId", bundle.controlId],
-        ["period", bundle.period],
-      ] as const) {
-        if (isUnsafePathComponent(value)) {
-          throw new ComplianceControlsError(
-            `writeBundle: ${field} may not contain a path separator or ".." segment (got "${value}")`,
-          );
-        }
-      }
-      const path = join(outputDir, bundle.frameworkId, bundle.controlId, `${bundle.period}.json`);
-      mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-      writeFileSync(path, `${JSON.stringify(bundle, null, 2)}\n`, { mode: 0o600 });
-      return path;
-    },
-  };
-}
-
-export {
-  matches as _matchesForTest,
-  matchesAny as _matchesAnyForTest,
-  canonicalDigest as _canonicalDigestForTest,
-  signDigest as _signDigestForTest,
-};