@forestrie/receipt-verify 3.1.0 → 3.2.0

package/dist/ks256-attestation-usage.js

@@ -0,0 +1,51 @@
+/**
+ * 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 function summarizeKs256AttestationUsage(attestations, records, failure) {
+    const usage = { used: [], rejected: [], unused: [] };
+    const seen = [...records, ...(failure !== undefined ? [failure] : [])];
+    const tried = (i) => seen.some((r) => r.attestationIndex === i || (r.attestationsRejected ?? []).includes(i));
+    attestations.forEach((a, index) => {
+        const digestHex = bytesToHex(a.digest);
+        const used = records
+            .filter((r) => r.attestationIndex === index && r.attestationNeeded)
+            .map((r) => r.index);
+        const rejected = seen
+            .filter((r) => (r.attestationsRejected ?? []).includes(index))
+            .map((r) => r.index);
+        if (used.length > 0)
+            usage.used.push({ index, digestHex, links: used });
+        if (rejected.length > 0) {
+            usage.rejected.push({ index, digestHex, links: rejected });
+        }
+        if (used.length > 0 || rejected.length > 0)
+            return;
+        let reason = "no_matching_certificate";
+        if (seen.some((r) => r.attestationIndex === index)) {
+            reason = "not_needed";
+        }
+        else if (attestations.some((b, j) => j !== index &&
+            tried(j) &&
+            bytesEqual(a.digest, b.digest) &&
+            bytesEqual(a.signatureHash, b.signatureHash))) {
+            reason = "duplicate";
+        }
+        usage.unused.push({ index, digestHex, reason });
+    });
+    return usage;
+}
+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;
+}
+function bytesToHex(bytes) {
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}

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

@@ -0,0 +1,57 @@
+/**
+ * Choosing an ERC-1271 attestation from several (owner ruling D8,
+ * 2026-10-19). A contract KS256 root (a Safe) that rotated its delegate
+ * signs one certificate per delegate, and each certificate needs its own
+ * attestation; a caller holding a checkpoint chain or several receipts
+ * supplies them as a list. Each certificate takes the attestation whose
+ * `digest` AND `signatureHash` are that certificate's: keccak256 of its
+ * Sig_structure and keccak256 of its signature bytes.
+ *
+ * Selection never makes an attestation acceptable on its own:
+ * `verifyKs256DelegationCert` still checks address, digest, signature hash,
+ * genesis chain id and magic.
+ */
+import type { Ks256CertificateDigest } from "@forestrie/delegation-cose";
+import type { Ks256Attestation } from "./ks256-attestation.js";
+import { type DelegatedResolution } from "./resolve-delegated-verify-key.js";
+import type { RootVerifyKey } from "./root-verify-key.js";
+/**
+ * The attestation in `attestations` made for this certificate: the first
+ * whose `digest` equals the certificate digest and whose `signatureHash`
+ * equals keccak256 of the certificate signature.
+ *
+ * @param cert - From `extractKs256CertificateDigest` (delegation-cose) or
+ *   {@link extractKs256DelegationDigest}.
+ * @returns The first matching attestation, or `undefined` when none
+ *   matches. The verifiers go further: they try EVERY match in order and
+ *   keep the first that passes its own checks.
+ */
+export declare function selectKs256Attestation(cert: Ks256CertificateDigest, attestations: readonly Ks256Attestation[]): Ks256Attestation | undefined;
+/**
+ * Resolve a COSE_Sign1's label-1000 certificate (a receipt or a checkpoint)
+ * under `rootKeys`, trying the supplied attestations made for it.
+ *
+ * Every attestation whose digest and signature hash match the certificate
+ * is tried in list order, and the first that resolves wins: a stale or
+ * wrong-chain copy listed before a good one must not mask it. When none
+ * resolves, the first failure is returned. When none matches at all, a
+ * DIAGNOSTIC stand-in (one with the right digest if any, else the first) is
+ * passed so a contract root fails with the precise
+ * `ks256_attestation_*_mismatch` reason rather than a bare
+ * `ks256_root_not_recovered`; a stand-in can never verify, because
+ * `verifyKs256DelegationCert` checks digest and signature hash. With one
+ * attestation supplied this is exactly the 3.1.0 behaviour of the singular
+ * `ks256Attestation` input.
+ *
+ * @returns The resolution; `selected`, the index of the attestation it was
+ *   resolved with (whether or not ecrecover made it unnecessary); and
+ *   `rejected`, the matching attestations tried that failed their own
+ *   checks (address, chain id, magic).
+ * @internal
+ */
+export declare function resolveWithKs256Attestations(coseSign1Bytes: Uint8Array, rootKeys: RootVerifyKey[], attestations: readonly Ks256Attestation[], forestChainId: bigint | undefined): Promise<{
+    resolution: DelegatedResolution;
+    selected?: number;
+    rejected: number[];
+}>;
+//# sourceMappingURL=select-ks256-attestation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"select-ks256-attestation.d.ts","sourceRoot":"","sources":["../src/select-ks256-attestation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AACzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAG1D;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,sBAAsB,EAC5B,YAAY,EAAE,SAAS,gBAAgB,EAAE,GACxC,gBAAgB,GAAG,SAAS,CAG9B;AASD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,4BAA4B,CAChD,cAAc,EAAE,UAAU,EAC1B,QAAQ,EAAE,aAAa,EAAE,EACzB,YAAY,EAAE,SAAS,gBAAgB,EAAE,EACzC,aAAa,EAAE,MAAM,GAAG,SAAS,GAChC,OAAO,CAAC;IACT,UAAU,EAAE,mBAAmB,CAAC;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC,CA6CD"}

package/dist/select-ks256-attestation.js

@@ -0,0 +1,119 @@
+/**
+ * Choosing an ERC-1271 attestation from several (owner ruling D8,
+ * 2026-10-19). A contract KS256 root (a Safe) that rotated its delegate
+ * signs one certificate per delegate, and each certificate needs its own
+ * attestation; a caller holding a checkpoint chain or several receipts
+ * supplies them as a list. Each certificate takes the attestation whose
+ * `digest` AND `signatureHash` are that certificate's: keccak256 of its
+ * Sig_structure and keccak256 of its signature bytes.
+ *
+ * Selection never makes an attestation acceptable on its own:
+ * `verifyKs256DelegationCert` still checks address, digest, signature hash,
+ * genesis chain id and magic.
+ */
+import { keccak_256 } from "@noble/hashes/sha3";
+import { resolveDelegatedVerifyKey, } from "./resolve-delegated-verify-key.js";
+import { extractKs256DelegationDigest } from "./verify-ks256-delegation.js";
+/**
+ * The attestation in `attestations` made for this certificate: the first
+ * whose `digest` equals the certificate digest and whose `signatureHash`
+ * equals keccak256 of the certificate signature.
+ *
+ * @param cert - From `extractKs256CertificateDigest` (delegation-cose) or
+ *   {@link extractKs256DelegationDigest}.
+ * @returns The first matching attestation, or `undefined` when none
+ *   matches. The verifiers go further: they try EVERY match in order and
+ *   keep the first that passes its own checks.
+ */
+export function selectKs256Attestation(cert, attestations) {
+    const i = selectKs256AttestationIndex(cert, attestations);
+    return i === undefined ? undefined : attestations[i];
+}
+function selectKs256AttestationIndex(cert, attestations) {
+    return matchingIndexes(cert, attestations)[0];
+}
+/**
+ * Resolve a COSE_Sign1's label-1000 certificate (a receipt or a checkpoint)
+ * under `rootKeys`, trying the supplied attestations made for it.
+ *
+ * Every attestation whose digest and signature hash match the certificate
+ * is tried in list order, and the first that resolves wins: a stale or
+ * wrong-chain copy listed before a good one must not mask it. When none
+ * resolves, the first failure is returned. When none matches at all, a
+ * DIAGNOSTIC stand-in (one with the right digest if any, else the first) is
+ * passed so a contract root fails with the precise
+ * `ks256_attestation_*_mismatch` reason rather than a bare
+ * `ks256_root_not_recovered`; a stand-in can never verify, because
+ * `verifyKs256DelegationCert` checks digest and signature hash. With one
+ * attestation supplied this is exactly the 3.1.0 behaviour of the singular
+ * `ks256Attestation` input.
+ *
+ * @returns The resolution; `selected`, the index of the attestation it was
+ *   resolved with (whether or not ecrecover made it unnecessary); and
+ *   `rejected`, the matching attestations tried that failed their own
+ *   checks (address, chain id, magic).
+ * @internal
+ */
+export async function resolveWithKs256Attestations(coseSign1Bytes, rootKeys, attestations, forestChainId) {
+    if (attestations.length === 0) {
+        return {
+            resolution: await resolveDelegatedVerifyKey(coseSign1Bytes, rootKeys),
+            rejected: [],
+        };
+    }
+    let cert = null;
+    try {
+        cert = extractKs256DelegationDigest(coseSign1Bytes);
+    }
+    catch {
+        // Not a KS256 certificate (or not a COSE_Sign1): no attestation can be
+        // made for it; the stand-in below is never consulted by an ES256 root.
+        cert = null;
+    }
+    const candidates = cert === null ? [] : matchingIndexes(cert, attestations);
+    const rejected = [];
+    let firstFailure;
+    for (const i of candidates) {
+        const resolution = await resolveDelegatedVerifyKey(coseSign1Bytes, rootKeys, { attestation: attestations[i], forestChainId });
+        if (resolution.kind !== "broken") {
+            return { resolution, selected: i, rejected };
+        }
+        firstFailure ??= resolution;
+        // Only an attestation's own checks make it "rejected"; any other
+        // failure is the certificate's and no other copy can change it.
+        if (!resolution.reason?.startsWith("ks256_attestation_"))
+            break;
+        rejected.push(i);
+    }
+    if (firstFailure !== undefined)
+        return { resolution: firstFailure, rejected };
+    const standIn = (cert !== null &&
+        attestations.find((a) => bytesEqual(a.digest, cert.digest))) ||
+        attestations[0];
+    return {
+        resolution: await resolveDelegatedVerifyKey(coseSign1Bytes, rootKeys, {
+            attestation: standIn,
+            forestChainId,
+        }),
+        rejected,
+    };
+}
+function matchingIndexes(cert, attestations) {
+    const signatureHash = keccak_256(cert.signature);
+    const out = [];
+    attestations.forEach((a, i) => {
+        if (bytesEqual(a.digest, cert.digest) &&
+            bytesEqual(a.signatureHash, signatureHash)) {
+            out.push(i);
+        }
+    });
+    return out;
+}
+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;
+}

package/dist/verify-grant-receipt-offline.d.ts

@@ -9,6 +9,8 @@ export type VerifyGrantReceiptOfflineInput = {
     idtimestampBe8: Uint8Array;
     /** See {@link VerifyReceiptOfflineInput.ks256Attestation}. */
     ks256Attestation?: Ks256Attestation;
+    /** See {@link VerifyReceiptOfflineInput.ks256Attestations}. */
+    ks256Attestations?: readonly Ks256Attestation[];
 };
 /**
  * Offline grant receipt verify (layers A–C, ADR-0045). Pure over bytes; no network.
@@ -38,6 +40,15 @@ export type VerifyReceiptOfflineInput = {
      * binds the root address, the certificate digest and the genesis chain id.
      */
     ks256Attestation?: Ks256Attestation;
+    /**
+     * Several attestations (owner ruling D8): the one whose digest and
+     * signature hash match the receipt's certificate is used
+     * ({@link selectKs256Attestation}). Combined with
+     * {@link ks256Attestation} when both are given. When none matches, one
+     * still reaches the KS256 check only to name the mismatch: it can never
+     * verify the certificate.
+     */
+    ks256Attestations?: readonly Ks256Attestation[];
 };
 /**
  * Offline verify of a receipt against the EXACT registered payload. The log

package/dist/verify-grant-receipt-offline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"verify-grant-receipt-offline.d.ts","sourceRoot":"","sources":["../src/verify-grant-receipt-offline.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAIjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAOhF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAGtE,MAAM,MAAM,8BAA8B,GAAG;IAC3C,WAAW,EAAE,UAAU,CAAC;IACxB,WAAW,EAAE,UAAU,CAAC;IACxB,KAAK,EAAE,KAAK,CAAC;IACb,cAAc,EAAE,UAAU,CAAC;IAC3B,8DAA8D;IAC9D,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACrC,CAAC;AA4EF;;GAEG;AACH,wBAAsB,yBAAyB,CAC7C,KAAK,EAAE,8BAA8B,GACpC,OAAO,CAAC,mBAAmB,CAAC,CAe9B;AAED,MAAM,MAAM,sCAAsC,GAAG,IAAI,CACvD,8BAA8B,EAC9B,aAAa,CACd,GACC,IAAI,CAAC,iCAAiC,EAAE,WAAW,GAAG,mBAAmB,CAAC,CAAC;AAE7E;;;;GAIG;AACH,wBAAsB,iCAAiC,CACrD,KAAK,EAAE,sCAAsC,GAC5C,OAAO,CAAC,mBAAmB,CAAC,CAc9B;AAED,MAAM,MAAM,yBAAyB,GAAG;IACtC,WAAW,EAAE,UAAU,CAAC;IACxB,WAAW,EAAE,UAAU,CAAC;IACxB;;;;;OAKG;IACH,OAAO,EAAE,UAAU,CAAC;IACpB,cAAc,EAAE,UAAU,CAAC;IAC3B;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACrC,CAAC;AAEF;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,yBAAyB,GAC/B,OAAO,CAAC,mBAAmB,CAAC,CAc9B;AAED,MAAM,MAAM,iCAAiC,GAAG,IAAI,CAClD,yBAAyB,EACzB,aAAa,CACd,GAAG;IACF;;;;;;OAMG;IACH,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,UAAU,CAAC;CAChC,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,4BAA4B,CAChD,KAAK,EAAE,iCAAiC,GACvC,OAAO,CAAC,mBAAmB,CAAC,CAc9B"}
+{"version":3,"file":"verify-grant-receipt-offline.d.ts","sourceRoot":"","sources":["../src/verify-grant-receipt-offline.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAIjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAOhF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAItE,MAAM,MAAM,8BAA8B,GAAG;IAC3C,WAAW,EAAE,UAAU,CAAC;IACxB,WAAW,EAAE,UAAU,CAAC;IACxB,KAAK,EAAE,KAAK,CAAC;IACb,cAAc,EAAE,UAAU,CAAC;IAC3B,8DAA8D;IAC9D,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,+DAA+D;IAC/D,iBAAiB,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACjD,CAAC;AA4EF;;GAEG;AACH,wBAAsB,yBAAyB,CAC7C,KAAK,EAAE,8BAA8B,GACpC,OAAO,CAAC,mBAAmB,CAAC,CAe9B;AAED,MAAM,MAAM,sCAAsC,GAAG,IAAI,CACvD,8BAA8B,EAC9B,aAAa,CACd,GACC,IAAI,CAAC,iCAAiC,EAAE,WAAW,GAAG,mBAAmB,CAAC,CAAC;AAE7E;;;;GAIG;AACH,wBAAsB,iCAAiC,CACrD,KAAK,EAAE,sCAAsC,GAC5C,OAAO,CAAC,mBAAmB,CAAC,CAiB9B;AAED,MAAM,MAAM,yBAAyB,GAAG;IACtC,WAAW,EAAE,UAAU,CAAC;IACxB,WAAW,EAAE,UAAU,CAAC;IACxB;;;;;OAKG;IACH,OAAO,EAAE,UAAU,CAAC;IACpB,cAAc,EAAE,UAAU,CAAC;IAC3B;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACjD,CAAC;AAEF;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,yBAAyB,GAC/B,OAAO,CAAC,mBAAmB,CAAC,CAc9B;AAED,MAAM,MAAM,iCAAiC,GAAG,IAAI,CAClD,yBAAyB,EACzB,aAAa,CACd,GAAG;IACF;;;;;;OAMG;IACH,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,UAAU,CAAC;CAChC,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,4BAA4B,CAChD,KAAK,EAAE,iCAAiC,GACvC,OAAO,CAAC,mBAAmB,CAAC,CAiB9B"}

package/dist/verify-grant-receipt-offline.js

@@ -4,10 +4,11 @@ import { grantCommitmentHashFromGrant } from "./grant-commitment.js";
 import { decodeTrustRootFromGenesis } from "./decode-trust-root-from-genesis.js";
 import { decodeChainBindingFromGenesis } from "./decode-chain-binding-from-genesis.js";
 import { isParsedKs256RootKey } from "./root-verify-key.js";
-import { checkDelegationConstraints, resolveDelegatedVerifyKey, } from "./resolve-delegated-verify-key.js";
+import { checkDelegationConstraints, } from "./resolve-delegated-verify-key.js";
 import { univocityLeafHash } from "./leaf-commitment.js";
 import { parseReceipt } from "./parse-receipt.js";
 import { SubtleHasher } from "./subtle-hasher.js";
+import { resolveWithKs256Attestations } from "./select-ks256-attestation.js";
 function readIdtimestampBe8(bytes) {
     if (!bytes || bytes.length < 8) {
         throw new Error("idtimestamp required for receipt verification (8 bytes)");
@@ -73,7 +74,7 @@ export async function verifyGrantReceiptOffline(input) {
         receiptCbor: input.receiptCbor,
         idtimestampBe8: input.idtimestampBe8,
         inner,
-        ks256Attestation: input.ks256Attestation,
+        ks256Attestations: attestationCandidates(input),
     });
 }
 /**
@@ -94,7 +95,10 @@ export async function verifyGrantReceiptOfflineWithKeys(input) {
         idtimestampBe8: input.idtimestampBe8,
         inner,
         trustKeys: input.trustKeys,
-        ks256Evidence: withKeysKs256Evidence(input),
+        ks256Attestations: attestationCandidates(input),
+        forestChainId: input.forestGenesisCbor
+            ? genesisChainIdOrUndefined(input.forestGenesisCbor)
+            : undefined,
     });
 }
 /**
@@ -111,7 +115,7 @@ export async function verifyReceiptOffline(input) {
         receiptCbor: input.receiptCbor,
         idtimestampBe8: input.idtimestampBe8,
         inner,
-        ks256Attestation: input.ks256Attestation,
+        ks256Attestations: attestationCandidates(input),
     });
 }
 /**
@@ -138,22 +142,21 @@ export async function verifyReceiptOfflineWithKeys(input) {
         idtimestampBe8: input.idtimestampBe8,
         inner,
         trustKeys: input.trustKeys,
-        ks256Evidence: withKeysKs256Evidence(input),
+        ks256Attestations: attestationCandidates(input),
+        forestChainId: input.forestGenesisCbor
+            ? genesisChainIdOrUndefined(input.forestGenesisCbor)
+            : undefined,
     });
 }
 /**
- * KS256 chain evidence for the caller-known-key entries: the attestation, and
- * the chain id from the forest genesis the caller supplied, if any.
+ * Every attestation the caller supplied: the list, then the singular field
+ * (kept for 3.1.0 callers).
  */
-function withKeysKs256Evidence(input) {
-    if (!input.ks256Attestation)
-        return {};
-    return {
-        attestation: input.ks256Attestation,
-        forestChainId: input.forestGenesisCbor
-            ? genesisChainIdOrUndefined(input.forestGenesisCbor)
-            : undefined,
-    };
+function attestationCandidates(input) {
+    return [
+        ...(input.ks256Attestations ?? []),
+        ...(input.ks256Attestation ? [input.ks256Attestation] : []),
+    ];
 }
 /**
  * The forest's chain id from its genesis chain binding, or `undefined` when
@@ -187,12 +190,8 @@ async function verifyReceiptOfflineWithLeafInner(input) {
         idtimestampBe8: input.idtimestampBe8,
         inner: input.inner,
         trustKeys: [trustRoot],
-        ks256Evidence: input.ks256Attestation
-            ? {
-                attestation: input.ks256Attestation,
-                forestChainId: genesisChainIdOrUndefined(input.genesisCbor),
-            }
-            : {},
+        ks256Attestations: input.ks256Attestations,
+        forestChainId: genesisChainIdOrUndefined(input.genesisCbor),
     });
 }
 /**
@@ -218,7 +217,10 @@ async function verifyReceiptOfflineWithLeafInnerKeys(input) {
     // delegated key first. A cert present but not chaining to a trust key is a
     // hard failure — do not silently fall back to the trust key (which cannot
     // verify a delegated-signed receipt anyway).
-    const delegation = await resolveDelegatedVerifyKey(input.receiptCbor, input.trustKeys, input.ks256Evidence);
+    // D8: the attestations made for THIS receipt's certificate (digest and
+    // signature hash), tried in order; none matching, a stand-in only names
+    // the mismatch.
+    const { resolution: delegation } = await resolveWithKs256Attestations(input.receiptCbor, input.trustKeys, input.ks256Attestations, input.forestChainId);
     if (delegation.kind === "broken") {
         return {
             ok: false,

package/dist/verify-receipt-against-checkpoint-chain.d.ts

@@ -0,0 +1,42 @@
+import type { CheckpointChainReceiptOutcome } from "./checkpoint-chain-receipt-outcome.js";
+import type { Ks256Attestation } from "./ks256-attestation.js";
+import type { RootVerifyKey } from "./root-verify-key.js";
+/** Input to {@link verifyReceiptAgainstCheckpointChain}. */
+export type VerifyReceiptAgainstCheckpointChainInput = {
+    receiptCbor: Uint8Array;
+    /** The leaf's idtimestamp; the last 8 bytes are used (big-endian). */
+    idtimestampBe8: Uint8Array;
+    /** Leaf ContentHash: SHA-256(payload), or the grant commitment hash. */
+    inner: Uint8Array;
+    /** Retained checkpoints in fold (ascending size) order. */
+    checkpoints: readonly Uint8Array[];
+    /** ES256 keys and KS256 addresses, from genesis or caller-known keys. */
+    rootKeys: readonly RootVerifyKey[];
+    /** ERC-1271 attestations, one per contract-root certificate. */
+    attestations?: readonly Ks256Attestation[] | undefined;
+    /**
+     * The forest genesis, read only for its chain id (attestations must
+     * match it). Give this or {@link forestChainId}; both must agree.
+     */
+    forestGenesisCbor?: Uint8Array | undefined;
+    forestChainId?: bigint | undefined;
+    /** Trusted base for a suffix chain; see `verifyCheckpointChain`. */
+    trustedBase?: {
+        size: bigint;
+        accumulator: Uint8Array[];
+    } | undefined;
+};
+/**
+ * Verify a receipt against a retained checkpoint chain.
+ *
+ * The receipt's own signature is not checked: the authenticated chain is
+ * the authority, and the peak is ALWAYS recomputed from the leaf
+ * (`idtimestamp ‖ inner`) and the inclusion path, never taken from an
+ * attached payload. A match binds the leaf's idtimestamp (through the leaf
+ * hash) and its mmrIndex (through the matched peak's POSITION, which must be
+ * the node the inclusion walk reaches: the leaf hash alone does not commit
+ * its position, and an empty path commits none).
+ * Links are searched newest first; the newest cover is reported.
+ */
+export declare function verifyReceiptAgainstCheckpointChain(input: VerifyReceiptAgainstCheckpointChainInput): Promise<CheckpointChainReceiptOutcome>;
+//# sourceMappingURL=verify-receipt-against-checkpoint-chain.d.ts.map

package/dist/verify-receipt-against-checkpoint-chain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-receipt-against-checkpoint-chain.d.ts","sourceRoot":"","sources":["../src/verify-receipt-against-checkpoint-chain.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,uCAAuC,CAAC;AAM3F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAK/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAG1D,4DAA4D;AAC5D,MAAM,MAAM,wCAAwC,GAAG;IACrD,WAAW,EAAE,UAAU,CAAC;IACxB,sEAAsE;IACtE,cAAc,EAAE,UAAU,CAAC;IAC3B,wEAAwE;IACxE,KAAK,EAAE,UAAU,CAAC;IAClB,2DAA2D;IAC3D,WAAW,EAAE,SAAS,UAAU,EAAE,CAAC;IACnC,yEAAyE;IACzE,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;IACnC,gEAAgE;IAChE,YAAY,CAAC,EAAE,SAAS,gBAAgB,EAAE,GAAG,SAAS,CAAC;IACvD;;;OAGG;IACH,iBAAiB,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IAC3C,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,oEAAoE;IACpE,WAAW,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,UAAU,EAAE,CAAA;KAAE,GAAG,SAAS,CAAC;CACvE,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAsB,mCAAmC,CACvD,KAAK,EAAE,wCAAwC,GAC9C,OAAO,CAAC,6BAA6B,CAAC,CA0KxC"}

package/dist/verify-receipt-against-checkpoint-chain.js

@@ -0,0 +1,205 @@
+/**
+ * The checkpoint-chain trust root (FOR-368 Phase 3; owner ruling D8): fold a
+ * retained `.sth` chain under the caller's roots with per-link delegation
+ * limits ({@link makeCheckpointLinkVerifier}), match the receipt's peak
+ * against ANY authenticated link, then judge certificate expiry on the
+ * links covering the now-bound leaf ({@link checkCheckpointLinkExpiry}).
+ * Lifted from mcp-verify 0.6.1's `verifyAtCheckpointChain`; forestrie-cli,
+ * which matches peaks its own way, can use the pieces instead.
+ *
+ * Later links' signed consistency proofs commit an earlier accumulator
+ * forward, so burial never turns an honest receipt tamper-shaped. Retention
+ * limits coverage, never validity: a receipt newer than the chain fails
+ * closed with a refresh remedy.
+ *
+ * Pure over bytes; no network (canopy rule C1).
+ */
+import { calculateRoot, peakMMRIndexes } from "@forestrie/merklelog";
+import { verifyCheckpointChain, } from "./checkpoint-chain.js";
+import { checkCheckpointLinkExpiry, makeCheckpointLinkVerifier, } from "./checkpoint-link-verifier.js";
+import { decodeChainBindingFromGenesis } from "./decode-chain-binding-from-genesis.js";
+import { summarizeKs256AttestationUsage } from "./ks256-attestation-usage.js";
+import { inclusionWalkEndIndex } from "./inclusion-walk-end.js";
+import { univocityLeafHash } from "./leaf-commitment.js";
+import { parseReceipt } from "./parse-receipt.js";
+import { SubtleHasher } from "./subtle-hasher.js";
+/**
+ * Verify a receipt against a retained checkpoint chain.
+ *
+ * The receipt's own signature is not checked: the authenticated chain is
+ * the authority, and the peak is ALWAYS recomputed from the leaf
+ * (`idtimestamp ‖ inner`) and the inclusion path, never taken from an
+ * attached payload. A match binds the leaf's idtimestamp (through the leaf
+ * hash) and its mmrIndex (through the matched peak's POSITION, which must be
+ * the node the inclusion walk reaches: the leaf hash alone does not commit
+ * its position, and an empty path commits none).
+ * Links are searched newest first; the newest cover is reported.
+ */
+export async function verifyReceiptAgainstCheckpointChain(input) {
+    const attestations = input.attestations ?? [];
+    const empty = {
+        links: [],
+        records: [],
+        attestations: summarizeKs256AttestationUsage(attestations, []),
+    };
+    if (input.rootKeys.length === 0) {
+        return { ...empty, ok: false, stage: "input", reason: "no_trust_key" };
+    }
+    let forestChainId = input.forestChainId;
+    if (input.forestGenesisCbor !== undefined) {
+        let fromGenesis;
+        try {
+            fromGenesis = BigInt(decodeChainBindingFromGenesis(input.forestGenesisCbor).chainId);
+        }
+        catch {
+            return {
+                ...empty,
+                ok: false,
+                stage: "input",
+                reason: "forest_genesis_invalid",
+            };
+        }
+        if (forestChainId !== undefined && forestChainId !== fromGenesis) {
+            return {
+                ...empty,
+                ok: false,
+                stage: "input",
+                reason: "forest_chain_id_mismatch",
+            };
+        }
+        forestChainId = fromGenesis;
+    }
+    const verifier = makeCheckpointLinkVerifier({
+        rootKeys: input.rootKeys,
+        attestations,
+        forestChainId,
+    });
+    const chain = await verifyCheckpointChain({
+        checkpoints: [...input.checkpoints],
+        verifySignature: verifier.verifySignature,
+        ...(input.trustedBase !== undefined
+            ? { trustedBase: input.trustedBase }
+            : {}),
+    });
+    const linkFailure = verifier.failure();
+    const common = {
+        links: chain.links,
+        records: verifier.records,
+        attestations: summarizeKs256AttestationUsage(attestations, verifier.records, linkFailure),
+    };
+    if (!chain.ok) {
+        return {
+            ...common,
+            ok: false,
+            stage: "chain",
+            reason: linkFailure?.reason ?? `checkpoint_chain_${chain.reason}`,
+            at: chain.at,
+            detail: chain.detail,
+            ...(linkFailure !== undefined ? { linkFailure } : {}),
+        };
+    }
+    let parsed;
+    try {
+        parsed = parseReceipt(input.receiptCbor);
+    }
+    catch {
+        return {
+            ...common,
+            ok: false,
+            stage: "parse",
+            reason: "receipt_malformed",
+        };
+    }
+    if (input.idtimestampBe8.length < 8) {
+        return {
+            ...common,
+            ok: false,
+            stage: "parse",
+            reason: "idtimestamp_invalid",
+        };
+    }
+    const idtimestamp = readU64Be(input.idtimestampBe8.slice(-8));
+    // parseReceipt always sets mmrIndex; leafIndex wins when present, as in
+    // every other peak recompute in this package.
+    const leafMmrIndex = parsed.proof.leafIndex ?? parsed.proof.mmrIndex;
+    if (leafMmrIndex === undefined) {
+        return {
+            ...common,
+            ok: false,
+            stage: "parse",
+            reason: "receipt_malformed",
+        };
+    }
+    const links = chain.links;
+    const final = links[links.length - 1];
+    if (leafMmrIndex >= final.treeSize2) {
+        return {
+            ...common,
+            ok: false,
+            stage: "anchor",
+            reason: "receipt_newer_than_checkpoint_chain",
+        };
+    }
+    let peak;
+    try {
+        peak = await calculateRoot(new SubtleHasher(), await univocityLeafHash(idtimestamp, input.inner), parsed.proof, leafMmrIndex);
+    }
+    catch {
+        return {
+            ...common,
+            ok: false,
+            stage: "parse",
+            reason: "receipt_malformed",
+        };
+    }
+    // The peak the path claims to reach. A leaf hash does not commit its
+    // position (and an empty path commits none), so a value match alone would
+    // leave mmrIndex a caller claim: the matched peak must sit at this index.
+    const peakIndex = inclusionWalkEndIndex(leafMmrIndex, parsed.proof.path.length);
+    for (let i = links.length - 1; i >= 0; i--) {
+        const link = links[i];
+        const p = link.treeSize2 > 0n
+            ? peakMMRIndexes(link.treeSize2 - 1n).indexOf(peakIndex)
+            : -1;
+        if (p < 0 || !bytesEqual(link.accumulator[p] ?? new Uint8Array(), peak)) {
+            continue;
+        }
+        // The leaf hash, inclusion path and peak position now bind idtimestamp
+        // and mmrIndex to an authenticated accumulator, so expiry can be judged
+        // on them.
+        const expiry = checkCheckpointLinkExpiry(verifier.records, {
+            mmrIndex: leafMmrIndex,
+            idtimestamp,
+        });
+        if (!expiry.ok) {
+            return {
+                ...common,
+                ok: false,
+                stage: "delegation",
+                reason: expiry.reason,
+                at: expiry.at,
+            };
+        }
+        return { ...common, ok: true, matchedLink: i, matchedPeak: p };
+    }
+    return {
+        ...common,
+        ok: false,
+        stage: "anchor",
+        reason: "peak_not_in_checkpoint_chain",
+    };
+}
+function readU64Be(be8) {
+    let v = 0n;
+    for (const b of be8)
+        v = (v << 8n) | BigInt(b);
+    return v;
+}
+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;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forestrie/receipt-verify",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "license": "MIT",
   "type": "module",
   "description": "Offline SCITT grant receipt verification (ADR-0045)",
@@ -28,10 +28,10 @@
   ],
   "dependencies": {
     "@noble/hashes": "^1.7.1",
-    "@forestrie/delegation-cose": "0.4.0",
+    "@forestrie/chain-rpc": "0.3.0",
     "@forestrie/encoding": "0.9.1",
     "@forestrie/merklelog": "0.5.0",
-    "@forestrie/chain-rpc": "0.3.0"
+    "@forestrie/delegation-cose": "0.4.0"
   },
   "devDependencies": {
     "@noble/curves": "^1.9.7",