@nodii/audit-chain

Tamper-evident audit chain for the Nodii microservice stack — per-tenant SHA-256 hash chain over audit_event rows + pluggable DB + KMS signing client

• verifier helpers.

Spec: https://planning.dev.nucleus-cloud.in/api/v1/feature-docs?serviceId=nodii-libs&docKey=audit-chain

v0.1.0 — foundations

import {
  initAuditChain,
  auditChain,
  InMemoryAuditChainDbClient,
  HmacKmsClient,
  canonicalJson,
  computeChainHash,
  GENESIS_HASH,
} from "@nodii/audit-chain";

initAuditChain({
  db: new InMemoryAuditChainDbClient(),     // swap with Drizzle adapter at v0.1.x
  signingMode: "hmac",
  hmacSecret: process.env.AUDIT_HMAC_SECRET, // KMS adapter at v0.1.x
});

const { row, this_hash, prev_hash, sig } = await auditChain.emit({
  tenant_id: "tnt_123",
  event: { action: "invoice.create", target_id: "inv_1", amount: 100 },
});

const verdict = await auditChain.verify({ tenant_id: "tnt_123" });
if (!verdict.ok) {
  // verdict.brokenAt, .expected, .actual, .reason
}

Public surface

• initAuditChain({ db?, kmsClient?, signingMode?, hmacSecret? }) — bootstrap.
• auditChain.emit({ tenant_id, event }) / auditChain.append({ … }) — appends a tamper-evident row to the chain.
• auditChain.verify({ tenant_id, fromSeq?, toSeq? }) — recomputes the chain in-range and asserts each row's hash matches and sig verifies.
• auditChain.verifyOrThrow(...) — throws ChainBroken on first mismatch.
• canonicalJson(event) — exposed for parity-fence verification.
• computeChainHash({ prev_hash, event }) — exposed for tests.
• Typed errors: AuditChainError + AuditChainNotInitialized + ChainBroken
  • SignatureInvalid + EventNonCanonical.

Deferred to v0.1.x (marked // TODO audit-chain-v0.1.x: in source)

• Real KMS signing (aws-sdk-v3 / boto3 / aws-sdk-go-v2).
• Lambda verifier deployment artifact (spec § 5.5).
• Drizzle / SQLAlchemy / pgx schema migrations for audit_event_chain.
• Range-pagination on verify for very large chains.
• Per-tenant pg_advisory_xact_lock acquisition in the chain-write path.