@crewhaus/compliance-controls 0.1.1 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/compliance-controls",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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",
@@ -12,14 +12,14 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/audit-log": "0.1.1",
-    "@crewhaus/errors": "0.1.1"
+    "@crewhaus/audit-log": "0.1.3",
+    "@crewhaus/errors": "0.1.3"
   },
   "license": "Apache-2.0",
   "author": {
     "name": "Max Meier",
-    "email": "max@studiomax.io",
-    "url": "https://studiomax.io"
+    "email": "max@crewhaus.ai",
+    "url": "https://crewhaus.ai"
   },
   "repository": {
     "type": "git",
@@ -31,12 +31,7 @@
     "url": "https://github.com/crewhaus/factory/issues"
   },
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   },
-  "files": [
-    "src",
-    "README.md",
-    "LICENSE",
-    "NOTICE"
-  ]
+  "files": ["src", "README.md", "LICENSE", "NOTICE"]
 }

package/src/index.test.ts

@@ -2,7 +2,7 @@ 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 AuditRecord, recomputeRecordHash } from "@crewhaus/audit-log";
 import {
   type AuditRecordSource,
   BUILT_IN_CONTROLS,
@@ -15,6 +15,7 @@ import {
   _matchesForTest,
   _signDigestForTest,
   createComplianceCollector,
+  verifyBundle,
 } from "./index";
 
 function makeRecord(
@@ -23,6 +24,7 @@ function makeRecord(
   return {
     ts: partial.ts ?? Date.now(),
     version: 1,
+    seq: partial.seq ?? 0,
     kind: partial.kind,
     payload: partial.payload,
     prevHash: partial.prevHash ?? "GENESIS",
@@ -30,6 +32,28 @@ function makeRecord(
   };
 }
 
+// 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() {
@@ -121,6 +145,26 @@ describe("Match logic (T1)", () => {
     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)", () => {
@@ -172,25 +216,26 @@ describe("createComplianceCollector (T1 + T3)", () => {
   });
 
   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 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.hash)).toEqual(["h1", "h3"]);
+    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: AuditRecord[] = [
-      makeRecord({ kind: "policy_decision", payload: {}, hash: "h1" }),
-    ];
+    const records = chainOf([{ kind: "policy_decision", payload: {} }]);
     const collector = createComplianceCollector({ auditSource: source(records) });
     const bundle = await collector.collect("soc2", "CC6.1", {
       period: "2026-Q2",
@@ -208,15 +253,80 @@ describe("createComplianceCollector (T1 + T3)", () => {
   });
 
   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 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)", () => {
@@ -229,9 +339,7 @@ describe("writeBundle (T3 — disk persistence)", () => {
   });
 
   test("writes bundle to <outputDir>/<framework>/<control>/<period>.json", async () => {
-    const records: AuditRecord[] = [
-      makeRecord({ kind: "policy_decision", payload: {}, hash: "h1" }),
-    ];
+    const records = chainOf([{ kind: "policy_decision", payload: {} }]);
     const collector = createComplianceCollector({
       auditSource: source(records),
       outputDir: tmp,
@@ -263,4 +371,72 @@ describe("writeBundle (T3 — disk persistence)", () => {
     };
     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,7 +1,7 @@
-import { createHash, createHmac } from "node:crypto";
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
 import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import type { AuditKind, AuditRecord } from "@crewhaus/audit-log";
+import { type AuditKind, type AuditRecord, recomputeRecordHash } from "@crewhaus/audit-log";
 import { CrewhausError } from "@crewhaus/errors";
 
 /**
@@ -173,7 +173,11 @@ function matches(record: AuditRecord, filter: AuditEventFilter): boolean {
   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;
+    // 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") {
@@ -194,8 +198,25 @@ function matchesAny(record: AuditRecord, queries: ReadonlyArray<AuditEventFilter
   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 {
-  const text = records.map((r) => r.hash).join("|");
+  // 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");
 }
 
@@ -203,6 +224,62 @@ 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
 // --------------------------------------------------------------------
@@ -252,8 +329,34 @@ export function createComplianceCollector(opts: CollectorOptions): ComplianceCol
           `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);
         }
@@ -291,10 +394,19 @@ export function createComplianceCollector(opts: CollectorOptions): ComplianceCol
     },
 
     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}")`,
-        );
+      // 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 });