@forestrie/receipt-verify 3.0.1 → 3.1.0

package/dist/decode-trust-root-cbor.d.ts

@@ -1,6 +1,13 @@
 import type { ParsedVerifyKey } from "@forestrie/encoding";
-import { type RootVerifyKey } from "./root-verify-key.js";
+import { type ParsedKs256RootKey, type RootVerifyKey } from "./root-verify-key.js";
 export declare function importEs256PublicKeyFromGrantDataXy64(xy: Uint8Array): Promise<CryptoKey>;
+/**
+ * Wrap a 20-byte KS256 root address as a {@link ParsedKs256RootKey}.
+ *
+ * @throws When `address` is not 20 bytes: a key of any other length would
+ *   fail {@link isParsedKs256RootKey} and be mistaken for an ES256 key.
+ */
+export declare function ks256RootFromAddress(address: Uint8Array): ParsedKs256RootKey;
 export declare function decodeTrustRootCbor(decoded: unknown): Promise<RootVerifyKey>;
 export declare function es256ReceiptVerifyKeys(keys: RootVerifyKey[]): ParsedVerifyKey[];
 //# sourceMappingURL=decode-trust-root-cbor.d.ts.map

package/dist/decode-trust-root-cbor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decode-trust-root-cbor.d.ts","sourceRoot":"","sources":["../src/decode-trust-root-cbor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAE9B,wBAAsB,qCAAqC,CACzD,EAAE,EAAE,UAAU,GACb,OAAO,CAAC,SAAS,CAAC,CAgBpB;AAsCD,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,aAAa,CAAC,CAwCxB;AAED,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,aAAa,EAAE,GACpB,eAAe,EAAE,CAEnB"}
+{"version":3,"file":"decode-trust-root-cbor.d.ts","sourceRoot":"","sources":["../src/decode-trust-root-cbor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAE9B,wBAAsB,qCAAqC,CACzD,EAAE,EAAE,UAAU,GACb,OAAO,CAAC,SAAS,CAAC,CAgBpB;AAoBD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,UAAU,GAAG,kBAAkB,CAK5E;AAgBD,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,aAAa,CAAC,CAwCxB;AAED,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,aAAa,EAAE,GACpB,eAAe,EAAE,CAEnB"}

package/dist/decode-trust-root-cbor.js

@@ -28,7 +28,16 @@ function parseAlgInt(raw) {
     }
     return null;
 }
-function ks256RootFromAddress(address) {
+/**
+ * Wrap a 20-byte KS256 root address as a {@link ParsedKs256RootKey}.
+ *
+ * @throws When `address` is not 20 bytes: a key of any other length would
+ *   fail {@link isParsedKs256RootKey} and be mistaken for an ES256 key.
+ */
+export function ks256RootFromAddress(address) {
+    if (address.length !== 20) {
+        throw new Error("KS256 root address must be 20 bytes");
+    }
     return { kind: "KS256", alg: COSE_ALG_KS256, address };
 }
 function recordToTrustRootFields(decoded) {

package/dist/index.d.ts

@@ -48,6 +48,21 @@ export { checkDelegationConstraints, idtimestampToUnixMs, idtimestampToUnixSecon
 export type { DelegatedResolution, DelegationConstraints, } 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

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -37,6 +37,18 @@ export { verifyGrantReceiptOfflineWithKeys, verifyReceiptOfflineWithKeys, } from
 export { checkDelegationConstraints, idtimestampToUnixMs, idtimestampToUnixSeconds, resolveDelegatedVerifyKey, } 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 { ERC1271_MAGIC_VALUE, decodeKs256Attestation, encodeKs256Attestation, } from "./ks256-attestation.js";
+export { extractKs256DelegationDigest, verifyKs256DelegationCert, } from "./verify-ks256-delegation.js";
 /**
  * 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

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.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/verify-grant-receipt-offline.d.ts

@@ -1,19 +1,20 @@
 import type { Grant } from "@forestrie/encoding";
+import type { Ks256Attestation } from "./ks256-attestation.js";
+import { type RootVerifyKey } from "./root-verify-key.js";
 import type { ReceiptVerifyResult } from "./receipt-verify-result.js";
 export type VerifyGrantReceiptOfflineInput = {
     genesisCbor: Uint8Array;
     receiptCbor: Uint8Array;
     grant: Grant;
     idtimestampBe8: Uint8Array;
+    /** See {@link VerifyReceiptOfflineInput.ks256Attestation}. */
+    ks256Attestation?: Ks256Attestation;
 };
 /**
  * Offline grant receipt verify (layers A–C, ADR-0045). Pure over bytes; no network.
  */
 export declare function verifyGrantReceiptOffline(input: VerifyGrantReceiptOfflineInput): Promise<ReceiptVerifyResult>;
-export type VerifyGrantReceiptOfflineWithKeysInput = Omit<VerifyGrantReceiptOfflineInput, "genesisCbor"> & {
-    /** Caller-known ES256 trust keys — see {@link VerifyReceiptOfflineWithKeysInput}. */
-    trustKeys: CryptoKey[];
-};
+export type VerifyGrantReceiptOfflineWithKeysInput = Omit<VerifyGrantReceiptOfflineInput, "genesisCbor"> & Pick<VerifyReceiptOfflineWithKeysInput, "trustKeys" | "forestGenesisCbor">;
 /**
  * {@link verifyGrantReceiptOffline} under caller-supplied trust keys instead of
  * the genesis trust root — see {@link verifyReceiptOfflineWithKeys} for the
@@ -31,6 +32,12 @@ export type VerifyReceiptOfflineInput = {
      */
     payload: Uint8Array;
     idtimestampBe8: Uint8Array;
+    /**
+     * ERC-1271 attestation for a KS256 contract root (plan-2610-03 D4). Used
+     * only when ecrecover doesn't match the root, and accepted only when it
+     * binds the root address, the certificate digest and the genesis chain id.
+     */
+    ks256Attestation?: Ks256Attestation;
 };
 /**
  * Offline verify of a receipt against the EXACT registered payload. The log
@@ -42,12 +49,19 @@ export type VerifyReceiptOfflineInput = {
 export declare function verifyReceiptOffline(input: VerifyReceiptOfflineInput): Promise<ReceiptVerifyResult>;
 export type VerifyReceiptOfflineWithKeysInput = Omit<VerifyReceiptOfflineInput, "genesisCbor"> & {
     /**
-     * Caller-known ES256 trust keys, tried in order. For a child-log receipt
+     * Caller-known trust keys, tried in order: ES256 `CryptoKey`s or KS256
+     * 20-byte addresses ({@link knownLogKeyFromBytes}). For a child-log receipt
      * this is the log OWNER's key (the delegation-cert issuer), NOT the sealer
      * key — the label-1000 cert is verified under these keys and the delegated
      * sealer key is extracted from it, so the anchor survives sealer rotation.
      */
-    trustKeys: CryptoKey[];
+    trustKeys: RootVerifyKey[];
+    /**
+     * The forest's genesis, read only for the chain id a `ks256Attestation`
+     * must match (D6); it supplies no trust keys. Without it an attestation is
+     * refused with `ks256_attestation_chain_unbound`.
+     */
+    forestGenesisCbor?: Uint8Array;
 };
 /**
  * {@link verifyReceiptOffline} under caller-supplied trust keys instead of the

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

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

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

@@ -2,7 +2,8 @@ import { verifyCoseSign1WithParsedKey } from "@forestrie/encoding";
 import { calculateRoot, verifyInclusion, } from "@forestrie/merklelog";
 import { grantCommitmentHashFromGrant } from "./grant-commitment.js";
 import { decodeTrustRootFromGenesis } from "./decode-trust-root-from-genesis.js";
-import { es256ReceiptVerifyKeys } from "./decode-trust-root-cbor.js";
+import { decodeChainBindingFromGenesis } from "./decode-chain-binding-from-genesis.js";
+import { isParsedKs256RootKey } from "./root-verify-key.js";
 import { checkDelegationConstraints, resolveDelegatedVerifyKey, } from "./resolve-delegated-verify-key.js";
 import { univocityLeafHash } from "./leaf-commitment.js";
 import { parseReceipt } from "./parse-receipt.js";
@@ -72,6 +73,7 @@ export async function verifyGrantReceiptOffline(input) {
         receiptCbor: input.receiptCbor,
         idtimestampBe8: input.idtimestampBe8,
         inner,
+        ks256Attestation: input.ks256Attestation,
     });
 }
 /**
@@ -92,6 +94,7 @@ export async function verifyGrantReceiptOfflineWithKeys(input) {
         idtimestampBe8: input.idtimestampBe8,
         inner,
         trustKeys: input.trustKeys,
+        ks256Evidence: withKeysKs256Evidence(input),
     });
 }
 /**
@@ -108,6 +111,7 @@ export async function verifyReceiptOffline(input) {
         receiptCbor: input.receiptCbor,
         idtimestampBe8: input.idtimestampBe8,
         inner,
+        ks256Attestation: input.ks256Attestation,
     });
 }
 /**
@@ -134,8 +138,35 @@ export async function verifyReceiptOfflineWithKeys(input) {
         idtimestampBe8: input.idtimestampBe8,
         inner,
         trustKeys: input.trustKeys,
+        ks256Evidence: withKeysKs256Evidence(input),
     });
 }
+/**
+ * KS256 chain evidence for the caller-known-key entries: the attestation, and
+ * the chain id from the forest genesis the caller supplied, if any.
+ */
+function withKeysKs256Evidence(input) {
+    if (!input.ks256Attestation)
+        return {};
+    return {
+        attestation: input.ks256Attestation,
+        forestChainId: input.forestGenesisCbor
+            ? genesisChainIdOrUndefined(input.forestGenesisCbor)
+            : undefined,
+    };
+}
+/**
+ * The forest's chain id from its genesis chain binding, or `undefined` when
+ * the genesis carries none (an attestation then can't be bound, D6).
+ */
+function genesisChainIdOrUndefined(genesisCbor) {
+    try {
+        return BigInt(decodeChainBindingFromGenesis(genesisCbor).chainId);
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Shared offline-verify core: reconstruct the leaf as
  * `univocityLeafHash(idtimestamp, inner)`, resolve the (possibly delegated,
@@ -151,21 +182,25 @@ async function verifyReceiptOfflineWithLeafInner(input) {
     catch {
         return { ok: false, stage: "parse", reason: "genesis_invalid" };
     }
-    const verifyKeys = es256ReceiptVerifyKeys([trustRoot]);
-    if (!verifyKeys.length) {
-        return { ok: false, stage: "signature", reason: "no_es256_trust_key" };
-    }
     return verifyReceiptOfflineWithLeafInnerKeys({
         receiptCbor: input.receiptCbor,
         idtimestampBe8: input.idtimestampBe8,
         inner: input.inner,
-        trustKeys: verifyKeys,
+        trustKeys: [trustRoot],
+        ks256Evidence: input.ks256Attestation
+            ? {
+                attestation: input.ks256Attestation,
+                forestChainId: genesisChainIdOrUndefined(input.genesisCbor),
+            }
+            : {},
     });
 }
 /**
  * Trust-key-parameterised offline-verify core. Identical to the genesis path
  * once the trust keys are in hand: resolve the (possibly delegated, FOR-297)
- * verify key against `trustKeys`, then check signature + inclusion.
+ * verify key against `trustKeys`, then check signature + inclusion. Receipts
+ * are always ES256, so a KS256 trust key only ever verifies the delegation
+ * certificate; only ES256 trust keys are tried on the receipt itself.
  */
 async function verifyReceiptOfflineWithLeafInnerKeys(input) {
     let parsed;
@@ -183,13 +218,27 @@ async function verifyReceiptOfflineWithLeafInnerKeys(input) {
     // delegated key first. A cert present but not chaining to a trust key is a
     // hard failure — do not silently fall back to the trust key (which cannot
     // verify a delegated-signed receipt anyway).
-    const delegation = await resolveDelegatedVerifyKey(input.receiptCbor, input.trustKeys);
+    const delegation = await resolveDelegatedVerifyKey(input.receiptCbor, input.trustKeys, input.ks256Evidence);
     if (delegation.kind === "broken") {
-        return { ok: false, stage: "signature", reason: "delegation_invalid" };
+        return {
+            ok: false,
+            stage: "signature",
+            reason: delegation.reason ?? "delegation_invalid",
+        };
+    }
+    const es256TrustKeys = input.trustKeys.filter((k) => !isParsedKs256RootKey(k));
+    if (delegation.kind === "root-only" && !es256TrustKeys.length) {
+        // A KS256 root never signs a receipt; without a certificate there is no
+        // ES256 key to check it with.
+        return {
+            ok: false,
+            stage: "signature",
+            reason: "ks256_root_requires_delegation",
+        };
     }
     const allVerifyKeys = delegation.kind === "resolved"
-        ? [delegation.delegatedKey, ...input.trustKeys]
-        : input.trustKeys;
+        ? [delegation.delegatedKey, ...es256TrustKeys]
+        : es256TrustKeys;
     let idtimestamp;
     try {
         idtimestamp = readIdtimestampBe8(input.idtimestampBe8);