@crewhaus/compliance-controls 0.1.0

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@crewhaus/compliance-controls",
+  "version": "0.1.0",
+  "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",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/audit-log": "0.0.0",
+    "@crewhaus/errors": "0.0.0"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@studiomax.io",
+    "url": "https://studiomax.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/compliance-controls"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/compliance-controls#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}

package/src/index.test.ts

@@ -0,0 +1,266 @@
+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 } from "@crewhaus/audit-log";
+import {
+  type AuditRecordSource,
+  BUILT_IN_CONTROLS,
+  ComplianceControlsError,
+  HIPAA_CONTROLS,
+  ISO27001_CONTROLS,
+  SOC2_CONTROLS,
+  _canonicalDigestForTest,
+  _matchesAnyForTest,
+  _matchesForTest,
+  _signDigestForTest,
+  createComplianceCollector,
+} from "./index";
+
+function makeRecord(
+  partial: Pick<AuditRecord, "kind" | "payload"> & Partial<AuditRecord>,
+): AuditRecord {
+  return {
+    ts: partial.ts ?? Date.now(),
+    version: 1,
+    kind: partial.kind,
+    payload: partial.payload,
+    prevHash: partial.prevHash ?? "GENESIS",
+    hash: partial.hash ?? `hash-${Math.random()}`,
+  };
+}
+
+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);
+  });
+});
+
+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: AuditRecord[] = [
+      makeRecord({ kind: "policy_decision", payload: { action: "allow" }, hash: "h1" }),
+      makeRecord({ kind: "model_call", payload: { model: "claude" }, hash: "h2" }),
+      makeRecord({ kind: "policy_decision", payload: { action: "deny" }, hash: "h3" }),
+    ];
+    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.hash)).toEqual(["h1", "h3"]);
+    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: AuditRecord[] = [
+      makeRecord({ kind: "policy_decision", payload: {}, hash: "h1" }),
+    ];
+    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: AuditRecord[] = [
+      makeRecord({ kind: "policy_decision", payload: {}, hash: "h1" }),
+      makeRecord({ kind: "secrets_rotation", payload: {}, hash: "h2" }),
+    ];
+    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);
+  });
+});
+
+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: AuditRecord[] = [
+      makeRecord({ kind: "policy_decision", payload: {}, hash: "h1" }),
+    ];
+    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/);
+  });
+});

package/src/index.ts

@@ -0,0 +1,312 @@
+import { createHash, createHmac } from "node:crypto";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { AuditKind, 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 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;
+    if (!(filter.payloadField in payload)) 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;
+}
+
+function canonicalDigest(records: ReadonlyArray<AuditRecord>): string {
+  const text = records.map((r) => r.hash).join("|");
+  return createHash("sha256").update(text).digest("hex");
+}
+
+function signDigest(digest: string, key: string): string {
+  return createHmac("sha256", key).update(digest).digest("hex");
+}
+
+// --------------------------------------------------------------------
+// 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`,
+        );
+      }
+      const matched: AuditRecord[] = [];
+      for await (const record of opts.auditSource.read()) {
+        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 {
+      if (bundle.frameworkId.includes("/") || bundle.controlId.includes("/")) {
+        throw new ComplianceControlsError(
+          `writeBundle: framework/control id may not contain "/" (got "${bundle.frameworkId}/${bundle.controlId}")`,
+        );
+      }
+      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,
+};