@forestrie/receipt-verify 3.1.0 → 3.2.0

package/src/checkpoint-chain-receipt-outcome.ts

@@ -0,0 +1,67 @@
+/**
+ * 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;
+    });

package/src/checkpoint-link-record.ts

@@ -0,0 +1,74 @@
+/**
+ * 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[];
+};

package/src/checkpoint-link-verifier.ts

@@ -0,0 +1,241 @@
+/**
+ * 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 type {
+  CheckpointLinkFailure,
+  CheckpointLinkRecord,
+  CheckpointLinkVerifiedBy,
+} from "./checkpoint-link-record.js";
+import type { Ks256Attestation } from "./ks256-attestation.js";
+import {
+  idtimestampToUnixSeconds,
+  resolveDelegatedVerifyKey,
+  type DelegationConstraints,
+} from "./resolve-delegated-verify-key.js";
+import { isParsedKs256RootKey, type RootVerifyKey } from "./root-verify-key.js";
+import { resolveWithKs256Attestations } from "./select-ks256-attestation.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 function makeCheckpointLinkVerifier(opts: {
+  rootKeys: readonly RootVerifyKey[];
+  attestations?: readonly Ks256Attestation[] | undefined;
+  forestChainId?: bigint | undefined;
+}): CheckpointLinkVerifier {
+  const rootKeys = [...opts.rootKeys];
+  const attestations = opts.attestations ?? [];
+  const es256Roots = rootKeys.filter(
+    (k): k is CryptoKey => !isParsedKs256RootKey(k),
+  );
+  const records: CheckpointLinkRecord[] = [];
+  let failure: CheckpointLinkFailure | undefined;
+  let calls = 0;
+
+  const verifySignature = async (
+    checkpointBytes: Uint8Array,
+    detachedPayload: Uint8Array,
+  ): Promise<boolean> => {
+    const index = calls++;
+    const chosen = await resolveWithKs256Attestations(
+      checkpointBytes,
+      rootKeys,
+      attestations,
+      opts.forestChainId,
+    );
+    const resolution = chosen.resolution;
+    const fail = (reason: string): false => {
+      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: bigint;
+    try {
+      signedSize = checkpointConsistencyProof(checkpointBytes).signedTreeSize2;
+    } catch {
+      // The fold read the same label moments ago; fail closed.
+      return fail("proof_malformed");
+    }
+
+    const candidates: { key: CryptoKey; delegated: boolean }[] = [
+      ...(resolution.kind === "resolved"
+        ? [{ key: resolution.delegatedKey, delegated: true }]
+        : []),
+      ...es256Roots.map((key) => ({ key, delegated: false })),
+    ];
+    let signer: { key: CryptoKey; delegated: boolean } | undefined;
+    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: CheckpointLinkVerifiedBy = "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: CheckpointLinkRecord = {
+      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: DelegationConstraints,
+  signedSize: bigint,
+): { ok: true } | { ok: false; reason: "delegation_out_of_range" } {
+  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: readonly CheckpointLinkRecord[],
+  leaf: { mmrIndex: bigint; idtimestamp: bigint },
+): { ok: true } | { ok: false; reason: "delegation_expired"; at: number } {
+  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: Uint8Array): string {
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}

package/src/inclusion-walk-end.ts

@@ -0,0 +1,38 @@
+/**
+ * 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: bigint,
+  pathLength: number,
+): bigint {
+  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/src/index.ts

@@ -211,3 +211,33 @@ export {
   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";

package/src/known-accumulator.ts

@@ -33,8 +33,13 @@ import {
   decodeCborDeterministic,
   encodeCborDeterministic,
 } from "@forestrie/encoding";
-import { calculateRoot, type Proof } from "@forestrie/merklelog";
+import {
+  calculateRoot,
+  peakMMRIndexes,
+  type Proof,
+} 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";
@@ -243,23 +248,40 @@ export async function verifyReceiptOfflineAgainstKnownAccumulator(input: {
     };
   }
 
+  // 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: Uint8Array;
-  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,
+      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/src/ks256-attestation-usage.ts

@@ -0,0 +1,103 @@
+/**
+ * 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 function summarizeKs256AttestationUsage(
+  attestations: readonly Ks256Attestation[],
+  records: readonly CheckpointLinkRecord[],
+  failure?: CheckpointLinkFailure,
+): Ks256AttestationUsage {
+  const usage: Ks256AttestationUsage = { used: [], rejected: [], unused: [] };
+  const seen = [...records, ...(failure !== undefined ? [failure] : [])];
+  const tried = (i: number) =>
+    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: Ks256AttestationUnusedReason = "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: 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;
+}
+
+function bytesToHex(bytes: Uint8Array): string {
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}