@forestrie/receipt-verify 3.1.0 → 3.2.0

package/dist/checkpoint-chain-receipt-outcome.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The typed result of {@link verifyReceiptAgainstCheckpointChain}: the
+ * verdict, where it was decided, and everything a reporter needs (folded
+ * links, per-link delegation records, attestation usage).
+ */
+import type { CheckpointChainLink } from "./checkpoint-chain.js";
+import type { CheckpointLinkFailure, CheckpointLinkRecord } from "./checkpoint-link-record.js";
+import type { Ks256AttestationUsage } from "./ks256-attestation-usage.js";
+/**
+ * Where a failing run stopped:
+ * - `input`: the caller's inputs (no root keys, a forest genesis without a
+ *   chain binding).
+ * - `chain`: the checkpoint chain did not fold or a link was refused.
+ * - `parse`: the receipt or idtimestamp did not parse.
+ * - `anchor`: the chain folded but the receipt's leaf-derived peak is in no
+ *   link (`peak_not_in_checkpoint_chain`), or the leaf is past the chain
+ *   (`receipt_newer_than_checkpoint_chain`; refresh, not tamper).
+ * - `delegation`: the receipt matched, but a link covering its leaf was
+ *   signed under an expired certificate (`delegation_expired`).
+ */
+export type CheckpointChainReceiptStage = "input" | "chain" | "parse" | "anchor" | "delegation";
+/** Fields every outcome carries, pass or fail. */
+type OutcomeCommon = {
+    /** The authenticated links (the verified prefix on a chain failure). */
+    links: CheckpointChainLink[];
+    /** Per-link delegation facts, one per authenticated link. */
+    records: CheckpointLinkRecord[];
+    /** Every supplied attestation, as used or unused with a reason. */
+    attestations: Ks256AttestationUsage;
+};
+/** A receipt anchored in a retained checkpoint chain, or why not. */
+export type CheckpointChainReceiptOutcome = (OutcomeCommon & {
+    ok: true;
+    /** Index of the newest link whose accumulator holds the peak. */
+    matchedLink: number;
+    /** Index of the matching peak within that link's accumulator. */
+    matchedPeak: number;
+}) | (OutcomeCommon & {
+    ok: false;
+    stage: CheckpointChainReceiptStage;
+    /**
+     * Stable reason: a {@link CheckpointLinkFailure} reason, a
+     * `CheckpointChainResult` reason prefixed `checkpoint_chain_`, a
+     * receipt parse reason, or one of the anchor/delegation reasons
+     * above.
+     */
+    reason: string;
+    /** Offending link index, for `chain` and `delegation`. */
+    at?: number;
+    /** Human detail from the chain fold, when it failed there. */
+    detail?: string;
+    /** The per-link verifier's refusal, when it caused a `chain` failure. */
+    linkFailure?: CheckpointLinkFailure;
+});
+export {};
+//# sourceMappingURL=checkpoint-chain-receipt-outcome.d.ts.map

package/dist/checkpoint-chain-receipt-outcome.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-chain-receipt-outcome.d.ts","sourceRoot":"","sources":["../src/checkpoint-chain-receipt-outcome.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,KAAK,EACV,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAE1E;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,2BAA2B,GACnC,OAAO,GACP,OAAO,GACP,OAAO,GACP,QAAQ,GACR,YAAY,CAAC;AAEjB,kDAAkD;AAClD,KAAK,aAAa,GAAG;IACnB,wEAAwE;IACxE,KAAK,EAAE,mBAAmB,EAAE,CAAC;IAC7B,6DAA6D;IAC7D,OAAO,EAAE,oBAAoB,EAAE,CAAC;IAChC,mEAAmE;IACnE,YAAY,EAAE,qBAAqB,CAAC;CACrC,CAAC;AAEF,qEAAqE;AACrE,MAAM,MAAM,6BAA6B,GACrC,CAAC,aAAa,GAAG;IACf,EAAE,EAAE,IAAI,CAAC;IACT,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC,GACF,CAAC,aAAa,GAAG;IACf,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE,2BAA2B,CAAC;IACnC;;;;;OAKG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,WAAW,CAAC,EAAE,qBAAqB,CAAC;CACrC,CAAC,CAAC"}

package/dist/checkpoint-chain-receipt-outcome.js

@@ -0,0 +1 @@
+export {};

package/dist/checkpoint-link-record.d.ts

@@ -0,0 +1,69 @@
+/**
+ * What the per-link checkpoint verifier learned about each link of a
+ * retained `.sth` chain ({@link makeCheckpointLinkVerifier}). Consumers
+ * (mcp-verify, forestrie-cli) report these facts; the post-match expiry
+ * check ({@link checkCheckpointLinkExpiry}) reads them.
+ */
+import type { DelegationConstraints } from "./resolve-delegated-verify-key.js";
+/**
+ * Which key verified a link's checkpoint signature, and what vouched for it:
+ *
+ * - `es256-root`: an ES256 root key verified the checkpoint directly (no
+ *   certificate, or the root signed despite one).
+ * - `delegated`: the label-1000 certificate's delegated key verified it, and
+ *   an ES256 root (or passkey root) vouched for the certificate.
+ * - `ks256-root`: the delegated key verified it, and a KS256 root vouched for
+ *   the certificate: by ecrecover, or by an ERC-1271 attestation when
+ *   {@link CheckpointLinkRecord.attestationNeeded}.
+ */
+export type CheckpointLinkVerifiedBy = "es256-root" | "ks256-root" | "delegated";
+/** One authenticated link of a checkpoint chain. */
+export type CheckpointLinkRecord = {
+    /** Position in the supplied checkpoint list (fold order). */
+    index: number;
+    /** The checkpoint's SIGNED tree size (protected label -65933). */
+    signedSize: bigint;
+    /**
+     * The delegation certificate's limits, `null` when the link carries no
+     * certificate or the certificate declares none of labels 3/4/8/9.
+     */
+    constraints: DelegationConstraints | null;
+    verifiedBy: CheckpointLinkVerifiedBy;
+    /**
+     * Hex (no `0x`) of the digest of the attestation this link needed, set
+     * only when {@link attestationNeeded}.
+     */
+    attestationUsed?: string;
+    /**
+     * Index, in the caller's attestation list, of the attestation made for
+     * this link's certificate (digest and signature hash match), whether or
+     * not the link needed it.
+     */
+    attestationIndex?: number;
+    /**
+     * Indexes of attestations made for this link's certificate that were
+     * tried before {@link attestationIndex} and failed their own checks
+     * (address, chain id, magic).
+     */
+    attestationsRejected?: number[];
+    /**
+     * The link verified only because of an attestation: re-resolving its
+     * certificate under the same roots without one fails. Pure and offline.
+     */
+    attestationNeeded: boolean;
+};
+/** Why the per-link verifier refused a link. */
+export type CheckpointLinkFailure = {
+    index: number;
+    /**
+     * `delegation_invalid`, a KS256 reason (`ks256_root_not_recovered`,
+     * `ks256_attestation_*`, `delegation_not_ks256`), `delegation_out_of_range`,
+     * `signature_invalid` or `proof_malformed`.
+     */
+    reason: string;
+    /** As {@link CheckpointLinkRecord.attestationIndex}. */
+    attestationIndex?: number;
+    /** As {@link CheckpointLinkRecord.attestationsRejected}. */
+    attestationsRejected?: number[];
+};
+//# sourceMappingURL=checkpoint-link-record.d.ts.map

package/dist/checkpoint-link-record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-link-record.d.ts","sourceRoot":"","sources":["../src/checkpoint-link-record.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAC;AAE/E;;;;;;;;;;GAUG;AACH,MAAM,MAAM,wBAAwB,GAChC,YAAY,GACZ,YAAY,GACZ,WAAW,CAAC;AAEhB,oDAAoD;AACpD,MAAM,MAAM,oBAAoB,GAAG;IACjC,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,WAAW,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAC1C,UAAU,EAAE,wBAAwB,CAAC;IACrC;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;IAChC;;;OAGG;IACH,iBAAiB,EAAE,OAAO,CAAC;CAC5B,CAAC;AAEF,gDAAgD;AAChD,MAAM,MAAM,qBAAqB,GAAG;IAClC,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,4DAA4D;IAC5D,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;CACjC,CAAC"}

package/dist/checkpoint-link-record.js

@@ -0,0 +1 @@
+export {};

package/dist/checkpoint-link-verifier.d.ts

@@ -0,0 +1,80 @@
+import type { CheckpointLinkFailure, CheckpointLinkRecord } from "./checkpoint-link-record.js";
+import type { Ks256Attestation } from "./ks256-attestation.js";
+import { type DelegationConstraints } from "./resolve-delegated-verify-key.js";
+import { type RootVerifyKey } from "./root-verify-key.js";
+/** The per-link verifier and what it has learned so far. */
+export type CheckpointLinkVerifier = {
+    /** Pass as `verifyCheckpointChain({ verifySignature })`. */
+    verifySignature: (checkpointBytes: Uint8Array, detachedPayload: Uint8Array) => Promise<boolean>;
+    /** One record per link that verified, in fold order. */
+    records: CheckpointLinkRecord[];
+    /** Set when the verifier refused a link; the chain fold stops there. */
+    failure(): CheckpointLinkFailure | undefined;
+};
+/**
+ * Build the per-link signature verifier for {@link verifyCheckpointChain}.
+ *
+ * For each checkpoint, in fold order: resolve its label-1000 certificate
+ * under `rootKeys` (with the attestation made for that certificate, if any),
+ * verify the COSE signature over the FOLDED accumulator (the detached
+ * payload the fold computes, never one read from the checkpoint; ADR-0046),
+ * then enforce the certificate's size bound against the signed size. KS256
+ * roots vouch only for certificates; only ES256 roots may verify a
+ * checkpoint directly.
+ *
+ * The callback must be used for exactly one fold: link indices are the call
+ * count.
+ *
+ * @param opts.rootKeys - ES256 keys and KS256 addresses, from genesis or
+ *   caller-known log keys.
+ * @param opts.attestations - ERC-1271 attestations for KS256 contract
+ *   roots; each certificate takes the one with its digest and signature
+ *   hash ({@link selectKs256Attestation}).
+ * @param opts.forestChainId - The forest genesis chain id every attestation
+ *   must carry; without it a contract root fails
+ *   `ks256_attestation_chain_unbound`.
+ */
+export declare function makeCheckpointLinkVerifier(opts: {
+    rootKeys: readonly RootVerifyKey[];
+    attestations?: readonly Ks256Attestation[] | undefined;
+    forestChainId?: bigint | undefined;
+}): CheckpointLinkVerifier;
+/**
+ * The size bound univocity enforces on a checkpoint, judged from signed
+ * data alone: with `mmrIndex = signedSize > 0 ? signedSize - 1 : 0`, reject
+ * `mmrIndex < mmrStart || mmrIndex > mmrEnd` (`delegationVerifier.sol`,
+ * `_Univocity.sol` passes `claimedSize > 0 ? claimedSize - 1 : 0`).
+ *
+ * @returns `delegation_out_of_range` on either side of the window.
+ */
+export declare function checkCheckpointLinkSizeBound(constraints: DelegationConstraints, signedSize: bigint): {
+    ok: true;
+} | {
+    ok: false;
+    reason: "delegation_out_of_range";
+};
+/**
+ * Expiry, judged only AFTER a receipt matched the chain, when its leaf's
+ * idtimestamp and mmrIndex are bound by the leaf hash and inclusion path
+ * rather than being caller claims. A link whose signed size covers the leaf
+ * (`signedSize > leaf.mmrIndex`) was signed after the leaf was sequenced, so
+ * a leaf time past `expiresAt` proves signing past the key's lifetime. A
+ * link that does not cover the leaf says nothing about its time. Never
+ * wall-clock; no `issuedAt` bound (a certificate is legitimately signed a
+ * few seconds after the leaf it first covers).
+ *
+ * @param records - From {@link makeCheckpointLinkVerifier}.
+ * @param leaf.idtimestamp - The bound leaf's snowflake idtimestamp.
+ * @returns The first offending link as `at`.
+ */
+export declare function checkCheckpointLinkExpiry(records: readonly CheckpointLinkRecord[], leaf: {
+    mmrIndex: bigint;
+    idtimestamp: bigint;
+}): {
+    ok: true;
+} | {
+    ok: false;
+    reason: "delegation_expired";
+    at: number;
+};
+//# sourceMappingURL=checkpoint-link-verifier.d.ts.map

package/dist/checkpoint-link-verifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-link-verifier.d.ts","sourceRoot":"","sources":["../src/checkpoint-link-verifier.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EACV,qBAAqB,EACrB,oBAAoB,EAErB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAGL,KAAK,qBAAqB,EAC3B,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAGhF,4DAA4D;AAC5D,MAAM,MAAM,sBAAsB,GAAG;IACnC,4DAA4D;IAC5D,eAAe,EAAE,CACf,eAAe,EAAE,UAAU,EAC3B,eAAe,EAAE,UAAU,KACxB,OAAO,CAAC,OAAO,CAAC,CAAC;IACtB,wDAAwD;IACxD,OAAO,EAAE,oBAAoB,EAAE,CAAC;IAChC,wEAAwE;IACxE,OAAO,IAAI,qBAAqB,GAAG,SAAS,CAAC;CAC9C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE;IAC/C,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;IACnC,YAAY,CAAC,EAAE,SAAS,gBAAgB,EAAE,GAAG,SAAS,CAAC;IACvD,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC,GAAG,sBAAsB,CAkHzB;AAED;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,qBAAqB,EAClC,UAAU,EAAE,MAAM,GACjB;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,yBAAyB,CAAA;CAAE,CAMjE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,SAAS,oBAAoB,EAAE,EACxC,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,oBAAoB,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CASxE"}

package/dist/checkpoint-link-verifier.js

@@ -0,0 +1,181 @@
+/**
+ * Per-link trust for a retained checkpoint chain: the `verifySignature`
+ * callback {@link verifyCheckpointChain} takes, plus the delegation limits
+ * each link's label-1000 certificate imposes. Lifted from mcp-verify 0.6.1
+ * (`src/core/verify-shared.ts`) so mcp-verify and forestrie-cli share one
+ * copy; see mcp-verify `docs/trust-roots.md` ("Delegation limits under
+ * checkpoint-chain").
+ *
+ * The limits mirror univocity's on-chain check
+ * ([delegationVerifier.sol](https://github.com/forestrie/univocity/blob/main/src/checkpoints/lib/delegationVerifier.sol)):
+ * a checkpoint of claimed size `S` is anchored only when its delegation
+ * covers `mmrIndex = S > 0 ? S - 1 : 0`, i.e. `mmrStart <= mmrIndex <=
+ * mmrEnd`. Here `S` is the checkpoint's SIGNED tree size (label -65933), so
+ * a link the contract would refuse is refused offline too
+ * (`delegation_out_of_range`). Expiry needs a leaf the receipt binds and is
+ * judged after the receipt matched ({@link checkCheckpointLinkExpiry}).
+ *
+ * Pure over bytes; no network (canopy rule C1).
+ */
+import { verifyCoseSign1WithParsedKey } from "@forestrie/encoding";
+import { checkpointConsistencyProof } from "./checkpoint-chain.js";
+import { idtimestampToUnixSeconds, resolveDelegatedVerifyKey, } from "./resolve-delegated-verify-key.js";
+import { isParsedKs256RootKey } from "./root-verify-key.js";
+import { resolveWithKs256Attestations } from "./select-ks256-attestation.js";
+/**
+ * Build the per-link signature verifier for {@link verifyCheckpointChain}.
+ *
+ * For each checkpoint, in fold order: resolve its label-1000 certificate
+ * under `rootKeys` (with the attestation made for that certificate, if any),
+ * verify the COSE signature over the FOLDED accumulator (the detached
+ * payload the fold computes, never one read from the checkpoint; ADR-0046),
+ * then enforce the certificate's size bound against the signed size. KS256
+ * roots vouch only for certificates; only ES256 roots may verify a
+ * checkpoint directly.
+ *
+ * The callback must be used for exactly one fold: link indices are the call
+ * count.
+ *
+ * @param opts.rootKeys - ES256 keys and KS256 addresses, from genesis or
+ *   caller-known log keys.
+ * @param opts.attestations - ERC-1271 attestations for KS256 contract
+ *   roots; each certificate takes the one with its digest and signature
+ *   hash ({@link selectKs256Attestation}).
+ * @param opts.forestChainId - The forest genesis chain id every attestation
+ *   must carry; without it a contract root fails
+ *   `ks256_attestation_chain_unbound`.
+ */
+export function makeCheckpointLinkVerifier(opts) {
+    const rootKeys = [...opts.rootKeys];
+    const attestations = opts.attestations ?? [];
+    const es256Roots = rootKeys.filter((k) => !isParsedKs256RootKey(k));
+    const records = [];
+    let failure;
+    let calls = 0;
+    const verifySignature = async (checkpointBytes, detachedPayload) => {
+        const index = calls++;
+        const chosen = await resolveWithKs256Attestations(checkpointBytes, rootKeys, attestations, opts.forestChainId);
+        const resolution = chosen.resolution;
+        const fail = (reason) => {
+            failure = { index, reason };
+            if (chosen.selected !== undefined) {
+                failure.attestationIndex = chosen.selected;
+            }
+            if (chosen.rejected.length > 0) {
+                failure.attestationsRejected = chosen.rejected;
+            }
+            return false;
+        };
+        if (resolution.kind === "broken") {
+            return fail(resolution.reason ?? "delegation_invalid");
+        }
+        let signedSize;
+        try {
+            signedSize = checkpointConsistencyProof(checkpointBytes).signedTreeSize2;
+        }
+        catch {
+            // The fold read the same label moments ago; fail closed.
+            return fail("proof_malformed");
+        }
+        const candidates = [
+            ...(resolution.kind === "resolved"
+                ? [{ key: resolution.delegatedKey, delegated: true }]
+                : []),
+            ...es256Roots.map((key) => ({ key, delegated: false })),
+        ];
+        let signer;
+        for (const c of candidates) {
+            if (await verifyCoseSign1WithParsedKey(checkpointBytes, c.key, {
+                logPrefix: "checkpoint-chain",
+                detachedPayload,
+            })) {
+                signer = c;
+                break;
+            }
+        }
+        if (signer === undefined)
+            return fail("signature_invalid");
+        // A resolved certificate's limits bind the link even when a root key
+        // verified it directly: stricter than univocity, which would not accept
+        // a root signature alongside a certificate at all.
+        const constraints = resolution.kind === "resolved" ? resolution.constraints : null;
+        if (constraints !== null) {
+            const bound = checkCheckpointLinkSizeBound(constraints, signedSize);
+            if (!bound.ok)
+                return fail(bound.reason);
+        }
+        let verifiedBy = "es256-root";
+        if (signer.delegated) {
+            const viaEs256 = await resolveDelegatedVerifyKey(checkpointBytes, es256Roots);
+            verifiedBy = viaEs256.kind === "resolved" ? "delegated" : "ks256-root";
+        }
+        // Only a selected attestation can carry a certificate (a diagnostic
+        // stand-in never matches), so "needed" implies "selected".
+        const attestationNeeded = chosen.selected !== undefined &&
+            resolution.kind === "resolved" &&
+            (await resolveDelegatedVerifyKey(checkpointBytes, rootKeys)).kind ===
+                "broken";
+        const record = {
+            index,
+            signedSize,
+            constraints,
+            verifiedBy,
+            attestationNeeded,
+        };
+        if (chosen.rejected.length > 0) {
+            record.attestationsRejected = chosen.rejected;
+        }
+        if (chosen.selected !== undefined) {
+            record.attestationIndex = chosen.selected;
+            if (attestationNeeded) {
+                record.attestationUsed = bytesToHex(attestations[chosen.selected].digest);
+            }
+        }
+        records.push(record);
+        return true;
+    };
+    return { verifySignature, records, failure: () => failure };
+}
+/**
+ * The size bound univocity enforces on a checkpoint, judged from signed
+ * data alone: with `mmrIndex = signedSize > 0 ? signedSize - 1 : 0`, reject
+ * `mmrIndex < mmrStart || mmrIndex > mmrEnd` (`delegationVerifier.sol`,
+ * `_Univocity.sol` passes `claimedSize > 0 ? claimedSize - 1 : 0`).
+ *
+ * @returns `delegation_out_of_range` on either side of the window.
+ */
+export function checkCheckpointLinkSizeBound(constraints, signedSize) {
+    const mmrIndex = signedSize > 0n ? signedSize - 1n : 0n;
+    if (mmrIndex < constraints.mmrStart || mmrIndex > constraints.mmrEnd) {
+        return { ok: false, reason: "delegation_out_of_range" };
+    }
+    return { ok: true };
+}
+/**
+ * Expiry, judged only AFTER a receipt matched the chain, when its leaf's
+ * idtimestamp and mmrIndex are bound by the leaf hash and inclusion path
+ * rather than being caller claims. A link whose signed size covers the leaf
+ * (`signedSize > leaf.mmrIndex`) was signed after the leaf was sequenced, so
+ * a leaf time past `expiresAt` proves signing past the key's lifetime. A
+ * link that does not cover the leaf says nothing about its time. Never
+ * wall-clock; no `issuedAt` bound (a certificate is legitimately signed a
+ * few seconds after the leaf it first covers).
+ *
+ * @param records - From {@link makeCheckpointLinkVerifier}.
+ * @param leaf.idtimestamp - The bound leaf's snowflake idtimestamp.
+ * @returns The first offending link as `at`.
+ */
+export function checkCheckpointLinkExpiry(records, leaf) {
+    const leafSeconds = idtimestampToUnixSeconds(leaf.idtimestamp);
+    for (const r of records) {
+        if (r.constraints === null)
+            continue;
+        if (r.signedSize > leaf.mmrIndex && leafSeconds > r.constraints.expiresAt) {
+            return { ok: false, reason: "delegation_expired", at: r.index };
+        }
+    }
+    return { ok: true };
+}
+function bytesToHex(bytes) {
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}

package/dist/inclusion-walk-end.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The zero-based MMR index of the node an inclusion path of `pathLength`
+ * siblings reaches from `leafMmrIndex`: the peak the path claims to prove.
+ */
+export declare function inclusionWalkEndIndex(leafMmrIndex: bigint, pathLength: number): bigint;
+//# sourceMappingURL=inclusion-walk-end.d.ts.map

package/dist/inclusion-walk-end.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inclusion-walk-end.d.ts","sourceRoot":"","sources":["../src/inclusion-walk-end.ts"],"names":[],"mappings":"AAeA;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GACjB,MAAM,CAeR"}

package/dist/inclusion-walk-end.js

@@ -0,0 +1,35 @@
+/**
+ * Where an MMR inclusion walk ends. A leaf hash
+ * (`SHA-256(idtimestamp ‖ inner)`) does not commit the leaf's position, and
+ * a path of length 0 commits nothing more, so matching a recomputed peak by
+ * VALUE alone leaves the receipt's claimed `mmrIndex` unbound. Requiring the
+ * matched accumulator peak to sit at the node index the walk reaches binds
+ * it: interior nodes commit their position (`H(pos ‖ left ‖ right)`), and
+ * an empty path must start at the peak itself.
+ *
+ * Mirrors the position arithmetic of `calculateRoot` in
+ * [@forestrie/merklelog](https://github.com/forestrie/canopy/blob/main/packages/merklelog/src/mmr/algorithms.ts)
+ * (go-merklelog `mmr/proof.go`), without hashing.
+ */
+import { indexHeight } from "@forestrie/merklelog";
+/**
+ * The zero-based MMR index of the node an inclusion path of `pathLength`
+ * siblings reaches from `leafMmrIndex`: the peak the path claims to prove.
+ */
+export function inclusionWalkEndIndex(leafMmrIndex, pathLength) {
+    let height = indexHeight(leafMmrIndex);
+    // 1-based position, as calculateRoot tracks it.
+    let pos = leafMmrIndex + 1n;
+    for (let i = 0; i < pathLength; i++) {
+        // `indexHeight(pos)` is the height of the node AFTER the current one:
+        // higher means the current node is a right child.
+        if (indexHeight(pos) > height) {
+            pos += 1n;
+        }
+        else {
+            pos += 2n << BigInt(height);
+        }
+        height += 1;
+    }
+    return pos - 1n;
+}

package/dist/index.d.ts

@@ -110,4 +110,18 @@ export { univocityLeafHash } from "./leaf-commitment.js";
  * snapshot over RPC, or proof-path-extend a stale one via massif nodes).
  */
 export { assertSnapshotBinding, decodeKnownAccumulator, encodeKnownAccumulator, verifyReceiptOfflineAgainstKnownAccumulator, type KnownAccumulator, } from "./known-accumulator.js";
+/**
+ * Checkpoint-chain trust root with per-link delegation limits and several
+ * ERC-1271 attestations (owner ruling D8, receipt-verify 3.2.0): the one
+ * shared copy mcp-verify and forestrie-cli use. The high-level verifier
+ * folds, matches and judges expiry; the pieces serve callers that match
+ * peaks their own way.
+ */
+export { verifyReceiptAgainstCheckpointChain } from "./verify-receipt-against-checkpoint-chain.js";
+export type { VerifyReceiptAgainstCheckpointChainInput } from "./verify-receipt-against-checkpoint-chain.js";
+export type { CheckpointChainReceiptOutcome, CheckpointChainReceiptStage, } from "./checkpoint-chain-receipt-outcome.js";
+export { checkCheckpointLinkExpiry, checkCheckpointLinkSizeBound, makeCheckpointLinkVerifier, type CheckpointLinkVerifier, } from "./checkpoint-link-verifier.js";
+export type { CheckpointLinkFailure, CheckpointLinkRecord, CheckpointLinkVerifiedBy, } from "./checkpoint-link-record.js";
+export { selectKs256Attestation } from "./select-ks256-attestation.js";
+export { summarizeKs256AttestationUsage, type Ks256AttestationUnusedReason, type Ks256AttestationUsage, } from "./ks256-attestation-usage.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":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -89,3 +89,14 @@ export { univocityLeafHash } from "./leaf-commitment.js";
  * snapshot over RPC, or proof-path-extend a stale one via massif nodes).
  */
 export { assertSnapshotBinding, decodeKnownAccumulator, encodeKnownAccumulator, verifyReceiptOfflineAgainstKnownAccumulator, } from "./known-accumulator.js";
+/**
+ * Checkpoint-chain trust root with per-link delegation limits and several
+ * ERC-1271 attestations (owner ruling D8, receipt-verify 3.2.0): the one
+ * shared copy mcp-verify and forestrie-cli use. The high-level verifier
+ * folds, matches and judges expiry; the pieces serve callers that match
+ * peaks their own way.
+ */
+export { verifyReceiptAgainstCheckpointChain } from "./verify-receipt-against-checkpoint-chain.js";
+export { checkCheckpointLinkExpiry, checkCheckpointLinkSizeBound, makeCheckpointLinkVerifier, } from "./checkpoint-link-verifier.js";
+export { selectKs256Attestation } from "./select-ks256-attestation.js";
+export { summarizeKs256AttestationUsage, } from "./ks256-attestation-usage.js";

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

@@ -1 +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;AAsCtE,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,CAiD/B"}
+{"version":3,"file":"known-accumulator.d.ts","sourceRoot":"","sources":["../src/known-accumulator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAgBH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAsCtE,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,CAkE/B"}

package/dist/known-accumulator.js

@@ -29,8 +29,9 @@
  * the operator trust this anchor exists to remove.
  */
 import { decodeCborDeterministic, encodeCborDeterministic, } from "@forestrie/encoding";
-import { calculateRoot } from "@forestrie/merklelog";
+import { calculateRoot, peakMMRIndexes, } from "@forestrie/merklelog";
 import { normalizeHexAddress } from "@forestrie/chain-rpc";
+import { inclusionWalkEndIndex } from "./inclusion-walk-end.js";
 import { parseReceipt } from "./parse-receipt.js";
 import { univocityLeafHash } from "./leaf-commitment.js";
 import { SubtleHasher } from "./subtle-hasher.js";
@@ -190,18 +191,33 @@ export async function verifyReceiptOfflineAgainstKnownAccumulator(input) {
             reason: "receipt_newer_than_known_accumulator",
         };
     }
+    // The leaf (idtimestamp ‖ inner) and inclusion path ALWAYS decide the
+    // peak. An attached payload is only a claim of what that peak is: taken on
+    // its own, any receipt attaching a real anchored peak would "verify" for
+    // any payload and idtimestamp. Same stage and reason as the main offline
+    // path's inclusion check (verifySignatureAndInclusion).
     let recomputedPeak;
-    if (parsed.explicitPeak !== null) {
-        recomputedPeak = parsed.explicitPeak;
-    }
-    else {
-        const hasher = new SubtleHasher();
+    try {
         const leafHash = await univocityLeafHash(input.idtimestampBe8, input.inner);
-        recomputedPeak = await calculateRoot(hasher, leafHash, parsed.proof, leafIdx);
+        recomputedPeak = await calculateRoot(new SubtleHasher(), leafHash, parsed.proof, leafIdx);
+    }
+    catch {
+        return { ok: false, stage: "inclusion", reason: "inclusion_failed" };
+    }
+    if (parsed.explicitPeak !== null &&
+        !bytesEqual(parsed.explicitPeak, recomputedPeak)) {
+        return { ok: false, stage: "inclusion", reason: "inclusion_failed" };
     }
     // 2. Exact peak match — receipt state is a snapshot-covered accumulator.
-    for (const peak of input.accumulator) {
-        if (bytesEqual(recomputedPeak, peak)) {
+    // The peak must also sit at the node the inclusion walk reaches (contract
+    // order is ascending MMR index, as peakMMRIndexes lists them): a leaf hash
+    // does not commit its position, so a value match alone would leave the
+    // mmrIndex the freshness check above relies on a caller claim.
+    const peakIndex = inclusionWalkEndIndex(leafIdx, parsed.proof.path.length);
+    const p = peakMMRIndexes(input.size - 1n).indexOf(peakIndex);
+    if (p >= 0) {
+        const anchored = input.accumulator[p];
+        if (anchored !== undefined && bytesEqual(recomputedPeak, anchored)) {
             return { ok: true, stage: "binding" };
         }
     }

package/dist/ks256-attestation-usage.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Accounting for a LIST of ERC-1271 attestations over a checkpoint chain
+ * (owner ruling D8): every supplied attestation is reported as used or as
+ * unused with a reason, never silently ignored.
+ */
+import type { Ks256Attestation } from "./ks256-attestation.js";
+import type { CheckpointLinkFailure, CheckpointLinkRecord } from "./checkpoint-link-record.js";
+/**
+ * Why a supplied attestation contributed nothing:
+ * - `no_matching_certificate`: no link's certificate has its digest and
+ *   signature hash.
+ * - `not_needed`: it matched a certificate that verified without it
+ *   (ecrecover, or an ES256 root also vouched).
+ * - `duplicate`: another supplied attestation for the same certificate
+ *   (same digest and signature hash) was used, selected or rejected first,
+ *   so this one was never tried.
+ */
+export type Ks256AttestationUnusedReason = "no_matching_certificate" | "not_needed" | "duplicate";
+/**
+ * Which supplied attestations carried which links. An attestation may be
+ * in both `used` and `rejected` (used on earlier links, refused on a later
+ * one); it is in `unused` only when it is in neither.
+ */
+export type Ks256AttestationUsage = {
+    used: {
+        index: number;
+        digestHex: string;
+        links: number[];
+    }[];
+    /** Tried for a link's certificate and failed its own checks there. */
+    rejected: {
+        index: number;
+        digestHex: string;
+        links: number[];
+    }[];
+    unused: {
+        index: number;
+        digestHex: string;
+        reason: Ks256AttestationUnusedReason;
+    }[];
+};
+/**
+ * Classify each supplied attestation against the per-link records.
+ *
+ * @param attestations - The list the verifier was given, in order.
+ * @param records - Records of the links that verified.
+ * @param failure - The link the verifier refused, if any.
+ */
+export declare function summarizeKs256AttestationUsage(attestations: readonly Ks256Attestation[], records: readonly CheckpointLinkRecord[], failure?: CheckpointLinkFailure): Ks256AttestationUsage;
+//# sourceMappingURL=ks256-attestation-usage.d.ts.map

package/dist/ks256-attestation-usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ks256-attestation-usage.d.ts","sourceRoot":"","sources":["../src/ks256-attestation-usage.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EACV,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,6BAA6B,CAAC;AAErC;;;;;;;;;GASG;AACH,MAAM,MAAM,4BAA4B,GACpC,yBAAyB,GACzB,YAAY,GACZ,WAAW,CAAC;AAEhB;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;IAC9D,sEAAsE;IACtE,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;IAClE,MAAM,EAAE;QACN,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,4BAA4B,CAAC;KACtC,EAAE,CAAC;CACL,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAC5C,YAAY,EAAE,SAAS,gBAAgB,EAAE,EACzC,OAAO,EAAE,SAAS,oBAAoB,EAAE,EACxC,OAAO,CAAC,EAAE,qBAAqB,GAC9B,qBAAqB,CAsCvB"}