@propxchain/core-client 0.3.0-canary.28 → 0.3.0-canary.29

package/dist/audit/auditChain.d.ts

@@ -0,0 +1,20 @@
+import { Principal } from "@icp-sdk/core/principal";
+/** Structural shape of a decoded ledger_manager AuditEvent (candid). */
+export interface CertifiedAuditEvent {
+    eventId: bigint;
+    transactionId: string;
+    eventType: string;
+    timestamp: bigint;
+    caller: Principal;
+    details: string;
+    metadata: [] | [string];
+}
+/** Canonical event encoding — mirrors ledger_manager.encodeAuditEvent. */
+export declare function encodeAuditEvent(e: CertifiedAuditEvent): Uint8Array;
+/**
+ * Recompute a transaction's chain head from its events — mirrors
+ * ledger_manager.chainHead. Events are sorted by eventId ascending (the
+ * canister's canonical order) so the result is independent of array order.
+ */
+export declare function recomputeHeadHash(events: CertifiedAuditEvent[]): Promise<Uint8Array>;
+//# sourceMappingURL=auditChain.d.ts.map

package/dist/audit/auditChain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auditChain.d.ts","sourceRoot":"","sources":["../../src/audit/auditChain.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEpD,wEAAwE;AACxE,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,SAAS,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACzB;AA0BD,0EAA0E;AAC1E,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,mBAAmB,GAAG,UAAU,CAgBnE;AAOD;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,mBAAmB,EAAE,GAC5B,OAAO,CAAC,UAAU,CAAC,CASrB"}

package/dist/audit/auditChain.js

@@ -0,0 +1,67 @@
+// Audit hash chain — TypeScript mirror of ledger_manager's derived chain (ADR 0013).
+//
+// This MUST match the Motoko encoding in
+// packages/core/src/ledger_manager/main.mo (encodeAuditEvent / chainHead)
+// byte-for-byte, or verification will reject genuine records. The canonical
+// encoding: each field 4-byte big-endian length-prefixed UTF-8; metadata uses
+// a 1-byte presence tag (0 = null, 1 = present). eventHash_i =
+// SHA-256(prevHash ++ encode(event_i)); genesis prevHash = 32 zero bytes;
+// events ordered by eventId ascending.
+const encoder = new TextEncoder();
+function lenPrefixed(bytes) {
+    const n = bytes.length;
+    const out = new Uint8Array(4 + n);
+    out[0] = (n >>> 24) & 0xff;
+    out[1] = (n >>> 16) & 0xff;
+    out[2] = (n >>> 8) & 0xff;
+    out[3] = n & 0xff;
+    out.set(bytes, 4);
+    return out;
+}
+function concat(chunks) {
+    const total = chunks.reduce((sum, c) => sum + c.length, 0);
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const c of chunks) {
+        out.set(c, offset);
+        offset += c.length;
+    }
+    return out;
+}
+/** Canonical event encoding — mirrors ledger_manager.encodeAuditEvent. */
+export function encodeAuditEvent(e) {
+    const parts = [
+        lenPrefixed(encoder.encode(e.eventId.toString())),
+        lenPrefixed(encoder.encode(e.transactionId)),
+        lenPrefixed(encoder.encode(e.eventType)),
+        lenPrefixed(encoder.encode(e.timestamp.toString())),
+        lenPrefixed(encoder.encode(e.caller.toText())),
+        lenPrefixed(encoder.encode(e.details)),
+    ];
+    if (e.metadata.length === 0) {
+        parts.push(new Uint8Array([0]));
+    }
+    else {
+        parts.push(new Uint8Array([1]));
+        parts.push(lenPrefixed(encoder.encode(e.metadata[0])));
+    }
+    return concat(parts);
+}
+async function sha256(data) {
+    const digest = await crypto.subtle.digest("SHA-256", data);
+    return new Uint8Array(digest);
+}
+/**
+ * Recompute a transaction's chain head from its events — mirrors
+ * ledger_manager.chainHead. Events are sorted by eventId ascending (the
+ * canister's canonical order) so the result is independent of array order.
+ */
+export async function recomputeHeadHash(events) {
+    const ordered = [...events].sort((a, b) => a.eventId < b.eventId ? -1 : a.eventId > b.eventId ? 1 : 0);
+    let head = new Uint8Array(32); // genesis: 32 zero bytes
+    for (const e of ordered) {
+        head = await sha256(concat([head, encodeAuditEvent(e)]));
+    }
+    return head;
+}
+//# sourceMappingURL=auditChain.js.map

package/dist/audit/auditChain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auditChain.js","sourceRoot":"","sources":["../../src/audit/auditChain.ts"],"names":[],"mappings":"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"}

package/dist/audit/index.d.ts

@@ -0,0 +1,4 @@
+export { type CertifiedAuditEvent, encodeAuditEvent, recomputeHeadHash, } from "./auditChain.js";
+export { type CertifiedTransactionLog, type VerifyResult, type VerifyOptions, verifyCertifiedAuditLog, } from "./verifyAuditLog.js";
+export { AUDIT_SEAL_DOC_TYPE, type AuditSealBundle, buildAuditSealBundle, serializeAuditSealBundle, } from "./sealAuditBundle.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/audit/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/audit/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,mBAAmB,EACxB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,uBAAuB,GACxB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,mBAAmB,EACnB,KAAK,eAAe,EACpB,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,sBAAsB,CAAC"}

package/dist/audit/index.js

@@ -0,0 +1,6 @@
+// Verifiable audit trail (ADR 0013) — chain recompute, certificate
+// verification, and sealed proof bundles for the per-transaction audit log.
+export { encodeAuditEvent, recomputeHeadHash, } from "./auditChain.js";
+export { verifyCertifiedAuditLog, } from "./verifyAuditLog.js";
+export { AUDIT_SEAL_DOC_TYPE, buildAuditSealBundle, serializeAuditSealBundle, } from "./sealAuditBundle.js";
+//# sourceMappingURL=index.js.map

package/dist/audit/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/audit/index.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,4EAA4E;AAC5E,OAAO,EAEL,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAIL,uBAAuB,GACxB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,mBAAmB,EAEnB,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,sBAAsB,CAAC"}

package/dist/audit/sealAuditBundle.d.ts

@@ -0,0 +1,36 @@
+import { type CertifiedTransactionLog } from "./verifyAuditLog.js";
+export declare const AUDIT_SEAL_DOC_TYPE = "audit_seal";
+interface SerializableAuditEvent {
+    eventId: string;
+    transactionId: string;
+    eventType: string;
+    timestamp: string;
+    caller: string;
+    details: string;
+    metadata: string | null;
+}
+export interface AuditSealBundle {
+    version: 1;
+    canisterId: string;
+    transactionId: string;
+    /** Client capture time (ISO). The authoritative time is inside the certificate. */
+    capturedAt: string;
+    events: SerializableAuditEvent[];
+    headHashHex: string;
+    certificateB64: string;
+    witnessB64: string;
+}
+/**
+ * Build a sealed, serializable proof bundle from a certified log response.
+ * Throws if the response carries no certificate (nothing to seal).
+ */
+export declare function buildAuditSealBundle(args: {
+    canisterId: string;
+    transactionId: string;
+    capturedAt: string;
+    log: CertifiedTransactionLog;
+}): AuditSealBundle;
+/** Serialize a bundle to bytes for on-chain storage (document_storage). */
+export declare function serializeAuditSealBundle(bundle: AuditSealBundle): Uint8Array;
+export {};
+//# sourceMappingURL=sealAuditBundle.d.ts.map

package/dist/audit/sealAuditBundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sealAuditBundle.d.ts","sourceRoot":"","sources":["../../src/audit/sealAuditBundle.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,KAAK,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAEnE,eAAO,MAAM,mBAAmB,eAAe,CAAC;AAEhD,UAAU,sBAAsB;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,CAAC,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,mFAAmF;IACnF,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,sBAAsB,EAAE,CAAC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;CACpB;AAaD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,uBAAuB,CAAC;CAC9B,GAAG,eAAe,CAuBlB;AAED,2EAA2E;AAC3E,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,eAAe,GAAG,UAAU,CAE5E"}

package/dist/audit/sealAuditBundle.js

@@ -0,0 +1,58 @@
+// Sealed audit bundle (ADR 0013, proof model ii).
+//
+// A contemporaneous, self-contained snapshot of a transaction's certified
+// audit log. Built from a getCertifiedTransactionLog response (a query, so the
+// subnet certificate is present) — typically at completion, and regenerable on
+// demand. The bundle verifies offline against the IC root key, even if
+// PropXchain is gone: a forensic verifier re-runs verifyCertifiedAuditLog with
+// a relaxed freshness window.
+//
+// Persistence: the serialized bundle is stored on-chain in document_storage
+// (docType "audit_seal") per ADR 0008. That upload uses the existing document
+// upload path and is the caller's step — buildAuditSealBundle only produces the
+// bytes (no document bodies are embedded; events reference any documents by
+// hash only).
+export const AUDIT_SEAL_DOC_TYPE = "audit_seal";
+function toHex(bytes) {
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+function toB64(bytes) {
+    // Browser + Node (>=20) both expose btoa; build a binary string first.
+    let binary = "";
+    for (const b of bytes)
+        binary += String.fromCharCode(b);
+    return btoa(binary);
+}
+/**
+ * Build a sealed, serializable proof bundle from a certified log response.
+ * Throws if the response carries no certificate (nothing to seal).
+ */
+export function buildAuditSealBundle(args) {
+    const { canisterId, transactionId, capturedAt, log } = args;
+    if (log.certificate.length === 0) {
+        throw new Error("cannot seal: certified log response has no certificate");
+    }
+    return {
+        version: 1,
+        canisterId,
+        transactionId,
+        capturedAt,
+        events: log.events.map((e) => ({
+            eventId: e.eventId.toString(),
+            transactionId: e.transactionId,
+            eventType: e.eventType,
+            timestamp: e.timestamp.toString(),
+            caller: e.caller.toText(),
+            details: e.details,
+            metadata: e.metadata.length === 0 ? null : e.metadata[0],
+        })),
+        headHashHex: toHex(log.headHash),
+        certificateB64: toB64(log.certificate[0]),
+        witnessB64: toB64(log.witness),
+    };
+}
+/** Serialize a bundle to bytes for on-chain storage (document_storage). */
+export function serializeAuditSealBundle(bundle) {
+    return new TextEncoder().encode(JSON.stringify(bundle));
+}
+//# sourceMappingURL=sealAuditBundle.js.map

package/dist/audit/sealAuditBundle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sealAuditBundle.js","sourceRoot":"","sources":["../../src/audit/sealAuditBundle.ts"],"names":[],"mappings":"AAAA,kDAAkD;AAClD,EAAE;AACF,0EAA0E;AAC1E,+EAA+E;AAC/E,+EAA+E;AAC/E,uEAAuE;AACvE,+EAA+E;AAC/E,8BAA8B;AAC9B,EAAE;AACF,4EAA4E;AAC5E,8EAA8E;AAC9E,gFAAgF;AAChF,4EAA4E;AAC5E,cAAc;AAId,MAAM,CAAC,MAAM,mBAAmB,GAAG,YAAY,CAAC;AAwBhD,SAAS,KAAK,CAAC,KAAiB;IAC9B,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAC5E,CAAC;AAED,SAAS,KAAK,CAAC,KAAiB;IAC9B,uEAAuE;IACvE,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,KAAK,MAAM,CAAC,IAAI,KAAK;QAAE,MAAM,IAAI,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IACxD,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC;AACtB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAKpC;IACC,MAAM,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAC5D,IAAI,GAAG,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;IAC5E,CAAC;IACD,OAAO;QACL,OAAO,EAAE,CAAC;QACV,UAAU;QACV,aAAa;QACb,UAAU;QACV,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAC7B,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE;YAC7B,aAAa,EAAE,CAAC,CAAC,aAAa;YAC9B,SAAS,EAAE,CAAC,CAAC,SAAS;YACtB,SAAS,EAAE,CAAC,CAAC,SAAS,CAAC,QAAQ,EAAE;YACjC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE;YACzB,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;SACzD,CAAC,CAAC;QACH,WAAW,EAAE,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC;QAChC,cAAc,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;QACzC,UAAU,EAAE,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC;KAC/B,CAAC;AACJ,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,wBAAwB,CAAC,MAAuB;IAC9D,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;AAC1D,CAAC"}

package/dist/audit/verifyAuditLog.d.ts

@@ -0,0 +1,28 @@
+import { type CertifiedAuditEvent } from "./auditChain.js";
+/** Decoded ledger_manager.getCertifiedTransactionLog response. */
+export interface CertifiedTransactionLog {
+    events: CertifiedAuditEvent[];
+    headHash: Uint8Array;
+    certificate: [] | [Uint8Array];
+    witness: Uint8Array;
+}
+export interface VerifyResult {
+    verified: boolean;
+    reason?: string;
+    eventCount: number;
+}
+export interface VerifyOptions {
+    canisterId: string;
+    /** IC root public key — the mainnet constant, or `agent.rootKey` for local. */
+    rootKey: Uint8Array;
+    transactionId: string;
+    log: CertifiedTransactionLog;
+    /**
+     * Certificate freshness window. Omit for live verification (5 min). For
+     * forensic verification of a sealed bundle, pass a large value (e.g.
+     * Number.MAX_SAFE_INTEGER) to accept a historical certificate.
+     */
+    maxCertificateTimeOffsetMs?: number;
+}
+export declare function verifyCertifiedAuditLog(opts: VerifyOptions): Promise<VerifyResult>;
+//# sourceMappingURL=verifyAuditLog.d.ts.map

package/dist/audit/verifyAuditLog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verifyAuditLog.d.ts","sourceRoot":"","sources":["../../src/audit/verifyAuditLog.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,KAAK,mBAAmB,EAAqB,MAAM,iBAAiB,CAAC;AAiC9E,kEAAkE;AAClE,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,mBAAmB,EAAE,CAAC;IAC9B,QAAQ,EAAE,UAAU,CAAC;IACrB,WAAW,EAAE,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC;IAC/B,OAAO,EAAE,UAAU,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,+EAA+E;IAC/E,OAAO,EAAE,UAAU,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,GAAG,EAAE,uBAAuB,CAAC;IAC7B;;;;OAIG;IACH,0BAA0B,CAAC,EAAE,MAAM,CAAC;CACrC;AAiBD,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,YAAY,CAAC,CAkEvB"}

package/dist/audit/verifyAuditLog.js

@@ -0,0 +1,106 @@
+// Verifier for the certified per-transaction audit log (ADR 0013).
+//
+// Proves a transaction's audit trail is genuine canister state against the IC
+// root key, trusting no part of PropXchain:
+//   1. verify the subnet certificate + Merkle witness;
+//   2. read the certified headHash for the transaction from the witness tree;
+//   3. confirm the response's stated head matches the certified head;
+//   4. recompute the chain from the events and confirm it matches.
+//
+// Uses the @dfinity/* family (agent, principal, certificate-verification)
+// throughout — that is the lineage certificate-verification depends on, so the
+// HashTree/Principal types line up. The rest of core-client uses @icp-sdk;
+// this leaf module's boundary is plain Uint8Array/string, so the split is
+// contained.
+//
+// Live verification keeps the certificate-freshness window tight. Forensic
+// verification of a sealed historical bundle (ADR 0013, proof model ii)
+// relaxes it by design — the bundle proves a fact as-of the certificate's
+// /time, not a current one.
+import { lookup_path, lookupResultToBuffer } from "@dfinity/agent";
+import { Principal } from "@dfinity/principal";
+import { recomputeHeadHash } from "./auditChain.js";
+let cachedVerify;
+async function loadVerifyCertification() {
+    if (cachedVerify)
+        return cachedVerify;
+    const mod = (await import("@dfinity/certificate-verification"));
+    const fn = mod.verifyCertification ?? mod.default?.verifyCertification;
+    if (!fn) {
+        throw new Error("verifyCertification not found in @dfinity/certificate-verification");
+    }
+    cachedVerify = fn;
+    return fn;
+}
+const FIVE_MINUTES_MS = 5 * 60 * 1000;
+function toArrayBuffer(u8) {
+    const copy = new Uint8Array(u8.length);
+    copy.set(u8);
+    return copy.buffer;
+}
+function equalBytes(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a[i] ^ b[i];
+    return diff === 0;
+}
+export async function verifyCertifiedAuditLog(opts) {
+    const { log, transactionId } = opts;
+    const eventCount = log.events.length;
+    if (log.certificate.length === 0) {
+        return { verified: false, reason: "no certificate in response", eventCount };
+    }
+    // 1. Verify the subnet certificate + witness against the IC root key.
+    let tree;
+    try {
+        const verifyCertification = await loadVerifyCertification();
+        tree = await verifyCertification({
+            canisterId: Principal.fromText(opts.canisterId),
+            encodedCertificate: toArrayBuffer(log.certificate[0]),
+            encodedTree: toArrayBuffer(log.witness),
+            rootKey: toArrayBuffer(opts.rootKey),
+            maxCertificateTimeOffsetMs: opts.maxCertificateTimeOffsetMs ?? FIVE_MINUTES_MS,
+        });
+    }
+    catch (err) {
+        return {
+            verified: false,
+            reason: `certificate verification failed: ${String(err)}`,
+            eventCount,
+        };
+    }
+    // 2. Read the certified headHash for this transaction from the witness tree.
+    // The path segment is the UTF-8 bytes of the transactionId — exactly the key
+    // ledger_manager certified (Text.encodeUtf8(transactionId)).
+    const lookup = lookup_path([toArrayBuffer(new TextEncoder().encode(transactionId))], tree);
+    const certifiedBuf = lookupResultToBuffer(lookup);
+    if (!certifiedBuf) {
+        return {
+            verified: false,
+            reason: "transaction head not present in certified tree",
+            eventCount,
+        };
+    }
+    const certifiedHead = new Uint8Array(certifiedBuf);
+    // 3. The response's stated head must match the certified value.
+    if (!equalBytes(certifiedHead, log.headHash)) {
+        return {
+            verified: false,
+            reason: "response headHash does not match certified value",
+            eventCount,
+        };
+    }
+    // 4. The head recomputed from the events must match the certified head.
+    const recomputed = await recomputeHeadHash(log.events);
+    if (!equalBytes(recomputed, certifiedHead)) {
+        return {
+            verified: false,
+            reason: "recomputed chain head does not match certified head — events tampered",
+            eventCount,
+        };
+    }
+    return { verified: true, eventCount };
+}
+//# sourceMappingURL=verifyAuditLog.js.map

package/dist/audit/verifyAuditLog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verifyAuditLog.js","sourceRoot":"","sources":["../../src/audit/verifyAuditLog.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export { PropXchainClient } from "./client.js";
 export { MockPropXchainClient, isMockEnabled, MOCK_ENV_FLAG, } from "./mock.js";
 export { CoreClientError, wrapAgentError, type CoreClientErrorCode, } from "./errors.js";
 export { withRetry, type RetryOptions } from "./retry.js";
+export { type CertifiedAuditEvent, encodeAuditEvent, recomputeHeadHash, type CertifiedTransactionLog, type VerifyResult, type VerifyOptions, verifyCertifiedAuditLog, AUDIT_SEAL_DOC_TYPE, type AuditSealBundle, buildAuditSealBundle, serializeAuditSealBundle, } from "./audit/index.js";
 export { createAuditTrailStub, createAgentHarnessStub, type AuditTrailStub, type AgentHarnessStub, type AuditEvent, type AuditFilter, } from "./stubs.js";
 export { MAINNET_CANISTER_IDS, type CanisterIds, type IPropXchainClient, type PropXchainClientOptions, type TransactionManagerService, type DocumentStorageService, type UserManagementService, type LedgerManagerService, type PropertyRegistryService, type DocumentVerificationService, type EmailServiceService, type LandRegistryIntegrationService, } from "./types.js";
 export { Principal, Ed25519KeyIdentity, AuthClient, IdbStorage, Actor, HttpAgent, type Identity, type ActorSubclass, type ActorConfig, type ActorMethod, type AuthClientCreateOptions, type AuthClientSignInOptions, } from "./auth.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EACL,oBAAoB,EACpB,aAAa,EACb,aAAa,GACd,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,eAAe,EACf,cAAc,EACd,KAAK,mBAAmB,GACzB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,SAAS,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,UAAU,EACf,KAAK,WAAW,GACjB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,oBAAoB,EACpB,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,EAC5B,KAAK,yBAAyB,EAC9B,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,2BAA2B,EAChC,KAAK,mBAAmB,EACxB,KAAK,8BAA8B,GACpC,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,UAAU,EACV,UAAU,EACV,KAAK,EACL,SAAS,EACT,KAAK,QAAQ,EACb,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,uBAAuB,EAC5B,KAAK,uBAAuB,GAC7B,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,UAAU,IAAI,qBAAqB,EAAE,MAAM,0CAA0C,CAAC;AAC/F,OAAO,EAAE,UAAU,IAAI,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AACzF,OAAO,EAAE,UAAU,IAAI,iBAAiB,EAAE,MAAM,sCAAsC,CAAC;AACvF,OAAO,EAAE,UAAU,IAAI,gBAAgB,EAAE,MAAM,qCAAqC,CAAC;AACrF,OAAO,EAAE,UAAU,IAAI,mBAAmB,EAAE,MAAM,wCAAwC,CAAC;AAC3F,OAAO,EAAE,UAAU,IAAI,uBAAuB,EAAE,MAAM,4CAA4C,CAAC;AACnG,OAAO,EAAE,UAAU,IAAI,eAAe,EAAE,MAAM,oCAAoC,CAAC;AACnF,OAAO,EAAE,UAAU,IAAI,0BAA0B,EAAE,MAAM,gDAAgD,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EACL,oBAAoB,EACpB,aAAa,EACb,aAAa,GACd,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,eAAe,EACf,cAAc,EACd,KAAK,mBAAmB,GACzB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,SAAS,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,EACL,KAAK,mBAAmB,EACxB,gBAAgB,EAChB,iBAAiB,EACjB,KAAK,uBAAuB,EAC5B,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,uBAAuB,EACvB,mBAAmB,EACnB,KAAK,eAAe,EACpB,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,UAAU,EACf,KAAK,WAAW,GACjB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,oBAAoB,EACpB,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,EAC5B,KAAK,yBAAyB,EAC9B,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,2BAA2B,EAChC,KAAK,mBAAmB,EACxB,KAAK,8BAA8B,GACpC,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,UAAU,EACV,UAAU,EACV,KAAK,EACL,SAAS,EACT,KAAK,QAAQ,EACb,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,uBAAuB,EAC5B,KAAK,uBAAuB,GAC7B,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,UAAU,IAAI,qBAAqB,EAAE,MAAM,0CAA0C,CAAC;AAC/F,OAAO,EAAE,UAAU,IAAI,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AACzF,OAAO,EAAE,UAAU,IAAI,iBAAiB,EAAE,MAAM,sCAAsC,CAAC;AACvF,OAAO,EAAE,UAAU,IAAI,gBAAgB,EAAE,MAAM,qCAAqC,CAAC;AACrF,OAAO,EAAE,UAAU,IAAI,mBAAmB,EAAE,MAAM,wCAAwC,CAAC;AAC3F,OAAO,EAAE,UAAU,IAAI,uBAAuB,EAAE,MAAM,4CAA4C,CAAC;AACnG,OAAO,EAAE,UAAU,IAAI,eAAe,EAAE,MAAM,oCAAoC,CAAC;AACnF,OAAO,EAAE,UAAU,IAAI,0BAA0B,EAAE,MAAM,gDAAgD,CAAC"}

package/dist/index.js

@@ -2,6 +2,7 @@ export { PropXchainClient } from "./client.js";
 export { MockPropXchainClient, isMockEnabled, MOCK_ENV_FLAG, } from "./mock.js";
 export { CoreClientError, wrapAgentError, } from "./errors.js";
 export { withRetry } from "./retry.js";
+export { encodeAuditEvent, recomputeHeadHash, verifyCertifiedAuditLog, AUDIT_SEAL_DOC_TYPE, buildAuditSealBundle, serializeAuditSealBundle, } from "./audit/index.js";
 export { createAuditTrailStub, createAgentHarnessStub, } from "./stubs.js";
 export { MAINNET_CANISTER_IDS, } from "./types.js";
 export { Principal, Ed25519KeyIdentity, AuthClient, IdbStorage, Actor, HttpAgent, } from "./auth.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EACL,oBAAoB,EACpB,aAAa,EACb,aAAa,GACd,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,eAAe,EACf,cAAc,GAEf,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,SAAS,EAAqB,MAAM,YAAY,CAAC;AAC1D,OAAO,EACL,oBAAoB,EACpB,sBAAsB,GAKvB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,oBAAoB,GAYrB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,UAAU,EACV,UAAU,EACV,KAAK,EACL,SAAS,GAOV,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,UAAU,IAAI,qBAAqB,EAAE,MAAM,0CAA0C,CAAC;AAC/F,OAAO,EAAE,UAAU,IAAI,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AACzF,OAAO,EAAE,UAAU,IAAI,iBAAiB,EAAE,MAAM,sCAAsC,CAAC;AACvF,OAAO,EAAE,UAAU,IAAI,gBAAgB,EAAE,MAAM,qCAAqC,CAAC;AACrF,OAAO,EAAE,UAAU,IAAI,mBAAmB,EAAE,MAAM,wCAAwC,CAAC;AAC3F,OAAO,EAAE,UAAU,IAAI,uBAAuB,EAAE,MAAM,4CAA4C,CAAC;AACnG,OAAO,EAAE,UAAU,IAAI,eAAe,EAAE,MAAM,oCAAoC,CAAC;AACnF,OAAO,EAAE,UAAU,IAAI,0BAA0B,EAAE,MAAM,gDAAgD,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EACL,oBAAoB,EACpB,aAAa,EACb,aAAa,GACd,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,eAAe,EACf,cAAc,GAEf,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,SAAS,EAAqB,MAAM,YAAY,CAAC;AAC1D,OAAO,EAEL,gBAAgB,EAChB,iBAAiB,EAIjB,uBAAuB,EACvB,mBAAmB,EAEnB,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,oBAAoB,EACpB,sBAAsB,GAKvB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,oBAAoB,GAYrB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,UAAU,EACV,UAAU,EACV,KAAK,EACL,SAAS,GAOV,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,UAAU,IAAI,qBAAqB,EAAE,MAAM,0CAA0C,CAAC;AAC/F,OAAO,EAAE,UAAU,IAAI,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AACzF,OAAO,EAAE,UAAU,IAAI,iBAAiB,EAAE,MAAM,sCAAsC,CAAC;AACvF,OAAO,EAAE,UAAU,IAAI,gBAAgB,EAAE,MAAM,qCAAqC,CAAC;AACrF,OAAO,EAAE,UAAU,IAAI,mBAAmB,EAAE,MAAM,wCAAwC,CAAC;AAC3F,OAAO,EAAE,UAAU,IAAI,uBAAuB,EAAE,MAAM,4CAA4C,CAAC;AACnG,OAAO,EAAE,UAAU,IAAI,eAAe,EAAE,MAAM,oCAAoC,CAAC;AACnF,OAAO,EAAE,UAAU,IAAI,0BAA0B,EAAE,MAAM,gDAAgD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@propxchain/core-client",
-  "version": "0.3.0-canary.28",
+  "version": "0.3.0-canary.29",
   "description": "Typed TypeScript client for the PropXchain core canisters on the Internet Computer. Includes a deterministic mock mode for local development and tests.",
   "license": "UNLICENSED",
   "type": "module",
@@ -35,6 +35,9 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
+    "@dfinity/agent": "^1.4.0",
+    "@dfinity/certificate-verification": "^3.1.0",
+    "@dfinity/principal": "^1.4.0",
     "@icp-sdk/auth": "^7.0.0",
     "@icp-sdk/core": "^5.4.0"
   },

package/src/audit/auditChain.ts

@@ -0,0 +1,88 @@
+// Audit hash chain — TypeScript mirror of ledger_manager's derived chain (ADR 0013).
+//
+// This MUST match the Motoko encoding in
+// packages/core/src/ledger_manager/main.mo (encodeAuditEvent / chainHead)
+// byte-for-byte, or verification will reject genuine records. The canonical
+// encoding: each field 4-byte big-endian length-prefixed UTF-8; metadata uses
+// a 1-byte presence tag (0 = null, 1 = present). eventHash_i =
+// SHA-256(prevHash ++ encode(event_i)); genesis prevHash = 32 zero bytes;
+// events ordered by eventId ascending.
+
+import { Principal } from "@icp-sdk/core/principal";
+
+/** Structural shape of a decoded ledger_manager AuditEvent (candid). */
+export interface CertifiedAuditEvent {
+  eventId: bigint;
+  transactionId: string;
+  eventType: string;
+  timestamp: bigint;
+  caller: Principal;
+  details: string;
+  metadata: [] | [string];
+}
+
+const encoder = new TextEncoder();
+
+function lenPrefixed(bytes: Uint8Array): Uint8Array {
+  const n = bytes.length;
+  const out = new Uint8Array(4 + n);
+  out[0] = (n >>> 24) & 0xff;
+  out[1] = (n >>> 16) & 0xff;
+  out[2] = (n >>> 8) & 0xff;
+  out[3] = n & 0xff;
+  out.set(bytes, 4);
+  return out;
+}
+
+function concat(chunks: Uint8Array[]): Uint8Array {
+  const total = chunks.reduce((sum, c) => sum + c.length, 0);
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const c of chunks) {
+    out.set(c, offset);
+    offset += c.length;
+  }
+  return out;
+}
+
+/** Canonical event encoding — mirrors ledger_manager.encodeAuditEvent. */
+export function encodeAuditEvent(e: CertifiedAuditEvent): Uint8Array {
+  const parts: Uint8Array[] = [
+    lenPrefixed(encoder.encode(e.eventId.toString())),
+    lenPrefixed(encoder.encode(e.transactionId)),
+    lenPrefixed(encoder.encode(e.eventType)),
+    lenPrefixed(encoder.encode(e.timestamp.toString())),
+    lenPrefixed(encoder.encode(e.caller.toText())),
+    lenPrefixed(encoder.encode(e.details)),
+  ];
+  if (e.metadata.length === 0) {
+    parts.push(new Uint8Array([0]));
+  } else {
+    parts.push(new Uint8Array([1]));
+    parts.push(lenPrefixed(encoder.encode(e.metadata[0])));
+  }
+  return concat(parts);
+}
+
+async function sha256(data: Uint8Array): Promise<Uint8Array> {
+  const digest = await crypto.subtle.digest("SHA-256", data as unknown as BufferSource);
+  return new Uint8Array(digest);
+}
+
+/**
+ * Recompute a transaction's chain head from its events — mirrors
+ * ledger_manager.chainHead. Events are sorted by eventId ascending (the
+ * canister's canonical order) so the result is independent of array order.
+ */
+export async function recomputeHeadHash(
+  events: CertifiedAuditEvent[],
+): Promise<Uint8Array> {
+  const ordered = [...events].sort((a, b) =>
+    a.eventId < b.eventId ? -1 : a.eventId > b.eventId ? 1 : 0,
+  );
+  let head: Uint8Array = new Uint8Array(32); // genesis: 32 zero bytes
+  for (const e of ordered) {
+    head = await sha256(concat([head, encodeAuditEvent(e)]));
+  }
+  return head;
+}

package/src/audit/index.ts

@@ -0,0 +1,19 @@
+// Verifiable audit trail (ADR 0013) — chain recompute, certificate
+// verification, and sealed proof bundles for the per-transaction audit log.
+export {
+  type CertifiedAuditEvent,
+  encodeAuditEvent,
+  recomputeHeadHash,
+} from "./auditChain.js";
+export {
+  type CertifiedTransactionLog,
+  type VerifyResult,
+  type VerifyOptions,
+  verifyCertifiedAuditLog,
+} from "./verifyAuditLog.js";
+export {
+  AUDIT_SEAL_DOC_TYPE,
+  type AuditSealBundle,
+  buildAuditSealBundle,
+  serializeAuditSealBundle,
+} from "./sealAuditBundle.js";

package/src/audit/sealAuditBundle.ts

@@ -0,0 +1,90 @@
+// Sealed audit bundle (ADR 0013, proof model ii).
+//
+// A contemporaneous, self-contained snapshot of a transaction's certified
+// audit log. Built from a getCertifiedTransactionLog response (a query, so the
+// subnet certificate is present) — typically at completion, and regenerable on
+// demand. The bundle verifies offline against the IC root key, even if
+// PropXchain is gone: a forensic verifier re-runs verifyCertifiedAuditLog with
+// a relaxed freshness window.
+//
+// Persistence: the serialized bundle is stored on-chain in document_storage
+// (docType "audit_seal") per ADR 0008. That upload uses the existing document
+// upload path and is the caller's step — buildAuditSealBundle only produces the
+// bytes (no document bodies are embedded; events reference any documents by
+// hash only).
+
+import { type CertifiedTransactionLog } from "./verifyAuditLog.js";
+
+export const AUDIT_SEAL_DOC_TYPE = "audit_seal";
+
+interface SerializableAuditEvent {
+  eventId: string;
+  transactionId: string;
+  eventType: string;
+  timestamp: string;
+  caller: string;
+  details: string;
+  metadata: string | null;
+}
+
+export interface AuditSealBundle {
+  version: 1;
+  canisterId: string;
+  transactionId: string;
+  /** Client capture time (ISO). The authoritative time is inside the certificate. */
+  capturedAt: string;
+  events: SerializableAuditEvent[];
+  headHashHex: string;
+  certificateB64: string;
+  witnessB64: string;
+}
+
+function toHex(bytes: Uint8Array): string {
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+function toB64(bytes: Uint8Array): string {
+  // Browser + Node (>=20) both expose btoa; build a binary string first.
+  let binary = "";
+  for (const b of bytes) binary += String.fromCharCode(b);
+  return btoa(binary);
+}
+
+/**
+ * Build a sealed, serializable proof bundle from a certified log response.
+ * Throws if the response carries no certificate (nothing to seal).
+ */
+export function buildAuditSealBundle(args: {
+  canisterId: string;
+  transactionId: string;
+  capturedAt: string;
+  log: CertifiedTransactionLog;
+}): AuditSealBundle {
+  const { canisterId, transactionId, capturedAt, log } = args;
+  if (log.certificate.length === 0) {
+    throw new Error("cannot seal: certified log response has no certificate");
+  }
+  return {
+    version: 1,
+    canisterId,
+    transactionId,
+    capturedAt,
+    events: log.events.map((e) => ({
+      eventId: e.eventId.toString(),
+      transactionId: e.transactionId,
+      eventType: e.eventType,
+      timestamp: e.timestamp.toString(),
+      caller: e.caller.toText(),
+      details: e.details,
+      metadata: e.metadata.length === 0 ? null : e.metadata[0],
+    })),
+    headHashHex: toHex(log.headHash),
+    certificateB64: toB64(log.certificate[0]),
+    witnessB64: toB64(log.witness),
+  };
+}
+
+/** Serialize a bundle to bytes for on-chain storage (document_storage). */
+export function serializeAuditSealBundle(bundle: AuditSealBundle): Uint8Array {
+  return new TextEncoder().encode(JSON.stringify(bundle));
+}

package/src/audit/verifyAuditLog.ts

@@ -0,0 +1,168 @@
+// Verifier for the certified per-transaction audit log (ADR 0013).
+//
+// Proves a transaction's audit trail is genuine canister state against the IC
+// root key, trusting no part of PropXchain:
+//   1. verify the subnet certificate + Merkle witness;
+//   2. read the certified headHash for the transaction from the witness tree;
+//   3. confirm the response's stated head matches the certified head;
+//   4. recompute the chain from the events and confirm it matches.
+//
+// Uses the @dfinity/* family (agent, principal, certificate-verification)
+// throughout — that is the lineage certificate-verification depends on, so the
+// HashTree/Principal types line up. The rest of core-client uses @icp-sdk;
+// this leaf module's boundary is plain Uint8Array/string, so the split is
+// contained.
+//
+// Live verification keeps the certificate-freshness window tight. Forensic
+// verification of a sealed historical bundle (ADR 0013, proof model ii)
+// relaxes it by design — the bundle proves a fact as-of the certificate's
+// /time, not a current one.
+
+import { lookup_path, lookupResultToBuffer } from "@dfinity/agent";
+import type { HashTree } from "@dfinity/agent";
+import { Principal } from "@dfinity/principal";
+import { type CertifiedAuditEvent, recomputeHeadHash } from "./auditChain.js";
+
+// @dfinity/certificate-verification ships an ESM .d.ts (named exports, no
+// default) but a UMD .cjs as `main`. TS sees ESM; Node's loader sees CJS. A
+// static named import typechecks but fails at runtime; a default import does
+// the reverse. Load it dynamically and fall back across both shapes so the
+// verifier works in Node, browser bundlers, and typecheck alike.
+interface VerifyCertificationParams {
+  canisterId: Principal;
+  encodedCertificate: ArrayBuffer;
+  encodedTree: ArrayBuffer;
+  rootKey: ArrayBuffer;
+  maxCertificateTimeOffsetMs: number;
+}
+type VerifyCertificationFn = (p: VerifyCertificationParams) => Promise<HashTree>;
+
+let cachedVerify: VerifyCertificationFn | undefined;
+async function loadVerifyCertification(): Promise<VerifyCertificationFn> {
+  if (cachedVerify) return cachedVerify;
+  const mod = (await import("@dfinity/certificate-verification")) as unknown as {
+    verifyCertification?: VerifyCertificationFn;
+    default?: { verifyCertification?: VerifyCertificationFn };
+  };
+  const fn = mod.verifyCertification ?? mod.default?.verifyCertification;
+  if (!fn) {
+    throw new Error(
+      "verifyCertification not found in @dfinity/certificate-verification",
+    );
+  }
+  cachedVerify = fn;
+  return fn;
+}
+
+/** Decoded ledger_manager.getCertifiedTransactionLog response. */
+export interface CertifiedTransactionLog {
+  events: CertifiedAuditEvent[];
+  headHash: Uint8Array;
+  certificate: [] | [Uint8Array];
+  witness: Uint8Array;
+}
+
+export interface VerifyResult {
+  verified: boolean;
+  reason?: string;
+  eventCount: number;
+}
+
+export interface VerifyOptions {
+  canisterId: string;
+  /** IC root public key — the mainnet constant, or `agent.rootKey` for local. */
+  rootKey: Uint8Array;
+  transactionId: string;
+  log: CertifiedTransactionLog;
+  /**
+   * Certificate freshness window. Omit for live verification (5 min). For
+   * forensic verification of a sealed bundle, pass a large value (e.g.
+   * Number.MAX_SAFE_INTEGER) to accept a historical certificate.
+   */
+  maxCertificateTimeOffsetMs?: number;
+}
+
+const FIVE_MINUTES_MS = 5 * 60 * 1000;
+
+function toArrayBuffer(u8: Uint8Array): ArrayBuffer {
+  const copy = new Uint8Array(u8.length);
+  copy.set(u8);
+  return copy.buffer;
+}
+
+function equalBytes(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a[i] ^ b[i];
+  return diff === 0;
+}
+
+export async function verifyCertifiedAuditLog(
+  opts: VerifyOptions,
+): Promise<VerifyResult> {
+  const { log, transactionId } = opts;
+  const eventCount = log.events.length;
+
+  if (log.certificate.length === 0) {
+    return { verified: false, reason: "no certificate in response", eventCount };
+  }
+
+  // 1. Verify the subnet certificate + witness against the IC root key.
+  let tree: HashTree;
+  try {
+    const verifyCertification = await loadVerifyCertification();
+    tree = await verifyCertification({
+      canisterId: Principal.fromText(opts.canisterId),
+      encodedCertificate: toArrayBuffer(log.certificate[0]),
+      encodedTree: toArrayBuffer(log.witness),
+      rootKey: toArrayBuffer(opts.rootKey),
+      maxCertificateTimeOffsetMs:
+        opts.maxCertificateTimeOffsetMs ?? FIVE_MINUTES_MS,
+    });
+  } catch (err) {
+    return {
+      verified: false,
+      reason: `certificate verification failed: ${String(err)}`,
+      eventCount,
+    };
+  }
+
+  // 2. Read the certified headHash for this transaction from the witness tree.
+  // The path segment is the UTF-8 bytes of the transactionId — exactly the key
+  // ledger_manager certified (Text.encodeUtf8(transactionId)).
+  const lookup = lookup_path(
+    [toArrayBuffer(new TextEncoder().encode(transactionId))],
+    tree,
+  );
+  const certifiedBuf = lookupResultToBuffer(lookup);
+  if (!certifiedBuf) {
+    return {
+      verified: false,
+      reason: "transaction head not present in certified tree",
+      eventCount,
+    };
+  }
+  const certifiedHead = new Uint8Array(certifiedBuf);
+
+  // 3. The response's stated head must match the certified value.
+  if (!equalBytes(certifiedHead, log.headHash)) {
+    return {
+      verified: false,
+      reason: "response headHash does not match certified value",
+      eventCount,
+    };
+  }
+
+  // 4. The head recomputed from the events must match the certified head.
+  const recomputed = await recomputeHeadHash(log.events);
+  if (!equalBytes(recomputed, certifiedHead)) {
+    return {
+      verified: false,
+      reason:
+        "recomputed chain head does not match certified head — events tampered",
+      eventCount,
+    };
+  }
+
+  return { verified: true, eventCount };
+}

package/src/index.ts

@@ -10,6 +10,19 @@ export {
   type CoreClientErrorCode,
 } from "./errors.js";
 export { withRetry, type RetryOptions } from "./retry.js";
+export {
+  type CertifiedAuditEvent,
+  encodeAuditEvent,
+  recomputeHeadHash,
+  type CertifiedTransactionLog,
+  type VerifyResult,
+  type VerifyOptions,
+  verifyCertifiedAuditLog,
+  AUDIT_SEAL_DOC_TYPE,
+  type AuditSealBundle,
+  buildAuditSealBundle,
+  serializeAuditSealBundle,
+} from "./audit/index.js";
 export {
   createAuditTrailStub,
   createAgentHarnessStub,