@forestrie/receipt-verify 0.8.2 → 0.9.0

package/dist/index.d.ts

@@ -42,4 +42,19 @@ export type { LocatedLeaf } from "./find-grant-leaf.js";
 /** Re-exported so callers of findGrantLeafInMassif can catch it (FOR-344). */
 export { MissingIndexError } from "@forestrie/merklelog";
 export { accumulatorPayload, checkpointConsistencyProof, computeCheckpointAccumulator, verifyCheckpointChain, type CheckpointChainLink, type CheckpointChainResult, type CheckpointConsistencyProof, } from "./checkpoint-chain.js";
+/**
+ * Univocity leaf commitment hash. Was CLI-private (forestrie-cli's own
+ * mirror, "hoist to the library when the FOR-297 multi-hop resolver lands");
+ * exported here as of plan-2607-34 slice 02 Part B so consumers stop
+ * duplicating it.
+ */
+export { univocityLeafHash } from "./leaf-commitment.js";
+/**
+ * Known-accumulator snapshot (FOR-297 D5): verify a receipt against a
+ * caller-supplied on-chain accumulator read, fully offline. Hoisted from
+ * forestrie-cli (plan-2607-34 slice 02 Part B) — see known-accumulator.ts
+ * for the trust model and what this package does NOT do (fetch the
+ * snapshot over RPC, or proof-path-extend a stale one via massif nodes).
+ */
+export { assertSnapshotBinding, decodeKnownAccumulator, encodeKnownAccumulator, verifyReceiptOfflineAgainstKnownAccumulator, type KnownAccumulator, } from "./known-accumulator.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,4BAA4B,CAAC;AACpC,oFAAoF;AACpF,YAAY,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACjD,YAAY,EAAE,8BAA8B,EAAE,MAAM,mCAAmC,CAAC;AACxF,YAAY,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AACnF,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EACV,wBAAwB,EACxB,uBAAuB,EACvB,eAAe,EACf,gBAAgB,GACjB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,wBAAwB,EACxB,mBAAmB,EACnB,sBAAsB,EACtB,mBAAmB,EACnB,eAAe,GAChB,MAAM,4BAA4B,CAAC;AACpC,+EAA+E;AAC/E,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EACV,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAC9B;;;GAGG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,0BAA0B,EAAE,MAAM,qCAAqC,CAAC;AACjF,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AACzE;;;;GAIG;AACH,OAAO,EACL,iCAAiC,EACjC,4BAA4B,GAC7B,MAAM,mCAAmC,CAAC;AAC3C,YAAY,EACV,sCAAsC,EACtC,iCAAiC,GAClC,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,YAAY,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AAC7E,yEAAyE;AACzE,OAAO,EAAE,qCAAqC,EAAE,MAAM,6BAA6B,CAAC;AACpF,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAE3E,0EAA0E;AAC1E,OAAO,EACL,cAAc,EACd,iDAAiD,GAClD,MAAM,2CAA2C,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAC;AAC7E,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,6EAA6E;AAC7E,OAAO,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAC;AACrE,oEAAoE;AACpE,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,YAAY,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,8EAA8E;AAC9E,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EACL,kBAAkB,EAClB,0BAA0B,EAC1B,4BAA4B,EAC5B,qBAAqB,EACrB,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,0BAA0B,GAChC,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,4BAA4B,CAAC;AACpC,oFAAoF;AACpF,YAAY,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACjD,YAAY,EAAE,8BAA8B,EAAE,MAAM,mCAAmC,CAAC;AACxF,YAAY,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AACnF,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EACV,wBAAwB,EACxB,uBAAuB,EACvB,eAAe,EACf,gBAAgB,GACjB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,wBAAwB,EACxB,mBAAmB,EACnB,sBAAsB,EACtB,mBAAmB,EACnB,eAAe,GAChB,MAAM,4BAA4B,CAAC;AACpC,+EAA+E;AAC/E,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EACV,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAC9B;;;GAGG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,0BAA0B,EAAE,MAAM,qCAAqC,CAAC;AACjF,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AACzE;;;;GAIG;AACH,OAAO,EACL,iCAAiC,EACjC,4BAA4B,GAC7B,MAAM,mCAAmC,CAAC;AAC3C,YAAY,EACV,sCAAsC,EACtC,iCAAiC,GAClC,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,YAAY,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AAC7E,yEAAyE;AACzE,OAAO,EAAE,qCAAqC,EAAE,MAAM,6BAA6B,CAAC;AACpF,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAE3E,0EAA0E;AAC1E,OAAO,EACL,cAAc,EACd,iDAAiD,GAClD,MAAM,2CAA2C,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAC;AAC7E,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,6EAA6E;AAC7E,OAAO,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAC;AACrE,oEAAoE;AACpE,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,YAAY,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,8EAA8E;AAC9E,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EACL,kBAAkB,EAClB,0BAA0B,EAC1B,4BAA4B,EAC5B,qBAAqB,EACrB,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,0BAA0B,GAChC,MAAM,uBAAuB,CAAC;AAC/B;;;;;GAKG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD;;;;;;GAMG;AACH,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,sBAAsB,EACtB,2CAA2C,EAC3C,KAAK,gBAAgB,GACtB,MAAM,wBAAwB,CAAC"}

package/dist/index.js

@@ -31,3 +31,18 @@ export { findGrantLeafInMassif } from "./find-grant-leaf.js";
 /** Re-exported so callers of findGrantLeafInMassif can catch it (FOR-344). */
 export { MissingIndexError } from "@forestrie/merklelog";
 export { accumulatorPayload, checkpointConsistencyProof, computeCheckpointAccumulator, verifyCheckpointChain, } from "./checkpoint-chain.js";
+/**
+ * Univocity leaf commitment hash. Was CLI-private (forestrie-cli's own
+ * mirror, "hoist to the library when the FOR-297 multi-hop resolver lands");
+ * exported here as of plan-2607-34 slice 02 Part B so consumers stop
+ * duplicating it.
+ */
+export { univocityLeafHash } from "./leaf-commitment.js";
+/**
+ * Known-accumulator snapshot (FOR-297 D5): verify a receipt against a
+ * caller-supplied on-chain accumulator read, fully offline. Hoisted from
+ * forestrie-cli (plan-2607-34 slice 02 Part B) — see known-accumulator.ts
+ * for the trust model and what this package does NOT do (fetch the
+ * snapshot over RPC, or proof-path-extend a stale one via massif nodes).
+ */
+export { assertSnapshotBinding, decodeKnownAccumulator, encodeKnownAccumulator, verifyReceiptOfflineAgainstKnownAccumulator, } from "./known-accumulator.js";

package/dist/known-accumulator.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Known-accumulator snapshot (FOR-297 D5): a cached, auditable chain read of
+ * a Univocity log's `logState`, letting chain-anchored verification run
+ * fully offline. Hoisted from `forestrie-cli/src/lib/verify-known-accumulator.ts`
+ * (plan-2607-34 slice 02 Part B) so the CLI and any other consumer — e2e
+ * harnesses, a future browser relying party — share one implementation
+ * instead of duplicating this crypto per caller.
+ *
+ * Trust model (freshness / split-view): `--rpc-url` was never trust-free —
+ * the RPC provider is itself a trusted chain reader. The snapshot makes that
+ * trust explicit, portable, and cacheable. It binds `(chainId, univocity,
+ * logId, size, block)` so anyone with RPC can re-run the read at that block
+ * and confirm or disprove it — auditable, falsifiable trust, unlike a bare
+ * known key.
+ *
+ * Staleness limits coverage, never validity: the contract's consistency
+ * gating makes every anchored state a committed prefix of every later one,
+ * so a peak match at snapshot size N proves inclusion at N and forever
+ * after. Entries newer than the snapshot fail closed with a refresh hint.
+ *
+ * This module is pure — no network, no `node:*` imports (browser-safety
+ * enforced by `tools/check-browser-safe.mjs`). Fetching the snapshot itself
+ * over RPC is the caller's concern (forestrie-cli `fetch-accumulator`, or an
+ * equivalent reader — see `verifyReceiptOfflineAgainstKnownAccumulator`'s
+ * doc for why that stays out of this package).
+ *
+ * NEVER source the snapshot unauthenticated from the same store as the tiles
+ * (the log operator's massif/checkpoint store) — that silently re-internalises
+ * the operator trust this anchor exists to remove.
+ */
+import type { ReceiptVerifyResult } from "./receipt-verify-result.js";
+export type KnownAccumulator = {
+    version: number;
+    chainId: bigint;
+    /** Univocity contract address (20 bytes). */
+    univocity: Uint8Array;
+    /** Contract log id (32 bytes, UUID zero-padded on the left). */
+    logId: Uint8Array;
+    /** Anchored MMR size at the snapshot block. */
+    size: bigint;
+    /** Anchored accumulator peaks (32 bytes each), contract order. */
+    accumulator: Uint8Array[];
+    blockNumber: bigint;
+    /** Block hash of the read (32 bytes) — the falsifiability handle. */
+    blockHash: Uint8Array;
+};
+/** Encode a snapshot as canonical CBOR (RFC 8949 §4.2 — hard policy). */
+export declare function encodeKnownAccumulator(snapshot: KnownAccumulator): Uint8Array;
+/** Strict decode + shape validation of a snapshot artifact. */
+export declare function decodeKnownAccumulator(bytes: Uint8Array): KnownAccumulator;
+/**
+ * Reject a snapshot whose binding does not match the caller's stated target
+ * BEFORE any peak math — a snapshot for the wrong log or contract must never
+ * be silently accepted as an anchor. `univocity`/`logId` are raw
+ * caller-supplied strings (a `0x`-address, a UUID, or hex id) — normalized
+ * here so callers don't have to.
+ */
+export declare function assertSnapshotBinding(snapshot: KnownAccumulator, opts: {
+    univocity?: string | undefined;
+    logId?: string | undefined;
+}): void;
+/**
+ * Offline check: is the receipt's peak one of the known-accumulator's
+ * anchored peaks? Covers the two network-free cases from
+ * `forestrie-cli`'s `checkReceiptAnchoredToSnapshot`:
+ *
+ * 1. Fail closed when the receipt's leaf postdates the snapshot (refresh).
+ * 2. Exact peak match: the recomputed receipt peak is still a snapshot peak.
+ *
+ * Proof-path extension for stale snapshots (case 3 — needs a local massif
+ * blob) stays CLI-only for now; it is a bigger, file-shaped input this
+ * package's pure-bytes API doesn't take today. A receipt whose snapshot
+ * covers it but isn't an exact peak returns `peak_not_in_known_accumulator`
+ * — honest about not having tried extension, not a false negative dressed
+ * up as one.
+ *
+ * The live RPC read that produces `accumulator`/`size` stays the caller's
+ * concern (this package is pure — no network, browser-safety enforced by
+ * `tools/check-browser-safe.mjs`); see `system-testing/src/onchain-logstate.ts`
+ * or `forestrie-cli fetch-accumulator` for two independent, viem-free
+ * readers (`fetch()` + manual ABI decode of `logState(bytes32)`).
+ */
+export declare function verifyReceiptOfflineAgainstKnownAccumulator(input: {
+    receiptCbor: Uint8Array;
+    idtimestampBe8: Uint8Array;
+    /** Leaf ContentHash: SHA-256(payload) or the grant commitment hash. */
+    inner: Uint8Array;
+    /** Trusted accumulator peaks at `size`, contract order. */
+    accumulator: Uint8Array[];
+    /** Anchored MMR size at the snapshot. */
+    size: bigint;
+}): Promise<ReceiptVerifyResult>;
+//# sourceMappingURL=known-accumulator.d.ts.map

package/dist/known-accumulator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"known-accumulator.d.ts","sourceRoot":"","sources":["../src/known-accumulator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAWH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAoCtE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,SAAS,EAAE,UAAU,CAAC;IACtB,gEAAgE;IAChE,KAAK,EAAE,UAAU,CAAC;IAClB,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,SAAS,EAAE,UAAU,CAAC;CACvB,CAAC;AAEF,yEAAyE;AACzE,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,UAAU,CAa7E;AAgBD,+DAA+D;AAC/D,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,UAAU,GAAG,gBAAgB,CAgC1E;AAMD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,gBAAgB,EAC1B,IAAI,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GACnE,IAAI,CAiBN;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,2CAA2C,CAAC,KAAK,EAAE;IACvE,WAAW,EAAE,UAAU,CAAC;IACxB,cAAc,EAAE,UAAU,CAAC;IAC3B,uEAAuE;IACvE,KAAK,EAAE,UAAU,CAAC;IAClB,2DAA2D;IAC3D,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CAAC,mBAAmB,CAAC,CA4C/B"}

package/dist/known-accumulator.js

@@ -0,0 +1,213 @@
+/**
+ * Known-accumulator snapshot (FOR-297 D5): a cached, auditable chain read of
+ * a Univocity log's `logState`, letting chain-anchored verification run
+ * fully offline. Hoisted from `forestrie-cli/src/lib/verify-known-accumulator.ts`
+ * (plan-2607-34 slice 02 Part B) so the CLI and any other consumer — e2e
+ * harnesses, a future browser relying party — share one implementation
+ * instead of duplicating this crypto per caller.
+ *
+ * Trust model (freshness / split-view): `--rpc-url` was never trust-free —
+ * the RPC provider is itself a trusted chain reader. The snapshot makes that
+ * trust explicit, portable, and cacheable. It binds `(chainId, univocity,
+ * logId, size, block)` so anyone with RPC can re-run the read at that block
+ * and confirm or disprove it — auditable, falsifiable trust, unlike a bare
+ * known key.
+ *
+ * Staleness limits coverage, never validity: the contract's consistency
+ * gating makes every anchored state a committed prefix of every later one,
+ * so a peak match at snapshot size N proves inclusion at N and forever
+ * after. Entries newer than the snapshot fail closed with a refresh hint.
+ *
+ * This module is pure — no network, no `node:*` imports (browser-safety
+ * enforced by `tools/check-browser-safe.mjs`). Fetching the snapshot itself
+ * over RPC is the caller's concern (forestrie-cli `fetch-accumulator`, or an
+ * equivalent reader — see `verifyReceiptOfflineAgainstKnownAccumulator`'s
+ * doc for why that stays out of this package).
+ *
+ * NEVER source the snapshot unauthenticated from the same store as the tiles
+ * (the log operator's massif/checkpoint store) — that silently re-internalises
+ * the operator trust this anchor exists to remove.
+ */
+import { decodeCborDeterministic, encodeCborDeterministic, } from "@forestrie/encoding";
+import { calculateRoot } from "@forestrie/merklelog";
+import { normalizeHexAddress } from "@forestrie/chain-rpc";
+import { parseReceipt } from "./parse-receipt.js";
+import { univocityLeafHash } from "./leaf-commitment.js";
+import { SubtleHasher } from "./subtle-hasher.js";
+/**
+ * 16/32-byte hex or UUID log id -> the 32-byte contract key (UUID in the low
+ * bytes, zero-padded on the left — matches Univocity's `ToContractBytes32`).
+ * Small, pure, intentionally duplicated from `forestrie-cli`'s copy (same
+ * tolerance as this file's local `bytesEqual` — not security-sensitive
+ * enough to force a shared-utility package for a six-line formatter).
+ */
+function toContractLogId(logId) {
+    const hex = logId.replace(/-/g, "").replace(/^0x/, "").toLowerCase();
+    if (!/^[0-9a-f]{32}$/.test(hex) && !/^[0-9a-f]{64}$/.test(hex)) {
+        throw new Error(`log id must be a UUID or 16/32-byte hex id, got '${logId}'`);
+    }
+    return "0x" + hex.padStart(64, "0");
+}
+function bytesEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let x = 0;
+    for (let i = 0; i < a.length; i++)
+        x |= a[i] ^ b[i];
+    return x === 0;
+}
+/** CBOR map labels for the snapshot artifact (strict RFC 8949 §4.2). */
+const LABEL_VERSION = 1;
+const LABEL_CHAIN_ID = 2;
+const LABEL_UNIVOCITY = 3;
+const LABEL_LOG_ID = 4;
+const LABEL_SIZE = 5;
+const LABEL_ACCUMULATOR = 6;
+const LABEL_BLOCK_NUMBER = 7;
+const LABEL_BLOCK_HASH = 8;
+const SNAPSHOT_VERSION = 1;
+/** Encode a snapshot as canonical CBOR (RFC 8949 §4.2 — hard policy). */
+export function encodeKnownAccumulator(snapshot) {
+    return encodeCborDeterministic(new Map([
+        [LABEL_VERSION, snapshot.version],
+        [LABEL_CHAIN_ID, snapshot.chainId],
+        [LABEL_UNIVOCITY, snapshot.univocity],
+        [LABEL_LOG_ID, snapshot.logId],
+        [LABEL_SIZE, snapshot.size],
+        [LABEL_ACCUMULATOR, snapshot.accumulator],
+        [LABEL_BLOCK_NUMBER, snapshot.blockNumber],
+        [LABEL_BLOCK_HASH, snapshot.blockHash],
+    ]));
+}
+function asBigint(v, what) {
+    if (typeof v === "bigint")
+        return v;
+    if (typeof v === "number" && Number.isSafeInteger(v) && v >= 0)
+        return BigInt(v);
+    throw new Error(`known accumulator: ${what} must be an unsigned integer`);
+}
+function asBytes(v, length, what) {
+    if (!(v instanceof Uint8Array) || v.length !== length) {
+        throw new Error(`known accumulator: ${what} must be ${length} bytes`);
+    }
+    return v;
+}
+/** Strict decode + shape validation of a snapshot artifact. */
+export function decodeKnownAccumulator(bytes) {
+    let decoded;
+    try {
+        decoded = decodeCborDeterministic(bytes);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`known accumulator is not canonical CBOR: ${message}`);
+    }
+    if (!(decoded instanceof Map)) {
+        throw new Error("known accumulator must be a CBOR map");
+    }
+    const version = Number(asBigint(decoded.get(LABEL_VERSION), "version"));
+    if (version !== SNAPSHOT_VERSION) {
+        throw new Error(`known accumulator version ${version} not supported`);
+    }
+    const accRaw = decoded.get(LABEL_ACCUMULATOR);
+    if (!Array.isArray(accRaw)) {
+        throw new Error("known accumulator: accumulator must be an array");
+    }
+    const accumulator = accRaw.map((p, i) => asBytes(p, 32, `accumulator peak ${i}`));
+    return {
+        version,
+        chainId: asBigint(decoded.get(LABEL_CHAIN_ID), "chainId"),
+        univocity: asBytes(decoded.get(LABEL_UNIVOCITY), 20, "univocity"),
+        logId: asBytes(decoded.get(LABEL_LOG_ID), 32, "logId"),
+        size: asBigint(decoded.get(LABEL_SIZE), "size"),
+        accumulator,
+        blockNumber: asBigint(decoded.get(LABEL_BLOCK_NUMBER), "blockNumber"),
+        blockHash: asBytes(decoded.get(LABEL_BLOCK_HASH), 32, "blockHash"),
+    };
+}
+function bytesToHex(bytes) {
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+/**
+ * Reject a snapshot whose binding does not match the caller's stated target
+ * BEFORE any peak math — a snapshot for the wrong log or contract must never
+ * be silently accepted as an anchor. `univocity`/`logId` are raw
+ * caller-supplied strings (a `0x`-address, a UUID, or hex id) — normalized
+ * here so callers don't have to.
+ */
+export function assertSnapshotBinding(snapshot, opts) {
+    if (opts.univocity !== undefined) {
+        const given = normalizeHexAddress(opts.univocity);
+        if (given === null || given !== bytesToHex(snapshot.univocity)) {
+            throw new Error(`known accumulator is bound to univocity 0x${bytesToHex(snapshot.univocity)}, not --univocity ${opts.univocity}`);
+        }
+    }
+    if (opts.logId !== undefined) {
+        const given = toContractLogId(opts.logId).slice(2);
+        if (given !== bytesToHex(snapshot.logId)) {
+            throw new Error(`known accumulator is bound to log 0x${bytesToHex(snapshot.logId)}, not --log-id ${opts.logId}`);
+        }
+    }
+}
+/**
+ * Offline check: is the receipt's peak one of the known-accumulator's
+ * anchored peaks? Covers the two network-free cases from
+ * `forestrie-cli`'s `checkReceiptAnchoredToSnapshot`:
+ *
+ * 1. Fail closed when the receipt's leaf postdates the snapshot (refresh).
+ * 2. Exact peak match: the recomputed receipt peak is still a snapshot peak.
+ *
+ * Proof-path extension for stale snapshots (case 3 — needs a local massif
+ * blob) stays CLI-only for now; it is a bigger, file-shaped input this
+ * package's pure-bytes API doesn't take today. A receipt whose snapshot
+ * covers it but isn't an exact peak returns `peak_not_in_known_accumulator`
+ * — honest about not having tried extension, not a false negative dressed
+ * up as one.
+ *
+ * The live RPC read that produces `accumulator`/`size` stays the caller's
+ * concern (this package is pure — no network, browser-safety enforced by
+ * `tools/check-browser-safe.mjs`); see `system-testing/src/onchain-logstate.ts`
+ * or `forestrie-cli fetch-accumulator` for two independent, viem-free
+ * readers (`fetch()` + manual ABI decode of `logState(bytes32)`).
+ */
+export async function verifyReceiptOfflineAgainstKnownAccumulator(input) {
+    let parsed;
+    try {
+        parsed = parseReceipt(input.receiptCbor);
+    }
+    catch {
+        return { ok: false, stage: "parse", reason: "receipt_malformed" };
+    }
+    const leafIdx = parsed.proof.leafIndex !== undefined
+        ? parsed.proof.leafIndex
+        : parsed.proof.mmrIndex;
+    // 1. Newer-than-snapshot fails CLOSED — staleness limits coverage, never
+    // validity, so the remedy is a refresh, not a pass.
+    if (leafIdx >= input.size) {
+        return {
+            ok: false,
+            stage: "signature",
+            reason: "receipt_newer_than_known_accumulator",
+        };
+    }
+    let recomputedPeak;
+    if (parsed.explicitPeak !== null) {
+        recomputedPeak = parsed.explicitPeak;
+    }
+    else {
+        const hasher = new SubtleHasher();
+        const leafHash = await univocityLeafHash(input.idtimestampBe8, input.inner);
+        recomputedPeak = await calculateRoot(hasher, leafHash, parsed.proof, leafIdx);
+    }
+    // 2. Exact peak match — receipt state is a snapshot-covered accumulator.
+    for (const peak of input.accumulator) {
+        if (bytesEqual(recomputedPeak, peak)) {
+            return { ok: true, stage: "binding" };
+        }
+    }
+    return {
+        ok: false,
+        stage: "signature",
+        reason: "peak_not_in_known_accumulator",
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forestrie/receipt-verify",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "license": "MIT",
   "type": "module",
   "description": "Offline SCITT grant receipt verification (ADR-0045)",
@@ -29,6 +29,7 @@
   "dependencies": {
     "@noble/hashes": "^1.7.1",
     "@forestrie/merklelog": "0.3.0",
+    "@forestrie/chain-rpc": "0.1.1",
     "@forestrie/encoding": "0.5.0"
   },
   "devDependencies": {

package/src/index.ts

@@ -78,3 +78,24 @@ export {
   type CheckpointChainResult,
   type CheckpointConsistencyProof,
 } from "./checkpoint-chain.js";
+/**
+ * Univocity leaf commitment hash. Was CLI-private (forestrie-cli's own
+ * mirror, "hoist to the library when the FOR-297 multi-hop resolver lands");
+ * exported here as of plan-2607-34 slice 02 Part B so consumers stop
+ * duplicating it.
+ */
+export { univocityLeafHash } from "./leaf-commitment.js";
+/**
+ * Known-accumulator snapshot (FOR-297 D5): verify a receipt against a
+ * caller-supplied on-chain accumulator read, fully offline. Hoisted from
+ * forestrie-cli (plan-2607-34 slice 02 Part B) — see known-accumulator.ts
+ * for the trust model and what this package does NOT do (fetch the
+ * snapshot over RPC, or proof-path-extend a stale one via massif nodes).
+ */
+export {
+  assertSnapshotBinding,
+  decodeKnownAccumulator,
+  encodeKnownAccumulator,
+  verifyReceiptOfflineAgainstKnownAccumulator,
+  type KnownAccumulator,
+} from "./known-accumulator.js";

package/src/known-accumulator.ts

@@ -0,0 +1,265 @@
+/**
+ * Known-accumulator snapshot (FOR-297 D5): a cached, auditable chain read of
+ * a Univocity log's `logState`, letting chain-anchored verification run
+ * fully offline. Hoisted from `forestrie-cli/src/lib/verify-known-accumulator.ts`
+ * (plan-2607-34 slice 02 Part B) so the CLI and any other consumer — e2e
+ * harnesses, a future browser relying party — share one implementation
+ * instead of duplicating this crypto per caller.
+ *
+ * Trust model (freshness / split-view): `--rpc-url` was never trust-free —
+ * the RPC provider is itself a trusted chain reader. The snapshot makes that
+ * trust explicit, portable, and cacheable. It binds `(chainId, univocity,
+ * logId, size, block)` so anyone with RPC can re-run the read at that block
+ * and confirm or disprove it — auditable, falsifiable trust, unlike a bare
+ * known key.
+ *
+ * Staleness limits coverage, never validity: the contract's consistency
+ * gating makes every anchored state a committed prefix of every later one,
+ * so a peak match at snapshot size N proves inclusion at N and forever
+ * after. Entries newer than the snapshot fail closed with a refresh hint.
+ *
+ * This module is pure — no network, no `node:*` imports (browser-safety
+ * enforced by `tools/check-browser-safe.mjs`). Fetching the snapshot itself
+ * over RPC is the caller's concern (forestrie-cli `fetch-accumulator`, or an
+ * equivalent reader — see `verifyReceiptOfflineAgainstKnownAccumulator`'s
+ * doc for why that stays out of this package).
+ *
+ * NEVER source the snapshot unauthenticated from the same store as the tiles
+ * (the log operator's massif/checkpoint store) — that silently re-internalises
+ * the operator trust this anchor exists to remove.
+ */
+
+import {
+  decodeCborDeterministic,
+  encodeCborDeterministic,
+} from "@forestrie/encoding";
+import { calculateRoot, type Proof } from "@forestrie/merklelog";
+import { normalizeHexAddress } from "@forestrie/chain-rpc";
+import { parseReceipt } from "./parse-receipt.js";
+import { univocityLeafHash } from "./leaf-commitment.js";
+import { SubtleHasher } from "./subtle-hasher.js";
+import type { ReceiptVerifyResult } from "./receipt-verify-result.js";
+
+/**
+ * 16/32-byte hex or UUID log id -> the 32-byte contract key (UUID in the low
+ * bytes, zero-padded on the left — matches Univocity's `ToContractBytes32`).
+ * Small, pure, intentionally duplicated from `forestrie-cli`'s copy (same
+ * tolerance as this file's local `bytesEqual` — not security-sensitive
+ * enough to force a shared-utility package for a six-line formatter).
+ */
+function toContractLogId(logId: string): string {
+  const hex = logId.replace(/-/g, "").replace(/^0x/, "").toLowerCase();
+  if (!/^[0-9a-f]{32}$/.test(hex) && !/^[0-9a-f]{64}$/.test(hex)) {
+    throw new Error(`log id must be a UUID or 16/32-byte hex id, got '${logId}'`);
+  }
+  return "0x" + hex.padStart(64, "0");
+}
+
+function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  let x = 0;
+  for (let i = 0; i < a.length; i++) x |= a[i]! ^ b[i]!;
+  return x === 0;
+}
+
+/** CBOR map labels for the snapshot artifact (strict RFC 8949 §4.2). */
+const LABEL_VERSION = 1;
+const LABEL_CHAIN_ID = 2;
+const LABEL_UNIVOCITY = 3;
+const LABEL_LOG_ID = 4;
+const LABEL_SIZE = 5;
+const LABEL_ACCUMULATOR = 6;
+const LABEL_BLOCK_NUMBER = 7;
+const LABEL_BLOCK_HASH = 8;
+
+const SNAPSHOT_VERSION = 1;
+
+export type KnownAccumulator = {
+  version: number;
+  chainId: bigint;
+  /** Univocity contract address (20 bytes). */
+  univocity: Uint8Array;
+  /** Contract log id (32 bytes, UUID zero-padded on the left). */
+  logId: Uint8Array;
+  /** Anchored MMR size at the snapshot block. */
+  size: bigint;
+  /** Anchored accumulator peaks (32 bytes each), contract order. */
+  accumulator: Uint8Array[];
+  blockNumber: bigint;
+  /** Block hash of the read (32 bytes) — the falsifiability handle. */
+  blockHash: Uint8Array;
+};
+
+/** Encode a snapshot as canonical CBOR (RFC 8949 §4.2 — hard policy). */
+export function encodeKnownAccumulator(snapshot: KnownAccumulator): Uint8Array {
+  return encodeCborDeterministic(
+    new Map<number, unknown>([
+      [LABEL_VERSION, snapshot.version],
+      [LABEL_CHAIN_ID, snapshot.chainId],
+      [LABEL_UNIVOCITY, snapshot.univocity],
+      [LABEL_LOG_ID, snapshot.logId],
+      [LABEL_SIZE, snapshot.size],
+      [LABEL_ACCUMULATOR, snapshot.accumulator],
+      [LABEL_BLOCK_NUMBER, snapshot.blockNumber],
+      [LABEL_BLOCK_HASH, snapshot.blockHash],
+    ]),
+  );
+}
+
+function asBigint(v: unknown, what: string): bigint {
+  if (typeof v === "bigint") return v;
+  if (typeof v === "number" && Number.isSafeInteger(v) && v >= 0)
+    return BigInt(v);
+  throw new Error(`known accumulator: ${what} must be an unsigned integer`);
+}
+
+function asBytes(v: unknown, length: number, what: string): Uint8Array {
+  if (!(v instanceof Uint8Array) || v.length !== length) {
+    throw new Error(`known accumulator: ${what} must be ${length} bytes`);
+  }
+  return v;
+}
+
+/** Strict decode + shape validation of a snapshot artifact. */
+export function decodeKnownAccumulator(bytes: Uint8Array): KnownAccumulator {
+  let decoded: unknown;
+  try {
+    decoded = decodeCborDeterministic(bytes);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`known accumulator is not canonical CBOR: ${message}`);
+  }
+  if (!(decoded instanceof Map)) {
+    throw new Error("known accumulator must be a CBOR map");
+  }
+  const version = Number(asBigint(decoded.get(LABEL_VERSION), "version"));
+  if (version !== SNAPSHOT_VERSION) {
+    throw new Error(`known accumulator version ${version} not supported`);
+  }
+  const accRaw = decoded.get(LABEL_ACCUMULATOR);
+  if (!Array.isArray(accRaw)) {
+    throw new Error("known accumulator: accumulator must be an array");
+  }
+  const accumulator = accRaw.map((p, i) =>
+    asBytes(p, 32, `accumulator peak ${i}`),
+  );
+  return {
+    version,
+    chainId: asBigint(decoded.get(LABEL_CHAIN_ID), "chainId"),
+    univocity: asBytes(decoded.get(LABEL_UNIVOCITY), 20, "univocity"),
+    logId: asBytes(decoded.get(LABEL_LOG_ID), 32, "logId"),
+    size: asBigint(decoded.get(LABEL_SIZE), "size"),
+    accumulator,
+    blockNumber: asBigint(decoded.get(LABEL_BLOCK_NUMBER), "blockNumber"),
+    blockHash: asBytes(decoded.get(LABEL_BLOCK_HASH), 32, "blockHash"),
+  };
+}
+
+function bytesToHex(bytes: Uint8Array): string {
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+/**
+ * Reject a snapshot whose binding does not match the caller's stated target
+ * BEFORE any peak math — a snapshot for the wrong log or contract must never
+ * be silently accepted as an anchor. `univocity`/`logId` are raw
+ * caller-supplied strings (a `0x`-address, a UUID, or hex id) — normalized
+ * here so callers don't have to.
+ */
+export function assertSnapshotBinding(
+  snapshot: KnownAccumulator,
+  opts: { univocity?: string | undefined; logId?: string | undefined },
+): void {
+  if (opts.univocity !== undefined) {
+    const given = normalizeHexAddress(opts.univocity);
+    if (given === null || given !== bytesToHex(snapshot.univocity)) {
+      throw new Error(
+        `known accumulator is bound to univocity 0x${bytesToHex(snapshot.univocity)}, not --univocity ${opts.univocity}`,
+      );
+    }
+  }
+  if (opts.logId !== undefined) {
+    const given = toContractLogId(opts.logId).slice(2);
+    if (given !== bytesToHex(snapshot.logId)) {
+      throw new Error(
+        `known accumulator is bound to log 0x${bytesToHex(snapshot.logId)}, not --log-id ${opts.logId}`,
+      );
+    }
+  }
+}
+
+/**
+ * Offline check: is the receipt's peak one of the known-accumulator's
+ * anchored peaks? Covers the two network-free cases from
+ * `forestrie-cli`'s `checkReceiptAnchoredToSnapshot`:
+ *
+ * 1. Fail closed when the receipt's leaf postdates the snapshot (refresh).
+ * 2. Exact peak match: the recomputed receipt peak is still a snapshot peak.
+ *
+ * Proof-path extension for stale snapshots (case 3 — needs a local massif
+ * blob) stays CLI-only for now; it is a bigger, file-shaped input this
+ * package's pure-bytes API doesn't take today. A receipt whose snapshot
+ * covers it but isn't an exact peak returns `peak_not_in_known_accumulator`
+ * — honest about not having tried extension, not a false negative dressed
+ * up as one.
+ *
+ * The live RPC read that produces `accumulator`/`size` stays the caller's
+ * concern (this package is pure — no network, browser-safety enforced by
+ * `tools/check-browser-safe.mjs`); see `system-testing/src/onchain-logstate.ts`
+ * or `forestrie-cli fetch-accumulator` for two independent, viem-free
+ * readers (`fetch()` + manual ABI decode of `logState(bytes32)`).
+ */
+export async function verifyReceiptOfflineAgainstKnownAccumulator(input: {
+  receiptCbor: Uint8Array;
+  idtimestampBe8: Uint8Array;
+  /** Leaf ContentHash: SHA-256(payload) or the grant commitment hash. */
+  inner: Uint8Array;
+  /** Trusted accumulator peaks at `size`, contract order. */
+  accumulator: Uint8Array[];
+  /** Anchored MMR size at the snapshot. */
+  size: bigint;
+}): Promise<ReceiptVerifyResult> {
+  let parsed: { explicitPeak: Uint8Array | null; proof: Proof };
+  try {
+    parsed = parseReceipt(input.receiptCbor);
+  } catch {
+    return { ok: false, stage: "parse", reason: "receipt_malformed" };
+  }
+
+  const leafIdx =
+    parsed.proof.leafIndex !== undefined
+      ? parsed.proof.leafIndex
+      : parsed.proof.mmrIndex!;
+
+  // 1. Newer-than-snapshot fails CLOSED — staleness limits coverage, never
+  // validity, so the remedy is a refresh, not a pass.
+  if (leafIdx >= input.size) {
+    return {
+      ok: false,
+      stage: "signature",
+      reason: "receipt_newer_than_known_accumulator",
+    };
+  }
+
+  let recomputedPeak: Uint8Array;
+  if (parsed.explicitPeak !== null) {
+    recomputedPeak = parsed.explicitPeak;
+  } else {
+    const hasher = new SubtleHasher();
+    const leafHash = await univocityLeafHash(input.idtimestampBe8, input.inner);
+    recomputedPeak = await calculateRoot(hasher, leafHash, parsed.proof, leafIdx);
+  }
+
+  // 2. Exact peak match — receipt state is a snapshot-covered accumulator.
+  for (const peak of input.accumulator) {
+    if (bytesEqual(recomputedPeak, peak)) {
+      return { ok: true, stage: "binding" };
+    }
+  }
+
+  return {
+    ok: false,
+    stage: "signature",
+    reason: "peak_not_in_known_accumulator",
+  };
+}