@forestrie/receipt-verify 3.1.0 → 3.2.0

package/src/select-ks256-attestation.ts

@@ -0,0 +1,151 @@
+/**
+ * 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 type { Ks256CertificateDigest } from "@forestrie/delegation-cose";
+import type { Ks256Attestation } from "./ks256-attestation.js";
+import {
+  resolveDelegatedVerifyKey,
+  type DelegatedResolution,
+} from "./resolve-delegated-verify-key.js";
+import type { RootVerifyKey } from "./root-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: Ks256CertificateDigest,
+  attestations: readonly Ks256Attestation[],
+): Ks256Attestation | undefined {
+  const i = selectKs256AttestationIndex(cert, attestations);
+  return i === undefined ? undefined : attestations[i];
+}
+
+function selectKs256AttestationIndex(
+  cert: Ks256CertificateDigest,
+  attestations: readonly Ks256Attestation[],
+): number | undefined {
+  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: Uint8Array,
+  rootKeys: RootVerifyKey[],
+  attestations: readonly Ks256Attestation[],
+  forestChainId: bigint | undefined,
+): Promise<{
+  resolution: DelegatedResolution;
+  selected?: number;
+  rejected: number[];
+}> {
+  if (attestations.length === 0) {
+    return {
+      resolution: await resolveDelegatedVerifyKey(coseSign1Bytes, rootKeys),
+      rejected: [],
+    };
+  }
+  let cert: Ks256CertificateDigest | null = 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: number[] = [];
+  let firstFailure: DelegatedResolution | undefined;
+  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: Ks256CertificateDigest,
+  attestations: readonly Ks256Attestation[],
+): number[] {
+  const signatureHash = keccak_256(cert.signature);
+  const out: number[] = [];
+  attestations.forEach((a, i) => {
+    if (
+      bytesEqual(a.digest, cert.digest) &&
+      bytesEqual(a.signatureHash, signatureHash)
+    ) {
+      out.push(i);
+    }
+  });
+  return out;
+}
+
+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;
+}

package/src/verify-grant-receipt-offline.ts

@@ -9,7 +9,6 @@ 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 type { Ks256Attestation } from "./ks256-attestation.js";
-import type { Ks256DelegationEvidence } from "./verify-ks256-delegation.js";
 import { isParsedKs256RootKey, type RootVerifyKey } from "./root-verify-key.js";
 import {
   checkDelegationConstraints,
@@ -19,6 +18,7 @@ import { univocityLeafHash } from "./leaf-commitment.js";
 import { parseReceipt } from "./parse-receipt.js";
 import type { ReceiptVerifyResult } from "./receipt-verify-result.js";
 import { SubtleHasher } from "./subtle-hasher.js";
+import { resolveWithKs256Attestations } from "./select-ks256-attestation.js";
 
 export type VerifyGrantReceiptOfflineInput = {
   genesisCbor: Uint8Array;
@@ -27,6 +27,8 @@ export type VerifyGrantReceiptOfflineInput = {
   idtimestampBe8: Uint8Array;
   /** See {@link VerifyReceiptOfflineInput.ks256Attestation}. */
   ks256Attestation?: Ks256Attestation;
+  /** See {@link VerifyReceiptOfflineInput.ks256Attestations}. */
+  ks256Attestations?: readonly Ks256Attestation[];
 };
 
 function readIdtimestampBe8(bytes: Uint8Array): bigint {
@@ -121,7 +123,7 @@ export async function verifyGrantReceiptOffline(
     receiptCbor: input.receiptCbor,
     idtimestampBe8: input.idtimestampBe8,
     inner,
-    ks256Attestation: input.ks256Attestation,
+    ks256Attestations: attestationCandidates(input),
   });
 }
 
@@ -150,7 +152,10 @@ export async function verifyGrantReceiptOfflineWithKeys(
     idtimestampBe8: input.idtimestampBe8,
     inner,
     trustKeys: input.trustKeys,
-    ks256Evidence: withKeysKs256Evidence(input),
+    ks256Attestations: attestationCandidates(input),
+    forestChainId: input.forestGenesisCbor
+      ? genesisChainIdOrUndefined(input.forestGenesisCbor)
+      : undefined,
   });
 }
 
@@ -171,6 +176,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[];
 };
 
 /**
@@ -194,7 +208,7 @@ export async function verifyReceiptOffline(
     receiptCbor: input.receiptCbor,
     idtimestampBe8: input.idtimestampBe8,
     inner,
-    ks256Attestation: input.ks256Attestation,
+    ks256Attestations: attestationCandidates(input),
   });
 }
 
@@ -249,25 +263,25 @@ export async function verifyReceiptOfflineWithKeys(
     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: {
+function attestationCandidates(input: {
   ks256Attestation?: Ks256Attestation | undefined;
-  forestGenesisCbor?: Uint8Array | undefined;
-}): Ks256DelegationEvidence {
-  if (!input.ks256Attestation) return {};
-  return {
-    attestation: input.ks256Attestation,
-    forestChainId: input.forestGenesisCbor
-      ? genesisChainIdOrUndefined(input.forestGenesisCbor)
-      : undefined,
-  };
+  ks256Attestations?: readonly Ks256Attestation[] | undefined;
+}): Ks256Attestation[] {
+  return [
+    ...(input.ks256Attestations ?? []),
+    ...(input.ks256Attestation ? [input.ks256Attestation] : []),
+  ];
 }
 
 /**
@@ -296,7 +310,7 @@ async function verifyReceiptOfflineWithLeafInner(input: {
   receiptCbor: Uint8Array;
   idtimestampBe8: Uint8Array;
   inner: Uint8Array;
-  ks256Attestation?: Ks256Attestation | undefined;
+  ks256Attestations: Ks256Attestation[];
 }): Promise<ReceiptVerifyResult> {
   let trustRoot: RootVerifyKey;
   try {
@@ -310,12 +324,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),
   });
 }
 
@@ -331,7 +341,9 @@ async function verifyReceiptOfflineWithLeafInnerKeys(input: {
   idtimestampBe8: Uint8Array;
   inner: Uint8Array;
   trustKeys: RootVerifyKey[];
-  ks256Evidence: Ks256DelegationEvidence;
+  ks256Attestations: Ks256Attestation[];
+  /** The forest genesis chain id an attestation must carry, if known. */
+  forestChainId: bigint | undefined;
 }): Promise<ReceiptVerifyResult> {
   let parsed: ReturnType<typeof parseReceipt>;
   try {
@@ -349,10 +361,14 @@ 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(
+  // 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.ks256Evidence,
+    input.ks256Attestations,
+    input.forestChainId,
   );
   if (delegation.kind === "broken") {
     return {

package/src/verify-receipt-against-checkpoint-chain.ts

@@ -0,0 +1,256 @@
+/**
+ * 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,
+  type CheckpointChainLink,
+} from "./checkpoint-chain.js";
+import type { CheckpointChainReceiptOutcome } from "./checkpoint-chain-receipt-outcome.js";
+import {
+  checkCheckpointLinkExpiry,
+  makeCheckpointLinkVerifier,
+} from "./checkpoint-link-verifier.js";
+import { decodeChainBindingFromGenesis } from "./decode-chain-binding-from-genesis.js";
+import type { Ks256Attestation } from "./ks256-attestation.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 type { RootVerifyKey } from "./root-verify-key.js";
+import { SubtleHasher } from "./subtle-hasher.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 async function verifyReceiptAgainstCheckpointChain(
+  input: VerifyReceiptAgainstCheckpointChainInput,
+): Promise<CheckpointChainReceiptOutcome> {
+  const attestations = input.attestations ?? [];
+  const empty = {
+    links: [] as CheckpointChainLink[],
+    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: bigint;
+    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: ReturnType<typeof parseReceipt>;
+  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: Uint8Array;
+  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: Uint8Array): bigint {
+  let v = 0n;
+  for (const b of be8) v = (v << 8n) | BigInt(b);
+  return v;
+}
+
+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;
+}