basalt / audit/src / AuditHashChainIntegrity

Interface: AuditHashChainIntegrity

The keyed form of integrity: 'hash-chain'. Every new entry is an HMAC-SHA256 under key, and its hash records keyId (v2:hmac-sha256:<keyId>:<hex>), so rotating the key does not invalidate what the old one signed: move the old key to verifyKeys and verification picks each entry's key by its id.

integrity: {
  mode: 'hash-chain',
  key: process.env.AUDIT_CHAIN_KEY!, keyId: '2026-09',
  verifyKeys: [{ id: '2026-01', key: process.env.AUDIT_CHAIN_KEY_2026_01! }],
}

Properties

key?

> optional key?: AuditIntegrityKey

Defined in: audit/src/index.ts:559

Signs new entries (HMAC-SHA256, >= 128 bits). Omit for a plain SHA-256 chain.

keyId?

> optional keyId?: string

Defined in: audit/src/index.ts:565

The id recorded with every entry key signs (AUDIT_KEY_ID_PATTERN). Default: auditKeyId(key), a fingerprint derived from the key — the same on every replica. Name it yourself to make rotations readable.

mode

> mode: "hash-chain"

Defined in: audit/src/index.ts:557

verifyKeys?

> optional verifyKeys?: (AuditIntegrityKey | AuditSigningKey)[]

Defined in: audit/src/index.ts:572

Retired keys, for verification only — never used to sign. A bare key gets its default id (auditKeyId(key)), which is the id it recorded if it was used without an explicit keyId. Legacy (v1) entries, which record no id, are accepted under any key held here or as key. Requires key.