@centient/secrets 0.9.0 → 0.11.0

package/dist/audit/hmac-chain.js

@@ -0,0 +1,811 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+const HMAC_KEY_BYTES = 32;
+const SHA256_HEX_LENGTH = 64;
+const MAX_CANONICAL_DEPTH = 64;
+const MAX_CANONICAL_BYTES = 1024 * 1024;
+const IDENTIFIER_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const CREDENTIAL_AUDIT_TYPE_UIDS = new Set([300402, 300404, 300499]);
+/** Configuration/state errors produced by the writer side of the chain. */
+export class AuditChainError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "AuditChainError";
+    }
+}
+function isPlainRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function assertWellFormedUnicode(value) {
+    for (let index = 0; index < value.length; index++) {
+        const code = value.charCodeAt(index);
+        if (code >= 0xd800 && code <= 0xdbff) {
+            const next = value.charCodeAt(index + 1);
+            if (!(next >= 0xdc00 && next <= 0xdfff)) {
+                throw new TypeError("JCS input contains an unpaired UTF-16 surrogate");
+            }
+            index++;
+        }
+        else if (code >= 0xdc00 && code <= 0xdfff) {
+            throw new TypeError("JCS input contains an unpaired UTF-16 surrogate");
+        }
+    }
+}
+/**
+ * RFC 8785 JSON Canonicalization Scheme for the JSON data model used by OCSF.
+ *
+ * Objects are plain data objects, names are ordered by UTF-16 code units, and
+ * strings/numbers use ECMAScript JSON serialization. Values outside I-JSON
+ * (cycles, sparse arrays, accessors, non-finite numbers, lone surrogates,
+ * `undefined`, `bigint`, functions, symbols) fail closed.
+ */
+export function canonicalizeAuditEvent(value) {
+    const ancestors = new Set();
+    const visit = (current, depth) => {
+        if (depth > MAX_CANONICAL_DEPTH) {
+            throw new TypeError("JCS input exceeds the maximum nesting depth");
+        }
+        if (current === null)
+            return "null";
+        switch (typeof current) {
+            case "boolean":
+                return current ? "true" : "false";
+            case "number": {
+                if (!Number.isFinite(current)) {
+                    throw new TypeError("JCS input contains a non-finite number");
+                }
+                return JSON.stringify(current);
+            }
+            case "string": {
+                assertWellFormedUnicode(current);
+                return JSON.stringify(current);
+            }
+            case "object":
+                break;
+            default:
+                throw new TypeError(`JCS cannot serialize a ${typeof current} value`);
+        }
+        if (ancestors.has(current)) {
+            throw new TypeError("JCS input contains a cycle");
+        }
+        ancestors.add(current);
+        try {
+            if (Array.isArray(current)) {
+                const items = [];
+                for (let index = 0; index < current.length; index++) {
+                    if (!Object.prototype.hasOwnProperty.call(current, index)) {
+                        throw new TypeError("JCS input contains a sparse array");
+                    }
+                    items.push(visit(current[index], depth + 1));
+                }
+                return `[${items.join(",")}]`;
+            }
+            if (!isPlainRecord(current)) {
+                throw new TypeError("JCS input must contain only plain JSON objects");
+            }
+            if (Object.getOwnPropertySymbols(current).length > 0) {
+                throw new TypeError("JCS input contains a symbol-keyed property");
+            }
+            const descriptors = Object.getOwnPropertyDescriptors(current);
+            const keys = Object.keys(current).sort();
+            const members = [];
+            for (const key of keys) {
+                assertWellFormedUnicode(key);
+                const descriptor = descriptors[key];
+                if (!descriptor || !("value" in descriptor)) {
+                    throw new TypeError("JCS input contains an accessor property");
+                }
+                members.push(`${JSON.stringify(key)}:${visit(descriptor.value, depth + 1)}`);
+            }
+            return `{${members.join(",")}}`;
+        }
+        finally {
+            ancestors.delete(current);
+        }
+    };
+    const canonical = visit(value, 0);
+    if (Buffer.byteLength(canonical, "utf8") > MAX_CANONICAL_BYTES) {
+        throw new TypeError("JCS input exceeds the maximum canonical byte length");
+    }
+    return canonical;
+}
+function assertIdentifier(value, field) {
+    if (typeof value !== "string" || !IDENTIFIER_PATTERN.test(value)) {
+        throw new AuditChainError(field === "chainId" ? "INVALID_CHAIN_ID" : "INVALID_KEY_ID", `${field} must be 1-128 safe ASCII characters`);
+    }
+}
+function copyKey(key) {
+    if (!(key instanceof Uint8Array) || key.byteLength !== HMAC_KEY_BYTES) {
+        throw new AuditChainError("INVALID_KEY", `audit chain key must be exactly ${HMAC_KEY_BYTES} bytes`);
+    }
+    return Buffer.from(key);
+}
+function isSha256Hex(value) {
+    return typeof value === "string" && /^[0-9a-f]{64}$/.test(value);
+}
+function isCredentialAuditTypeUid(value) {
+    return typeof value === "number" && CREDENTIAL_AUDIT_TYPE_UIDS.has(value);
+}
+function makeFingerprint(value) {
+    return {
+        algorithm_id: 99,
+        algorithm: "HMAC-SHA-256",
+        encoding_id: 1,
+        serialization_id: 2,
+        value,
+    };
+}
+function snapshotCheckpoint(checkpoint) {
+    // Read every caller-owned field exactly once, then validate and operate only
+    // on this plain snapshot. Accessor-backed arrays must not change identity
+    // between validation and use.
+    try {
+        const chainId = checkpoint.chainId;
+        const sequenceNumber = checkpoint.sequenceNumber;
+        const eventUid = checkpoint.eventUid;
+        const eventHash = checkpoint.eventHash;
+        const typeUid = checkpoint.typeUid;
+        const keyId = checkpoint.keyId;
+        const rawUsedKeyIds = checkpoint.usedKeyIds;
+        const rawUsedKeyFingerprints = checkpoint.usedKeyFingerprints;
+        if (!Array.isArray(rawUsedKeyIds) || !Array.isArray(rawUsedKeyFingerprints)) {
+            throw new AuditChainError("INVALID_CHECKPOINT", "checkpoint key history must use arrays");
+        }
+        const candidate = {
+            chainId,
+            sequenceNumber,
+            eventUid,
+            eventHash,
+            typeUid,
+            keyId,
+            usedKeyIds: Array.from(rawUsedKeyIds),
+            usedKeyFingerprints: Array.from(rawUsedKeyFingerprints),
+        };
+        validateCheckpoint(candidate);
+        return Object.freeze({
+            ...candidate,
+            usedKeyIds: Object.freeze([...candidate.usedKeyIds]),
+            usedKeyFingerprints: Object.freeze([...candidate.usedKeyFingerprints]),
+        });
+    }
+    catch (error) {
+        if (error instanceof AuditChainError && error.code === "INVALID_CHECKPOINT") {
+            throw error;
+        }
+        throw new AuditChainError("INVALID_CHECKPOINT", "audit chain checkpoint could not be snapshotted");
+    }
+}
+function validateCheckpoint(checkpoint) {
+    try {
+        assertIdentifier(checkpoint.chainId, "chainId");
+        assertIdentifier(checkpoint.keyId, "keyId");
+    }
+    catch (error) {
+        throw new AuditChainError("INVALID_CHECKPOINT", error instanceof Error ? error.message : "checkpoint identifier is invalid");
+    }
+    if (!Number.isSafeInteger(checkpoint.sequenceNumber) ||
+        checkpoint.sequenceNumber < 1 ||
+        typeof checkpoint.eventUid !== "string" ||
+        checkpoint.eventUid.length === 0 ||
+        !isSha256Hex(checkpoint.eventHash) ||
+        !isCredentialAuditTypeUid(checkpoint.typeUid) ||
+        !Array.isArray(checkpoint.usedKeyIds) ||
+        checkpoint.usedKeyIds.length === 0 ||
+        !Array.isArray(checkpoint.usedKeyFingerprints) ||
+        checkpoint.usedKeyFingerprints.length !== checkpoint.usedKeyIds.length) {
+        throw new AuditChainError("INVALID_CHECKPOINT", "audit chain checkpoint is malformed");
+    }
+    const used = new Set();
+    const usedFingerprints = new Set();
+    for (let index = 0; index < checkpoint.usedKeyIds.length; index++) {
+        const keyId = checkpoint.usedKeyIds[index];
+        const keyFingerprint = checkpoint.usedKeyFingerprints[index];
+        try {
+            assertIdentifier(keyId, "keyId");
+        }
+        catch {
+            throw new AuditChainError("INVALID_CHECKPOINT", "checkpoint contains an invalid key ID");
+        }
+        if (used.has(keyId)) {
+            throw new AuditChainError("INVALID_CHECKPOINT", "checkpoint contains duplicate key IDs");
+        }
+        used.add(keyId);
+        if (!isSha256Hex(keyFingerprint) || usedFingerprints.has(keyFingerprint)) {
+            throw new AuditChainError("INVALID_CHECKPOINT", "checkpoint contains an invalid or duplicate key fingerprint");
+        }
+        usedFingerprints.add(keyFingerprint);
+    }
+    if (!used.has(checkpoint.keyId) ||
+        checkpoint.usedKeyIds[checkpoint.usedKeyIds.length - 1] !== checkpoint.keyId) {
+        throw new AuditChainError("INVALID_CHECKPOINT", "checkpoint keyId must be the final used key ID");
+    }
+}
+function deepFreeze(value, seen = new Set()) {
+    if (typeof value !== "object" || value === null || seen.has(value))
+        return value;
+    seen.add(value);
+    for (const child of Object.values(value)) {
+        deepFreeze(child, seen);
+    }
+    return Object.freeze(value);
+}
+function unsignedEventForHash(event) {
+    const attestations = event.attestation_list;
+    if (!Array.isArray(attestations) || attestations.length !== 1) {
+        throw new TypeError("record-integrity event must contain one attestation");
+    }
+    const current = attestations[0];
+    if (!isPlainRecord(current)) {
+        throw new TypeError("record-integrity attestation must be an object");
+    }
+    const { fingerprint: _fingerprint, ...unsignedAttestation } = current;
+    return {
+        ...event,
+        attestation_list: [unsignedAttestation],
+    };
+}
+function hmacSha256(key, canonical) {
+    return createHmac("sha256", key).update(canonical, "utf8").digest();
+}
+function hmacHex(key, canonical) {
+    return hmacSha256(key, canonical).toString("hex");
+}
+function keyMaterialFingerprint(chainId, key) {
+    return createHmac("sha256", key)
+        .update("centient.audit-chain/key-fingerprint/v1\0", "utf8")
+        .update(chainId, "utf8")
+        .digest("hex");
+}
+function buildUnsignedEvent(event, chainId, keyId, sequenceNumber, previous) {
+    if (event.attestation_list !== undefined || event.metadata.sequence !== undefined) {
+        throw new AuditChainError("EVENT_ALREADY_CHAINED", "audit chain append expects an event without record-integrity state");
+    }
+    return {
+        ...event,
+        metadata: {
+            ...event.metadata,
+            sequence: sequenceNumber,
+            profiles: ["record_integrity"],
+        },
+        unmapped: {
+            ...event.unmapped,
+            "centient.audit_chain.key_id": keyId,
+        },
+        attestation_list: [
+            {
+                chain_uid: chainId,
+                ...(previous
+                    ? {
+                        prev_event: {
+                            uid: previous.eventUid,
+                            type_uid: previous.typeUid,
+                            fingerprint: makeFingerprint(previous.eventHash),
+                        },
+                    }
+                    : {}),
+            },
+        ],
+    };
+}
+/** Create one synchronous, process-local HMAC-SHA-256 audit chain. */
+export function createHmacAuditChain(options) {
+    // Snapshot caller-owned options once. Re-reading a mutable object or getter
+    // after validation could otherwise change the identity of a live chain.
+    const chainId = options.chainId;
+    const initialKeyId = options.keyId;
+    const initialKey = options.key;
+    const checkpoint = options.checkpoint;
+    assertIdentifier(chainId, "chainId");
+    assertIdentifier(initialKeyId, "keyId");
+    let key = copyKey(initialKey);
+    let keyId = initialKeyId;
+    let keyFingerprint = keyMaterialFingerprint(chainId, key);
+    let destroyed = false;
+    let state = null;
+    // `seen*` also reserve keys selected by rotate() before they emit an event.
+    // The aligned `emitted*` arrays are the durable subset in checkpoints.
+    const seenKeyIds = new Set();
+    const seenKeyFingerprints = new Set();
+    const emittedKeyIds = [];
+    const emittedKeyFingerprints = [];
+    if (checkpoint !== undefined) {
+        try {
+            const trustedCheckpoint = snapshotCheckpoint(checkpoint);
+            if (trustedCheckpoint.chainId !== chainId) {
+                throw new AuditChainError("CHAIN_ID_MISMATCH", "checkpoint chainId does not match the configured chainId");
+            }
+            for (let index = 0; index < trustedCheckpoint.usedKeyIds.length; index++) {
+                const usedKeyId = trustedCheckpoint.usedKeyIds[index];
+                const usedKeyFingerprint = trustedCheckpoint.usedKeyFingerprints[index];
+                seenKeyIds.add(usedKeyId);
+                seenKeyFingerprints.add(usedKeyFingerprint);
+                emittedKeyIds.push(usedKeyId);
+                emittedKeyFingerprints.push(usedKeyFingerprint);
+            }
+            if (seenKeyIds.has(keyId) && keyId !== trustedCheckpoint.keyId) {
+                throw new AuditChainError("KEY_ID_REUSE", "a resumed chain cannot reuse an earlier key ID");
+            }
+            const checkpointKeyFingerprint = trustedCheckpoint.usedKeyFingerprints.at(-1);
+            if (keyId === trustedCheckpoint.keyId &&
+                keyFingerprint !== checkpointKeyFingerprint) {
+                throw new AuditChainError("CHECKPOINT_KEY_MISMATCH", "the configured key does not match the checkpoint's current key ID");
+            }
+            if (keyId !== trustedCheckpoint.keyId &&
+                seenKeyFingerprints.has(keyFingerprint)) {
+                throw new AuditChainError("KEY_MATERIAL_REUSE", "a resumed chain cannot reuse historical key material under a fresh ID");
+            }
+            seenKeyIds.add(keyId);
+            seenKeyFingerprints.add(keyFingerprint);
+            state = {
+                sequenceNumber: trustedCheckpoint.sequenceNumber,
+                eventUid: trustedCheckpoint.eventUid,
+                eventHash: trustedCheckpoint.eventHash,
+                typeUid: trustedCheckpoint.typeUid,
+                keyId: trustedCheckpoint.keyId,
+            };
+        }
+        catch (error) {
+            key.fill(0);
+            throw error;
+        }
+    }
+    else {
+        seenKeyIds.add(keyId);
+        seenKeyFingerprints.add(keyFingerprint);
+    }
+    const assertOpen = () => {
+        if (destroyed) {
+            throw new AuditChainError("CHAIN_DESTROYED", "audit chain has been destroyed");
+        }
+    };
+    return {
+        append(event) {
+            assertOpen();
+            const sequenceNumber = (state?.sequenceNumber ?? 0) + 1;
+            if (!Number.isSafeInteger(sequenceNumber)) {
+                throw new AuditChainError("SEQUENCE_EXHAUSTED", "audit chain sequence exhausted the safe integer range");
+            }
+            const unsignedCandidate = buildUnsignedEvent(event, chainId, keyId, sequenceNumber, state);
+            let canonical;
+            let unsignedClone;
+            try {
+                canonical = canonicalizeAuditEvent(unsignedCandidate);
+                unsignedClone = JSON.parse(canonical);
+            }
+            catch (error) {
+                throw new AuditChainError("CANONICALIZATION_FAILED", error instanceof Error ? error.message : "audit event canonicalization failed");
+            }
+            const eventHash = hmacHex(key, canonical);
+            const unsignedAttestation = unsignedClone.attestation_list[0];
+            const signed = {
+                ...unsignedClone,
+                attestation_list: [
+                    {
+                        ...unsignedAttestation,
+                        fingerprint: makeFingerprint(eventHash),
+                    },
+                ],
+            };
+            // Commit state before handing the immutable record to a caller/sink. A
+            // later sink failure must leave an observable sequence gap, not roll the
+            // chain back and silently erase the missing record.
+            state = {
+                sequenceNumber,
+                eventUid: signed.metadata.uid,
+                eventHash,
+                typeUid: signed.type_uid,
+                keyId,
+            };
+            if (emittedKeyIds[emittedKeyIds.length - 1] !== keyId) {
+                emittedKeyIds.push(keyId);
+                emittedKeyFingerprints.push(keyFingerprint);
+            }
+            return deepFreeze(signed);
+        },
+        rotate(next) {
+            assertOpen();
+            const nextKeyId = next.keyId;
+            const nextKeyInput = next.key;
+            assertIdentifier(nextKeyId, "keyId");
+            if (seenKeyIds.has(nextKeyId)) {
+                throw new AuditChainError("KEY_ID_REUSE", "audit chain key IDs cannot be reused");
+            }
+            const nextKey = copyKey(nextKeyInput);
+            const nextKeyFingerprint = keyMaterialFingerprint(chainId, nextKey);
+            if (seenKeyFingerprints.has(nextKeyFingerprint)) {
+                nextKey.fill(0);
+                throw new AuditChainError("KEY_MATERIAL_REUSE", "audit chain key material cannot be reused");
+            }
+            key.fill(0);
+            key = nextKey;
+            keyId = nextKeyId;
+            keyFingerprint = nextKeyFingerprint;
+            seenKeyIds.add(keyId);
+            seenKeyFingerprints.add(keyFingerprint);
+        },
+        checkpoint() {
+            assertOpen();
+            if (!state)
+                return null;
+            return snapshotCheckpoint({
+                chainId,
+                sequenceNumber: state.sequenceNumber,
+                eventUid: state.eventUid,
+                eventHash: state.eventHash,
+                typeUid: state.typeUid,
+                keyId: state.keyId,
+                usedKeyIds: [...emittedKeyIds],
+                usedKeyFingerprints: [...emittedKeyFingerprints],
+            });
+        },
+        destroy() {
+            if (destroyed)
+                return;
+            key.fill(0);
+            destroyed = true;
+        },
+    };
+}
+function verificationFailure(code, message, index, sequenceNumber) {
+    return {
+        ok: false,
+        error: {
+            code,
+            message,
+            index,
+            ...(sequenceNumber !== undefined ? { sequenceNumber } : {}),
+        },
+    };
+}
+function parseFingerprint(value) {
+    if (!isPlainRecord(value)) {
+        return { ok: false, code: "MALFORMED_EVENT", message: "fingerprint must be an object" };
+    }
+    if (value.algorithm_id !== 99 || value.algorithm !== "HMAC-SHA-256") {
+        return {
+            ok: false,
+            code: "UNSUPPORTED_ALGORITHM",
+            message: "audit chain fingerprint must use HMAC-SHA-256",
+        };
+    }
+    if (value.serialization_id !== 2) {
+        return {
+            ok: false,
+            code: "UNSUPPORTED_CANONICALIZATION",
+            message: "audit chain fingerprint must use RFC 8785 JCS",
+        };
+    }
+    if (value.encoding_id !== 1 || !isSha256Hex(value.value)) {
+        return {
+            ok: false,
+            code: "MALFORMED_EVENT",
+            message: "audit chain fingerprint must be lowercase SHA-256 hex",
+        };
+    }
+    return { ok: true, value: value };
+}
+function parseIntegrityEvent(value) {
+    if (!isPlainRecord(value)) {
+        return { ok: false, code: "MALFORMED_EVENT", message: "audit event must be an object" };
+    }
+    if (!isCredentialAuditTypeUid(value.type_uid)) {
+        return { ok: false, code: "MALFORMED_EVENT", message: "audit event type_uid is invalid" };
+    }
+    if (!isPlainRecord(value.metadata)) {
+        return { ok: false, code: "MALFORMED_EVENT", message: "audit metadata is missing" };
+    }
+    const sequenceNumber = value.metadata.sequence;
+    if (!Number.isSafeInteger(sequenceNumber) || sequenceNumber < 1) {
+        return { ok: false, code: "INVALID_SEQUENCE", message: "audit sequence is invalid" };
+    }
+    if (typeof value.metadata.uid !== "string" || value.metadata.uid.length === 0) {
+        return {
+            ok: false,
+            code: "MALFORMED_EVENT",
+            message: "audit metadata uid is missing",
+            sequenceNumber: sequenceNumber,
+        };
+    }
+    if (!Array.isArray(value.metadata.profiles) ||
+        value.metadata.profiles.length !== 1 ||
+        value.metadata.profiles[0] !== "record_integrity") {
+        return {
+            ok: false,
+            code: "MALFORMED_EVENT",
+            message: "record_integrity profile is missing",
+            sequenceNumber: sequenceNumber,
+        };
+    }
+    if (!isPlainRecord(value.unmapped)) {
+        return {
+            ok: false,
+            code: "MALFORMED_EVENT",
+            message: "audit unmapped extension is missing",
+            sequenceNumber: sequenceNumber,
+        };
+    }
+    const keyId = value.unmapped["centient.audit_chain.key_id"];
+    if (typeof keyId !== "string" || !IDENTIFIER_PATTERN.test(keyId)) {
+        return {
+            ok: false,
+            code: "MALFORMED_EVENT",
+            message: "audit chain key ID is invalid",
+            sequenceNumber: sequenceNumber,
+        };
+    }
+    if (!Array.isArray(value.attestation_list) || value.attestation_list.length !== 1) {
+        return {
+            ok: false,
+            code: "MALFORMED_EVENT",
+            message: "audit event must contain one attestation",
+            sequenceNumber: sequenceNumber,
+        };
+    }
+    const attestation = value.attestation_list[0];
+    if (!isPlainRecord(attestation) || typeof attestation.chain_uid !== "string") {
+        return {
+            ok: false,
+            code: "MALFORMED_EVENT",
+            message: "audit attestation chain ID is invalid",
+            sequenceNumber: sequenceNumber,
+        };
+    }
+    if (!IDENTIFIER_PATTERN.test(attestation.chain_uid)) {
+        return {
+            ok: false,
+            code: "MALFORMED_EVENT",
+            message: "audit attestation chain ID is invalid",
+            sequenceNumber: sequenceNumber,
+        };
+    }
+    const fingerprint = parseFingerprint(attestation.fingerprint);
+    if (!fingerprint.ok) {
+        return {
+            ok: false,
+            code: fingerprint.code,
+            message: fingerprint.message,
+            sequenceNumber: sequenceNumber,
+        };
+    }
+    let previousEvent;
+    if (attestation.prev_event !== undefined) {
+        if (!isPlainRecord(attestation.prev_event)) {
+            return {
+                ok: false,
+                code: "MALFORMED_EVENT",
+                message: "previous event reference is invalid",
+                sequenceNumber: sequenceNumber,
+            };
+        }
+        const previousFingerprint = parseFingerprint(attestation.prev_event.fingerprint);
+        if (!previousFingerprint.ok) {
+            return {
+                ok: false,
+                code: previousFingerprint.code,
+                message: previousFingerprint.message,
+                sequenceNumber: sequenceNumber,
+            };
+        }
+        if (typeof attestation.prev_event.uid !== "string" ||
+            attestation.prev_event.uid.length === 0 ||
+            !isCredentialAuditTypeUid(attestation.prev_event.type_uid)) {
+            return {
+                ok: false,
+                code: "MALFORMED_EVENT",
+                message: "previous event locator is invalid",
+                sequenceNumber: sequenceNumber,
+            };
+        }
+        previousEvent = {
+            uid: attestation.prev_event.uid,
+            typeUid: attestation.prev_event.type_uid,
+            fingerprint: previousFingerprint.value,
+        };
+    }
+    return {
+        ok: true,
+        value: {
+            record: value,
+            sequenceNumber: sequenceNumber,
+            chainId: attestation.chain_uid,
+            keyId,
+            eventUid: value.metadata.uid,
+            typeUid: value.type_uid,
+            fingerprint: fingerprint.value,
+            ...(previousEvent ? { previousEvent } : {}),
+        },
+    };
+}
+function checkpointsEqual(actual, expected) {
+    return (actual !== null &&
+        actual.chainId === expected.chainId &&
+        actual.sequenceNumber === expected.sequenceNumber &&
+        actual.eventUid === expected.eventUid &&
+        actual.eventHash === expected.eventHash &&
+        actual.typeUid === expected.typeUid &&
+        actual.keyId === expected.keyId &&
+        actual.usedKeyIds.length === expected.usedKeyIds.length &&
+        actual.usedKeyIds.every((keyId, index) => keyId === expected.usedKeyIds[index]) &&
+        actual.usedKeyFingerprints.length === expected.usedKeyFingerprints.length &&
+        actual.usedKeyFingerprints.every((fingerprint, index) => fingerprint === expected.usedKeyFingerprints[index]));
+}
+/**
+ * Verify one ordered chain segment without mutating records or key material.
+ *
+ * The function returns a discriminated failure for hostile input. It requires
+ * genesis (`sequence=1`, no `prev_event`) unless a trusted initial checkpoint
+ * anchors a later segment. An optional trusted final checkpoint detects suffix
+ * deletion; no hash-chain algorithm can detect deletion of the entire log by
+ * looking only at that log.
+ */
+export function verifyHmacAuditChain(events, options) {
+    let previous = null;
+    let rotations = 0;
+    const usedKeyIds = new Set();
+    const usedKeyFingerprints = new Set();
+    const keyFingerprintsById = new Map();
+    let expectedChainId;
+    let expectedFinalCheckpoint;
+    let resolveKey;
+    try {
+        const configuredExpectedChainId = options.expectedChainId;
+        const initialCheckpoint = options.initialCheckpoint;
+        const finalCheckpoint = options.expectedFinalCheckpoint;
+        resolveKey = options.resolveKey;
+        if (configuredExpectedChainId !== undefined) {
+            assertIdentifier(configuredExpectedChainId, "chainId");
+            expectedChainId = configuredExpectedChainId;
+        }
+        if (initialCheckpoint !== undefined) {
+            const trustedInitialCheckpoint = snapshotCheckpoint(initialCheckpoint);
+            previous = trustedInitialCheckpoint;
+            for (let index = 0; index < previous.usedKeyIds.length; index++) {
+                const keyId = previous.usedKeyIds[index];
+                const keyFingerprint = previous.usedKeyFingerprints[index];
+                usedKeyIds.add(keyId);
+                usedKeyFingerprints.add(keyFingerprint);
+                keyFingerprintsById.set(keyId, keyFingerprint);
+            }
+            if (expectedChainId !== undefined && previous.chainId !== expectedChainId) {
+                return verificationFailure("CHAIN_ID_MISMATCH", "initial checkpoint does not match the expected chain ID", -1, previous.sequenceNumber);
+            }
+        }
+        if (finalCheckpoint !== undefined) {
+            const trustedFinalCheckpoint = snapshotCheckpoint(finalCheckpoint);
+            expectedFinalCheckpoint = trustedFinalCheckpoint;
+            if (expectedChainId !== undefined &&
+                expectedFinalCheckpoint.chainId !== expectedChainId) {
+                return verificationFailure("CHAIN_ID_MISMATCH", "final checkpoint does not match the expected chain ID", -1, expectedFinalCheckpoint.sequenceNumber);
+            }
+        }
+    }
+    catch (error) {
+        return verificationFailure("MALFORMED_EVENT", error instanceof Error ? error.message : "audit checkpoint is malformed", -1);
+    }
+    for (let index = 0; index < events.length; index++) {
+        let parsedResult;
+        try {
+            parsedResult = parseIntegrityEvent(events[index]);
+        }
+        catch {
+            return verificationFailure("MALFORMED_EVENT", "audit event could not be parsed", index);
+        }
+        if (!parsedResult.ok) {
+            return verificationFailure(parsedResult.code, parsedResult.message, index, parsedResult.sequenceNumber);
+        }
+        const parsed = parsedResult.value;
+        if (expectedChainId !== undefined && parsed.chainId !== expectedChainId) {
+            return verificationFailure("CHAIN_ID_MISMATCH", "audit event does not match the expected chain ID", index, parsed.sequenceNumber);
+        }
+        if (previous === null) {
+            if (parsed.sequenceNumber !== 1 || parsed.previousEvent !== undefined) {
+                return verificationFailure("UNANCHORED_SEGMENT", "verification must start at genesis or a trusted checkpoint", index, parsed.sequenceNumber);
+            }
+        }
+        else {
+            if (parsed.chainId !== previous.chainId) {
+                return verificationFailure("CHAIN_ID_MISMATCH", "audit event changed chain ID", index, parsed.sequenceNumber);
+            }
+            if (parsed.sequenceNumber !== previous.sequenceNumber + 1) {
+                return verificationFailure("SEQUENCE_GAP_OR_REORDER", "audit sequence contains a gap, duplicate, or reorder", index, parsed.sequenceNumber);
+            }
+            if (!parsed.previousEvent) {
+                return verificationFailure("PREVIOUS_EVENT_MISMATCH", "audit event is missing its previous-event reference", index, parsed.sequenceNumber);
+            }
+            if (parsed.previousEvent.uid !== previous.eventUid ||
+                parsed.previousEvent.typeUid !== previous.typeUid) {
+                return verificationFailure("PREVIOUS_EVENT_MISMATCH", "audit previous-event locator does not match", index, parsed.sequenceNumber);
+            }
+            if (parsed.previousEvent.fingerprint.value !== previous.eventHash) {
+                return verificationFailure("PREVIOUS_HASH_MISMATCH", "audit previous-event fingerprint does not match", index, parsed.sequenceNumber);
+            }
+        }
+        const isRotation = previous !== null && parsed.keyId !== previous.keyId;
+        if (isRotation) {
+            if (usedKeyIds.has(parsed.keyId)) {
+                return verificationFailure("KEY_ID_REUSE", "audit chain reused an earlier key ID", index, parsed.sequenceNumber);
+            }
+        }
+        let resolved;
+        try {
+            resolved = resolveKey(parsed.keyId);
+        }
+        catch {
+            return verificationFailure("KEY_RESOLUTION_FAILED", "audit verification key resolution failed", index, parsed.sequenceNumber);
+        }
+        if (resolved === undefined) {
+            return verificationFailure("UNKNOWN_KEY_ID", "audit verification key ID is unknown", index, parsed.sequenceNumber);
+        }
+        if (!(resolved instanceof Uint8Array) || resolved.byteLength !== HMAC_KEY_BYTES) {
+            return verificationFailure("INVALID_KEY", "audit verification key must be exactly 32 bytes", index, parsed.sequenceNumber);
+        }
+        const resolvedKeyFingerprint = keyMaterialFingerprint(parsed.chainId, resolved);
+        const knownKeyFingerprint = keyFingerprintsById.get(parsed.keyId);
+        if (knownKeyFingerprint !== undefined &&
+            knownKeyFingerprint !== resolvedKeyFingerprint) {
+            return verificationFailure("KEY_ID_MATERIAL_MISMATCH", "audit key ID resolved to different key material", index, parsed.sequenceNumber);
+        }
+        if (knownKeyFingerprint === undefined &&
+            usedKeyFingerprints.has(resolvedKeyFingerprint)) {
+            return verificationFailure("KEY_MATERIAL_REUSE", "audit chain reused historical key material under a fresh ID", index, parsed.sequenceNumber);
+        }
+        if (knownKeyFingerprint === undefined) {
+            usedKeyIds.add(parsed.keyId);
+            usedKeyFingerprints.add(resolvedKeyFingerprint);
+            keyFingerprintsById.set(parsed.keyId, resolvedKeyFingerprint);
+        }
+        if (isRotation)
+            rotations++;
+        let canonical;
+        try {
+            canonical = canonicalizeAuditEvent(unsignedEventForHash(parsed.record));
+        }
+        catch {
+            return verificationFailure("MALFORMED_EVENT", "audit event cannot be canonicalized", index, parsed.sequenceNumber);
+        }
+        const keyCopy = Buffer.from(resolved);
+        let expected;
+        try {
+            expected = hmacSha256(keyCopy, canonical);
+        }
+        finally {
+            keyCopy.fill(0);
+        }
+        const observed = Buffer.from(parsed.fingerprint.value, "hex");
+        if (!timingSafeEqual(expected, observed)) {
+            expected.fill(0);
+            observed.fill(0);
+            return verificationFailure("HASH_MISMATCH", "audit event HMAC does not match", index, parsed.sequenceNumber);
+        }
+        expected.fill(0);
+        observed.fill(0);
+        previous = snapshotCheckpoint({
+            chainId: parsed.chainId,
+            sequenceNumber: parsed.sequenceNumber,
+            eventUid: parsed.eventUid,
+            eventHash: parsed.fingerprint.value,
+            typeUid: parsed.typeUid,
+            keyId: parsed.keyId,
+            usedKeyIds: [...usedKeyIds],
+            usedKeyFingerprints: [...usedKeyFingerprints],
+        });
+    }
+    if (expectedFinalCheckpoint !== undefined &&
+        !checkpointsEqual(previous, expectedFinalCheckpoint)) {
+        return verificationFailure("FINAL_CHECKPOINT_MISMATCH", "audit chain does not reach the expected final checkpoint", events.length, previous?.sequenceNumber);
+    }
+    return {
+        ok: true,
+        value: {
+            verifiedCount: events.length,
+            rotations,
+            checkpoint: previous,
+        },
+    };
+}
+//# sourceMappingURL=hmac-chain.js.map