@forestrie/receipt-verify 3.0.1 → 3.2.0

package/src/index.ts

@@ -89,6 +89,29 @@ export type {
 } from "./resolve-delegated-verify-key.js";
 /** Import a raw 64-byte x||y P-256 public key as an ES256 verify key. */
 export { importEs256PublicKeyFromGrantDataXy64 } from "./decode-trust-root-cbor.js";
+/**
+ * KS256 roots in offline verification (plan-2610-03 D4–D6, protocol ADR-0045
+ * amendment 2026-10-18). A KS256 root comes only from genesis, a caller-known
+ * log key ({@link knownLogKeyFromBytes}: asserts, does not prove) or, for a
+ * contract root, a caller-supplied ERC-1271 attestation; never from the
+ * delegation coordinator. EOA roots verify by ecrecover; anything else needs
+ * an attestation or fails with `ks256_root_not_recovered`.
+ */
+export { knownLogKeyFromBytes } from "./known-log-key.js";
+export { ks256RootFromAddress } from "./decode-trust-root-cbor.js";
+export type { ParsedKs256RootKey, RootVerifyKey } from "./root-verify-key.js";
+export {
+  ERC1271_MAGIC_VALUE,
+  decodeKs256Attestation,
+  encodeKs256Attestation,
+  type Ks256Attestation,
+} from "./ks256-attestation.js";
+export {
+  extractKs256DelegationDigest,
+  verifyKs256DelegationCert,
+} from "./verify-ks256-delegation.js";
+export type { Ks256DelegationEvidence } from "./verify-ks256-delegation.js";
+export type { Ks256CertificateDigest } from "@forestrie/delegation-cose";
 /**
  * Passkey session-key endorsement v2 (ADR-0064 as amended by ADR-0065):
  * build, assemble, and verify the artifact chaining a passkey log root to the
@@ -188,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/known-log-key.ts

@@ -0,0 +1,28 @@
+/**
+ * Caller-known log key bytes → trust key (FOR-297 "known log key"; plan-2610-03
+ * D6). The bytes alone decide the type, as univocity's
+ * `GrantDataInvalidKeyLength` and arbor's `grantDataIdentity` do: 64 bytes is
+ * an ES256 x||y public key, 20 bytes a KS256 address, anything else is
+ * refused. Either way the caller ASSERTS, and does not prove, that the key
+ * owns the log — see `verifyReceiptOfflineWithKeys`.
+ */
+
+import {
+  importEs256PublicKeyFromGrantDataXy64,
+  ks256RootFromAddress,
+} from "./decode-trust-root-cbor.js";
+import type { RootVerifyKey } from "./root-verify-key.js";
+
+/**
+ * @param bytes - 64-byte ES256 x||y or 20-byte KS256 address.
+ * @throws When the length is neither.
+ */
+export async function knownLogKeyFromBytes(
+  bytes: Uint8Array,
+): Promise<RootVerifyKey> {
+  if (bytes.length === 64) return importEs256PublicKeyFromGrantDataXy64(bytes);
+  if (bytes.length === 20) return ks256RootFromAddress(bytes);
+  throw new Error(
+    `known log key must be 64 bytes (ES256 x||y) or 20 bytes (KS256 address), got ${bytes.length}`,
+  );
+}

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("");
+}

package/src/ks256-attestation.ts

@@ -0,0 +1,144 @@
+/**
+ * ERC-1271 attestation (plan-2610-03 D4, protocol ADR-0045 amendment
+ * 2026-10-18): a caller-supplied record that a contract KS256 root (a Safe)
+ * answered `isValidSignature(digest, signature)` with the ERC-1271 magic value
+ * at a given block. It lets a contract-rooted delegation certificate verify
+ * offline with the narrower guarantee "valid under the contract's signers at
+ * the attested block".
+ *
+ * Same trust model as the known-accumulator snapshot (known-accumulator.ts):
+ * the record is the fetching party's chain read, made explicit and auditable.
+ * It binds `(chainId, address, digest, signature hash, block)`, so anyone with
+ * RPC can re-run exactly that call at that block (the signature itself is in
+ * the receipt's certificate) and confirm or disprove it. This package never makes
+ * that call; forestrie-cli and mcp-resolve fetch it (slice 04).
+ *
+ * The verifier accepts an attestation only for the exact root address and
+ * certificate digest, and only when `chainId` equals the forest's genesis
+ * chain: the same Safe address on another chain can have other owners (D6).
+ */
+
+import {
+  decodeCborDeterministic,
+  encodeCborDeterministic,
+} from "@forestrie/encoding";
+
+/** ERC-1271 `isValidSignature` success value, `bytes4(0x1626ba7e)`. */
+export const ERC1271_MAGIC_VALUE = new Uint8Array([0x16, 0x26, 0xba, 0x7e]);
+
+/** CBOR map labels for the attestation artifact (strict RFC 8949 §4.2). */
+const LABEL_VERSION = 1;
+const LABEL_CHAIN_ID = 2;
+const LABEL_ADDRESS = 3;
+const LABEL_DIGEST = 4;
+const LABEL_BLOCK_NUMBER = 5;
+const LABEL_BLOCK_HASH = 6;
+const LABEL_MAGIC = 7;
+const LABEL_SIGNATURE_HASH = 8;
+
+const KNOWN_LABELS = new Set<number>([
+  LABEL_VERSION,
+  LABEL_CHAIN_ID,
+  LABEL_ADDRESS,
+  LABEL_DIGEST,
+  LABEL_BLOCK_NUMBER,
+  LABEL_BLOCK_HASH,
+  LABEL_MAGIC,
+  LABEL_SIGNATURE_HASH,
+]);
+
+const ATTESTATION_VERSION = 1;
+
+/** A block-bound ERC-1271 `isValidSignature` result for one digest. */
+export type Ks256Attestation = {
+  version: number;
+  /** Chain the call was made on; must equal the forest's genesis chain. */
+  chainId: bigint;
+  /** Contract root address (20 bytes) the call was made to. */
+  address: Uint8Array;
+  /** keccak256(Sig_structure) of the delegation certificate (32 bytes). */
+  digest: Uint8Array;
+  /**
+   * keccak256 of the signature bytes `isValidSignature` was called with
+   * (32 bytes); must match the certificate's signature.
+   */
+  signatureHash: Uint8Array;
+  /** Block the call was made at. */
+  blockNumber: bigint;
+  /** Hash of that block (32 bytes): the falsifiability handle. */
+  blockHash: Uint8Array;
+  /** The call's 4-byte return; only {@link ERC1271_MAGIC_VALUE} attests. */
+  magic: Uint8Array;
+};
+
+/** Encode an attestation as canonical CBOR (RFC 8949 §4.2, hard policy). */
+export function encodeKs256Attestation(
+  attestation: Ks256Attestation,
+): Uint8Array {
+  return encodeCborDeterministic(
+    new Map<number, unknown>([
+      [LABEL_VERSION, attestation.version],
+      [LABEL_CHAIN_ID, attestation.chainId],
+      [LABEL_ADDRESS, attestation.address],
+      [LABEL_DIGEST, attestation.digest],
+      [LABEL_BLOCK_NUMBER, attestation.blockNumber],
+      [LABEL_BLOCK_HASH, attestation.blockHash],
+      [LABEL_MAGIC, attestation.magic],
+      [LABEL_SIGNATURE_HASH, attestation.signatureHash],
+    ]),
+  );
+}
+
+function asBigint(v: unknown, what: string): bigint {
+  if (typeof v === "bigint") return v;
+  if (typeof v === "number" && Number.isSafeInteger(v) && v >= 0)
+    return BigInt(v);
+  throw new Error(`ks256 attestation: ${what} must be an unsigned integer`);
+}
+
+function asBytes(v: unknown, length: number, what: string): Uint8Array {
+  if (!(v instanceof Uint8Array) || v.length !== length) {
+    throw new Error(`ks256 attestation: ${what} must be ${length} bytes`);
+  }
+  return v;
+}
+
+/**
+ * Strict decode and shape validation of an attestation artifact: canonical
+ * CBOR, known labels only, version 1, exact types and lengths.
+ */
+export function decodeKs256Attestation(bytes: Uint8Array): Ks256Attestation {
+  let decoded: unknown;
+  try {
+    decoded = decodeCborDeterministic(bytes);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`ks256 attestation is not canonical CBOR: ${message}`);
+  }
+  if (!(decoded instanceof Map)) {
+    throw new Error("ks256 attestation must be a CBOR map");
+  }
+  for (const label of decoded.keys()) {
+    if (!KNOWN_LABELS.has(label as number)) {
+      throw new Error(`ks256 attestation: unknown label ${String(label)}`);
+    }
+  }
+  const version = Number(asBigint(decoded.get(LABEL_VERSION), "version"));
+  if (version !== ATTESTATION_VERSION) {
+    throw new Error(`ks256 attestation version ${version} not supported`);
+  }
+  return {
+    version,
+    chainId: asBigint(decoded.get(LABEL_CHAIN_ID), "chainId"),
+    address: asBytes(decoded.get(LABEL_ADDRESS), 20, "address"),
+    digest: asBytes(decoded.get(LABEL_DIGEST), 32, "digest"),
+    blockNumber: asBigint(decoded.get(LABEL_BLOCK_NUMBER), "blockNumber"),
+    blockHash: asBytes(decoded.get(LABEL_BLOCK_HASH), 32, "blockHash"),
+    magic: asBytes(decoded.get(LABEL_MAGIC), 4, "magic"),
+    signatureHash: asBytes(
+      decoded.get(LABEL_SIGNATURE_HASH),
+      32,
+      "signatureHash",
+    ),
+  };
+}

package/src/resolve-delegated-verify-key.ts

@@ -6,12 +6,13 @@
  * trust root and returns the delegated public key as an additional verify
  * candidate — the offline port of canopy-api's `resolveReceiptVerifyKey`.
  *
- * P-256 roots only: the genesis alg is ES256 and sealer delegate keys are
- * always secp256r1; KS256-rooted delegation is a server-only concern. A
- * passkey (WebAuthn) root signs the certificate with alg -65800 and the
- * ADR-0063 unprotected-header envelope — `verifyCoseSign1WithParsedKey`
- * verifies that envelope against the same P-256 root keys, so the chain walk
- * here is alg-agnostic (plan-2608-13 1.4).
+ * Sealer delegate keys are always secp256r1. A P-256 root's certificate is
+ * checked here; a passkey (WebAuthn) root signs the certificate with alg
+ * -65800 and the ADR-0063 unprotected-header envelope, which
+ * `verifyCoseSign1WithParsedKey` verifies against the same P-256 root keys
+ * (plan-2608-13 1.4). A KS256 root's certificate is checked by
+ * {@link verifyKs256DelegationCert}: ecrecover for an EOA, or a caller-supplied
+ * ERC-1271 attestation for a contract (plan-2610-03 D4).
  *
  * Trust anchors (FOR-297 trust ladder): `rootKeys` need not be genesis-derived
  * — a caller-known log OWNER key works identically (see
@@ -41,6 +42,11 @@ import {
   decodeCoseSign1,
   verifyCoseSign1WithParsedKey,
 } from "@forestrie/encoding";
+import { isParsedKs256RootKey, type RootVerifyKey } from "./root-verify-key.js";
+import {
+  verifyKs256DelegationCert,
+  type Ks256DelegationEvidence,
+} from "./verify-ks256-delegation.js";
 
 /** Unprotected header label carrying the delegation certificate. */
 const DELEGATION_CERT_LABEL = 1000;
@@ -104,7 +110,8 @@ export type DelegationConstraints = {
  *   `constraints` carries the cert's coverage/validity window when the payload
  *   declares it (null for legacy certs that predate labels 3/4/8/9).
  * broken: a cert is present but did not verify under the root, or its delegated
- *   key could not be parsed — the delegation chain is invalid.
+ *   key could not be parsed — the delegation chain is invalid. `reason` is set
+ *   when a KS256 root gives a more specific one than `delegation_invalid`.
  */
 export type DelegatedResolution =
   | { kind: "root-only" }
@@ -113,7 +120,7 @@ export type DelegatedResolution =
       delegatedKey: CryptoKey;
       constraints: DelegationConstraints | null;
     }
-  | { kind: "broken" };
+  | { kind: "broken"; reason?: string };
 
 function extractDelegationCertBytes(unprotected: unknown): Uint8Array | null {
   const umap = coseUnprotectedToMap(unprotected);
@@ -262,11 +269,16 @@ export function checkDelegationConstraints(
  * Resolve the delegated verify key from a receipt's delegation certificate.
  *
  * @param receiptCbor - the COSE_Sign1 receipt bytes.
- * @param rootKeys - genesis-derived ES256 root verify keys.
+ * @param rootKeys - trust roots: ES256 keys and KS256 addresses, from genesis
+ *   or caller-known log keys. A KS256 root never comes from the coordinator
+ *   (its public roots are last-write-wins, FOR-601/FOR-603).
+ * @param ks256Evidence - optional ERC-1271 attestation for a KS256 contract
+ *   root, with the forest's genesis chain id it must match.
  */
 export async function resolveDelegatedVerifyKey(
   receiptCbor: Uint8Array,
-  rootKeys: CryptoKey[],
+  rootKeys: RootVerifyKey[],
+  ks256Evidence: Ks256DelegationEvidence = {},
 ): Promise<DelegatedResolution> {
   const decoded = decodeCoseSign1(receiptCbor);
   if (!decoded) return { kind: "root-only" };
@@ -275,7 +287,21 @@ export async function resolveDelegatedVerifyKey(
   if (!certBytes) return { kind: "root-only" };
 
   let verified = false;
+  let ks256Reason: string | undefined;
   for (const rootKey of rootKeys) {
+    if (isParsedKs256RootKey(rootKey)) {
+      const check = await verifyKs256DelegationCert(
+        certBytes,
+        rootKey.address,
+        ks256Evidence,
+      );
+      if (check.ok) {
+        verified = true;
+        break;
+      }
+      ks256Reason ??= check.reason;
+      continue;
+    }
     if (
       await verifyCoseSign1WithParsedKey(certBytes, rootKey, {
         logPrefix: "delegation-cert-offline",
@@ -285,7 +311,7 @@ export async function resolveDelegatedVerifyKey(
       break;
     }
   }
-  if (!verified) return { kind: "broken" };
+  if (!verified) return { kind: "broken", reason: ks256Reason };
 
   const certDecoded = decodeCoseSign1(certBytes);
   if (!certDecoded) return { kind: "broken" };

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;
+}