@forestrie/receipt-verify 3.0.1 → 3.2.0

package/dist/known-accumulator.js

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

package/dist/known-log-key.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 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 declare function knownLogKeyFromBytes(bytes: Uint8Array): Promise<RootVerifyKey>;
+//# sourceMappingURL=known-log-key.d.ts.map

package/dist/known-log-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"known-log-key.d.ts","sourceRoot":"","sources":["../src/known-log-key.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,UAAU,GAChB,OAAO,CAAC,aAAa,CAAC,CAMxB"}

package/dist/known-log-key.js

@@ -0,0 +1,20 @@
+/**
+ * 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";
+/**
+ * @param bytes - 64-byte ES256 x||y or 20-byte KS256 address.
+ * @throws When the length is neither.
+ */
+export async function knownLogKeyFromBytes(bytes) {
+    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/dist/ks256-attestation-usage.d.ts

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

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

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

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/ks256-attestation.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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).
+ */
+/** ERC-1271 `isValidSignature` success value, `bytes4(0x1626ba7e)`. */
+export declare const ERC1271_MAGIC_VALUE: Uint8Array<ArrayBuffer>;
+/** 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 declare function encodeKs256Attestation(attestation: Ks256Attestation): Uint8Array;
+/**
+ * Strict decode and shape validation of an attestation artifact: canonical
+ * CBOR, known labels only, version 1, exact types and lengths.
+ */
+export declare function decodeKs256Attestation(bytes: Uint8Array): Ks256Attestation;
+//# sourceMappingURL=ks256-attestation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ks256-attestation.d.ts","sourceRoot":"","sources":["../src/ks256-attestation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAOH,uEAAuE;AACvE,eAAO,MAAM,mBAAmB,yBAA2C,CAAC;AAyB5E,uEAAuE;AACvE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,OAAO,EAAE,UAAU,CAAC;IACpB,yEAAyE;IACzE,MAAM,EAAE,UAAU,CAAC;IACnB;;;OAGG;IACH,aAAa,EAAE,UAAU,CAAC;IAC1B,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,SAAS,EAAE,UAAU,CAAC;IACtB,0EAA0E;IAC1E,KAAK,EAAE,UAAU,CAAC;CACnB,CAAC;AAEF,4EAA4E;AAC5E,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,gBAAgB,GAC5B,UAAU,CAaZ;AAgBD;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,UAAU,GAAG,gBAAgB,CAkC1E"}

package/dist/ks256-attestation.js

@@ -0,0 +1,104 @@
+/**
+ * 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([
+    LABEL_VERSION,
+    LABEL_CHAIN_ID,
+    LABEL_ADDRESS,
+    LABEL_DIGEST,
+    LABEL_BLOCK_NUMBER,
+    LABEL_BLOCK_HASH,
+    LABEL_MAGIC,
+    LABEL_SIGNATURE_HASH,
+]);
+const ATTESTATION_VERSION = 1;
+/** Encode an attestation as canonical CBOR (RFC 8949 §4.2, hard policy). */
+export function encodeKs256Attestation(attestation) {
+    return encodeCborDeterministic(new Map([
+        [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, what) {
+    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, length, what) {
+    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) {
+    let decoded;
+    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)) {
+            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/dist/resolve-delegated-verify-key.d.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
@@ -34,6 +35,8 @@
  * `issuedAt` lower bound are NOT enforced (see that function). This replaces the
  * earlier "does not yet enforce the window" gap.
  */
+import { type RootVerifyKey } from "./root-verify-key.js";
+import { type Ks256DelegationEvidence } from "./verify-ks256-delegation.js";
 export declare function idtimestampToUnixSeconds(idtimestamp: bigint): number;
 /**
  * Snowflake idtimestamp → Unix milliseconds: the time component an
@@ -58,7 +61,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";
@@ -68,6 +72,7 @@ export type DelegatedResolution = {
     constraints: DelegationConstraints | null;
 } | {
     kind: "broken";
+    reason?: string;
 };
 /**
  * Enforce a resolved cert's constraints against the verified leaf (FOR-420).
@@ -107,7 +112,11 @@ export declare function checkDelegationConstraints(constraints: DelegationConstr
  * 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 declare function resolveDelegatedVerifyKey(receiptCbor: Uint8Array, rootKeys: CryptoKey[]): Promise<DelegatedResolution>;
+export declare function resolveDelegatedVerifyKey(receiptCbor: Uint8Array, rootKeys: RootVerifyKey[], ks256Evidence?: Ks256DelegationEvidence): Promise<DelegatedResolution>;
 //# sourceMappingURL=resolve-delegated-verify-key.d.ts.map

package/dist/resolve-delegated-verify-key.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-delegated-verify-key.d.ts","sourceRoot":"","sources":["../src/resolve-delegated-verify-key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAqCH,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAK/D;AAED;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAC3B;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,GACrB;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,YAAY,EAAE,SAAS,CAAC;IACxB,WAAW,EAAE,qBAAqB,GAAG,IAAI,CAAC;CAC3C,GACD;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AAsGvB;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,qBAAqB,EAClC,YAAY,EAAE,MAAM,EACpB,eAAe,EAAE,MAAM,GACtB;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAS9C;AAED;;;;;GAKG;AACH,wBAAsB,yBAAyB,CAC7C,WAAW,EAAE,UAAU,EACvB,QAAQ,EAAE,SAAS,EAAE,GACpB,OAAO,CAAC,mBAAmB,CAAC,CAgC9B"}
+{"version":3,"file":"resolve-delegated-verify-key.d.ts","sourceRoot":"","sources":["../src/resolve-delegated-verify-key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAQH,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAChF,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,8BAA8B,CAAC;AA8BtC,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAK/D;AAED;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,mBAAmB,GAC3B;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,GACrB;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,YAAY,EAAE,SAAS,CAAC;IACxB,WAAW,EAAE,qBAAqB,GAAG,IAAI,CAAC;CAC3C,GACD;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAsGxC;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,qBAAqB,EAClC,YAAY,EAAE,MAAM,EACpB,eAAe,EAAE,MAAM,GACtB;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAS9C;AAED;;;;;;;;;GASG;AACH,wBAAsB,yBAAyB,CAC7C,WAAW,EAAE,UAAU,EACvB,QAAQ,EAAE,aAAa,EAAE,EACzB,aAAa,GAAE,uBAA4B,GAC1C,OAAO,CAAC,mBAAmB,CAAC,CA8C9B"}

package/dist/resolve-delegated-verify-key.js

@@ -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
@@ -35,6 +36,8 @@
  * earlier "does not yet enforce the window" gap.
  */
 import { coseUnprotectedToMap, decodeCborDeterministic, decodeCoseSign1, verifyCoseSign1WithParsedKey, } from "@forestrie/encoding";
+import { isParsedKs256RootKey } from "./root-verify-key.js";
+import { verifyKs256DelegationCert, } from "./verify-ks256-delegation.js";
 /** Unprotected header label carrying the delegation certificate. */
 const DELEGATION_CERT_LABEL = 1000;
 /** COSE_Key labels (RFC 9052) and EC2/P-256 constants. */
@@ -207,9 +210,13 @@ export function checkDelegationConstraints(constraints, leafMmrIndex, leafIdtime
  * 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, rootKeys) {
+export async function resolveDelegatedVerifyKey(receiptCbor, rootKeys, ks256Evidence = {}) {
     const decoded = decodeCoseSign1(receiptCbor);
     if (!decoded)
         return { kind: "root-only" };
@@ -217,7 +224,17 @@ export async function resolveDelegatedVerifyKey(receiptCbor, rootKeys) {
     if (!certBytes)
         return { kind: "root-only" };
     let verified = false;
+    let ks256Reason;
     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",
         })) {
@@ -226,7 +243,7 @@ export async function resolveDelegatedVerifyKey(receiptCbor, rootKeys) {
         }
     }
     if (!verified)
-        return { kind: "broken" };
+        return { kind: "broken", reason: ks256Reason };
     const certDecoded = decodeCoseSign1(certBytes);
     if (!certDecoded)
         return { kind: "broken" };

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"}