feat(audit): scope tamper-evident chains per organization (0.18.0) (#25)

Each organizationId now gets its own HMAC chain head, 1..N sequence, and
write lock; org-less events share one chain (backward-compatible). Binds
organizationId into the per-event hash when present; Postgres adapter now
persists organization_id and uses a per-org unique sequence index.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: scotty595

README.md

@@ -399,6 +399,24 @@ const chain = await gov.integrityChain!.export();
 const { valid, brokenAt, breakDetail } = await verifyAuditIntegrity(chain, process.env.AUDIT_SECRET!);
 ```
 
+**Per-org (multi-tenant) chains.** Since 0.18, chains are scoped per
+`organizationId`: each org gets its own head, its own `1..N` sequence, and
+its own write lock, so one tenant's events never interleave with another's.
+Pass the org on the context (or via `metadata.organizationId`) and export /
+verify a single tenant's contiguous chain:
+
+```typescript
+await gov.enforce({ agentId, organizationId: 'org_acme', action: 'tool_call', tool: 'search' });
+
+const acme = await gov.integrityChain!.export({ organizationId: 'org_acme' });
+await verifyAuditIntegrity(acme, process.env.AUDIT_SECRET!); // contiguous, standalone-verifiable
+```
+
+Events without an `organizationId` share a single org-less chain, byte-for-byte
+compatible with chains written before 0.18 — no migration needed. The org is
+bound into each event's hash (when present), so an event can't be relabelled
+into another tenant's chain without breaking verification.
+
 **What gets chained (when `integrityAudit` is set):**
 
 | Event type | Written by | What it captures |

packages/governance/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## [0.18.0] - 2026-06-26 — Per-org (multi-tenant) audit chains
+
+The tamper-evident audit chain is now scoped **per organization**. Before
+this release a single `createGovernance({ integrityAudit })` instance kept
+one global hash chain, so every org's events were interleaved into the same
+chain and sequence space — you couldn't hand one tenant a clean, contiguous,
+independently-verifiable export, and one tenant's volume affected another's
+chain. Now each `organizationId` gets its own head, its own 1..N sequence,
+and its own write lock; events with no org share a single org-less chain,
+byte-for-byte compatible with chains written before this release.
+
+Additive and backward-compatible — org-less usage is unchanged.
+
+### Added
+
+- `EnforcementContext.organizationId`, `AgentRegistration.organizationId`,
+  `ActionOutcome.organizationId` — supply the tenant to scope its chain.
+  `enforce()` / `enforceStage()` also fall back to `metadata.organizationId`.
+- `integrityChain.stats(organizationId?)` and `integrityChain.export({ organizationId })`
+  now operate on a single org's chain.
+- `GovernanceStorage.getChainHead(organizationId?)` — resume the right org's
+  chain on restart. The in-memory and Postgres adapters implement it.
+
+### Changed
+
+- `canonicalize()` binds `organizationId` into the per-event hash **only when
+  present**, so an event cannot be relabelled into another org's chain without
+  detection. Org-less events hash exactly as before (no migration needed).
+- Postgres adapter now persists `organization_id` on agents and audit events
+  (the columns/indexes already existed but were never written), and the
+  `integrity_sequence` unique index is now per-org
+  (`(COALESCE(organization_id,''), integrity_sequence)`). The integrity
+  migration drops the old global unique index and creates the composite one
+  — idempotent, safe on existing rows.
+
 ## [0.17.0] - 2026-05-07 — Custom conditions reachable from `createGovernance()`
 
 The condition registry (`registerCondition` / `unregisterCondition` /

packages/governance/README.md

@@ -399,6 +399,24 @@ const chain = await gov.integrityChain!.export();
 const { valid, brokenAt, breakDetail } = await verifyAuditIntegrity(chain, process.env.AUDIT_SECRET!);
 ```
 
+**Per-org (multi-tenant) chains.** Since 0.18, chains are scoped per
+`organizationId`: each org gets its own head, its own `1..N` sequence, and
+its own write lock, so one tenant's events never interleave with another's.
+Pass the org on the context (or via `metadata.organizationId`) and export /
+verify a single tenant's contiguous chain:
+
+```typescript
+await gov.enforce({ agentId, organizationId: 'org_acme', action: 'tool_call', tool: 'search' });
+
+const acme = await gov.integrityChain!.export({ organizationId: 'org_acme' });
+await verifyAuditIntegrity(acme, process.env.AUDIT_SECRET!); // contiguous, standalone-verifiable
+```
+
+Events without an `organizationId` share a single org-less chain, byte-for-byte
+compatible with chains written before 0.18 — no migration needed. The org is
+bound into each event's hash (when present), so an event can't be relabelled
+into another tenant's chain without breaking verification.
+
 **What gets chained (when `integrityAudit` is set):**
 
 | Event type | Written by | What it captures |

packages/governance/package.json

@@ -1,6 +1,6 @@
 {
   "name": "governance-sdk",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "AI Agent Governance for TypeScript — policy enforcement, scoring, compliance, and audit for AI agents",
   "type": "module",
   "main": "./dist/index.js",

packages/governance/src/audit-chain-per-org.test.ts

@@ -0,0 +1,112 @@
+/**
+ * Per-org integrity audit chain tests.
+ *
+ * Chains are scoped per organization: each org gets an independent HMAC chain
+ * with its own head and its own 1..N sequence. This means:
+ *   - one org's events never interleave into another org's chain
+ *   - a single org's exported slice is contiguous and verifies standalone
+ *   - relabelling an event into a different org breaks its hash (org is bound
+ *     into the canonical form)
+ *   - events with NO organizationId share one org-less chain, byte-for-byte
+ *     compatible with chains written before per-org scoping existed
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { createGovernance } from "./index";
+import { verifyAuditIntegrity } from "./audit-integrity-verify";
+
+const KEY = "per-org-chain-secret";
+
+describe("integrity chain — per-org scoping", () => {
+  it("gives each org an independent, contiguous, standalone-verifiable chain", async () => {
+    const gov = createGovernance({ integrityAudit: { signingKey: KEY } });
+
+    // 3 events for org A, 2 for org B, interleaved in time.
+    await gov.enforce({ agentId: "a1", organizationId: "orgA", action: "tool_call", tool: "t" });
+    await gov.enforce({ agentId: "b1", organizationId: "orgB", action: "tool_call", tool: "t" });
+    await gov.enforce({ agentId: "a1", organizationId: "orgA", action: "tool_call", tool: "t" });
+    await gov.enforce({ agentId: "b1", organizationId: "orgB", action: "tool_call", tool: "t" });
+    await gov.enforce({ agentId: "a1", organizationId: "orgA", action: "tool_call", tool: "t" });
+
+    const chainA = await gov.integrityChain!.export({ organizationId: "orgA" });
+    const chainB = await gov.integrityChain!.export({ organizationId: "orgB" });
+
+    // Each org's slice carries only its own events, with contiguous sequences.
+    assert.equal(chainA.length, 3);
+    assert.equal(chainB.length, 2);
+    assert.deepEqual(chainA.map((e) => e.integrity.sequence), [1, 2, 3]);
+    assert.deepEqual(chainB.map((e) => e.integrity.sequence), [1, 2]);
+    assert.ok(chainA.every((e) => e.organizationId === "orgA"));
+    assert.ok(chainB.every((e) => e.organizationId === "orgB"));
+
+    // Each slice verifies cleanly on its own.
+    const rA = await verifyAuditIntegrity(chainA, KEY);
+    const rB = await verifyAuditIntegrity(chainB, KEY);
+    assert.equal(rA.valid, true, rA.breakDetail ?? "");
+    assert.equal(rB.valid, true, rB.breakDetail ?? "");
+
+    // Heads are tracked per-org.
+    assert.equal(gov.integrityChain!.stats("orgA").latestSequence, 3);
+    assert.equal(gov.integrityChain!.stats("orgB").latestSequence, 2);
+  });
+
+  it("binds organizationId into the hash — relabelling into another org breaks verification", async () => {
+    const gov = createGovernance({ integrityAudit: { signingKey: KEY } });
+    await gov.enforce({ agentId: "a1", organizationId: "orgA", action: "tool_call", tool: "t" });
+    const [event] = await gov.integrityChain!.export({ organizationId: "orgA" });
+
+    // Untampered verifies.
+    assert.equal((await verifyAuditIntegrity([event], KEY)).valid, true);
+
+    // Move the event into another org without re-signing → hash no longer matches.
+    const moved = { ...event, organizationId: "orgB" };
+    const res = await verifyAuditIntegrity([moved], KEY);
+    assert.equal(res.valid, false);
+  });
+
+  it("resolves org from metadata.organizationId when the field is omitted", async () => {
+    const gov = createGovernance({ integrityAudit: { signingKey: KEY } });
+    await gov.enforce({ agentId: "a1", action: "tool_call", tool: "t", metadata: { organizationId: "orgMeta" } });
+
+    const chain = await gov.integrityChain!.export({ organizationId: "orgMeta" });
+    assert.equal(chain.length, 1);
+    assert.equal(chain[0].organizationId, "orgMeta");
+    assert.equal(gov.integrityChain!.stats("orgMeta").latestSequence, 1);
+  });
+
+  it("keeps the org-less chain independent from org chains", async () => {
+    const gov = createGovernance({ integrityAudit: { signingKey: KEY } });
+    await gov.audit.log({ agentId: "x", eventType: "custom", outcome: "success", severity: "info" });
+    await gov.enforce({ agentId: "a1", organizationId: "orgA", action: "tool_call", tool: "t" });
+    await gov.audit.log({ agentId: "x", eventType: "custom", outcome: "success", severity: "info" });
+
+    // org-less chain has its own contiguous sequence (2), unaffected by orgA.
+    const orgless = await gov.integrityChain!.export({});
+    const orglessOnly = orgless.filter((e) => e.organizationId == null);
+    assert.deepEqual(orglessOnly.map((e) => e.integrity.sequence), [1, 2]);
+    assert.equal(gov.integrityChain!.stats().latestSequence, 2);
+    assert.equal(gov.integrityChain!.stats("orgA").latestSequence, 1);
+  });
+
+  it("register() stamps the org onto the agent record and the agent_registered event", async () => {
+    const gov = createGovernance({ integrityAudit: { signingKey: KEY } });
+    const { id } = await gov.register({ name: "alpha", framework: "mastra", owner: "t", organizationId: "orgA" });
+
+    const stored = await gov.storage.getAgent(id);
+    assert.equal(stored?.organizationId, "orgA");
+
+    const chainA = await gov.integrityChain!.export({ organizationId: "orgA" });
+    assert.equal(chainA.length, 1);
+    assert.equal(chainA[0].eventType, "agent_registered");
+    assert.equal((await verifyAuditIntegrity(chainA, KEY)).valid, true);
+  });
+
+  it("recordOutcome() lands on the agent's org chain", async () => {
+    const gov = createGovernance({ integrityAudit: { signingKey: KEY } });
+    await gov.recordOutcome({ agentId: "a1", organizationId: "orgA", action: "tool_call", success: true });
+    const chainA = await gov.integrityChain!.export({ organizationId: "orgA" });
+    assert.equal(chainA.length, 1);
+    assert.equal(chainA[0].eventType, "action_outcome");
+  });
+});

packages/governance/src/audit-integrity.ts

@@ -111,6 +111,12 @@ export function deepSortKeys(value: unknown): unknown {
 /** Compute the canonical string representation of an audit event for hashing */
 export function canonicalize(event: AuditEvent, previousHash: string, sequence: number): string {
   // Deterministic serialization: ALL keys sorted recursively (including nested detail)
+  //
+  // `organizationId` is bound into the hash ONLY when the event carries one.
+  // This cryptographically scopes per-org chains (an event cannot be relabelled
+  // into another org's chain without breaking its hash) while staying byte-for-byte
+  // backward-compatible with org-less chains written before per-org scoping existed
+  // — omitting the key produces the identical canonical form as before.
   const canonical = deepSortKeys({
     agentId: event.agentId,
     createdAt: event.createdAt,
@@ -122,6 +128,7 @@ export function canonicalize(event: AuditEvent, previousHash: string, sequence:
     previousHash,
     sequence,
     severity: event.severity,
+    ...(event.organizationId != null ? { organizationId: event.organizationId } : {}),
   });
 
   return JSON.stringify(canonical);