@forestrie/receipt-verify 3.0.0 → 3.1.0

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

@@ -7,7 +7,10 @@ import {
 import type { Grant } from "@forestrie/encoding";
 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 type { Ks256Attestation } from "./ks256-attestation.js";
+import type { Ks256DelegationEvidence } from "./verify-ks256-delegation.js";
+import { isParsedKs256RootKey, type RootVerifyKey } from "./root-verify-key.js";
 import {
   checkDelegationConstraints,
   resolveDelegatedVerifyKey,
@@ -22,6 +25,8 @@ export type VerifyGrantReceiptOfflineInput = {
   receiptCbor: Uint8Array;
   grant: Grant;
   idtimestampBe8: Uint8Array;
+  /** See {@link VerifyReceiptOfflineInput.ks256Attestation}. */
+  ks256Attestation?: Ks256Attestation;
 };
 
 function readIdtimestampBe8(bytes: Uint8Array): bigint {
@@ -116,16 +121,15 @@ export async function verifyGrantReceiptOffline(
     receiptCbor: input.receiptCbor,
     idtimestampBe8: input.idtimestampBe8,
     inner,
+    ks256Attestation: input.ks256Attestation,
   });
 }
 
 export type VerifyGrantReceiptOfflineWithKeysInput = Omit<
   VerifyGrantReceiptOfflineInput,
   "genesisCbor"
-> & {
-  /** Caller-known ES256 trust keys — see {@link VerifyReceiptOfflineWithKeysInput}. */
-  trustKeys: CryptoKey[];
-};
+> &
+  Pick<VerifyReceiptOfflineWithKeysInput, "trustKeys" | "forestGenesisCbor">;
 
 /**
  * {@link verifyGrantReceiptOffline} under caller-supplied trust keys instead of
@@ -146,6 +150,7 @@ export async function verifyGrantReceiptOfflineWithKeys(
     idtimestampBe8: input.idtimestampBe8,
     inner,
     trustKeys: input.trustKeys,
+    ks256Evidence: withKeysKs256Evidence(input),
   });
 }
 
@@ -160,6 +165,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;
 };
 
 /**
@@ -183,6 +194,7 @@ export async function verifyReceiptOffline(
     receiptCbor: input.receiptCbor,
     idtimestampBe8: input.idtimestampBe8,
     inner,
+    ks256Attestation: input.ks256Attestation,
   });
 }
 
@@ -191,12 +203,19 @@ export type VerifyReceiptOfflineWithKeysInput = Omit<
   "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;
 };
 
 /**
@@ -230,9 +249,41 @@ export async function verifyReceiptOfflineWithKeys(
     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: {
+  ks256Attestation?: Ks256Attestation | undefined;
+  forestGenesisCbor?: Uint8Array | undefined;
+}): Ks256DelegationEvidence {
+  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: Uint8Array,
+): bigint | undefined {
+  try {
+    return BigInt(decodeChainBindingFromGenesis(genesisCbor).chainId);
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Shared offline-verify core: reconstruct the leaf as
  * `univocityLeafHash(idtimestamp, inner)`, resolve the (possibly delegated,
@@ -245,37 +296,42 @@ async function verifyReceiptOfflineWithLeafInner(input: {
   receiptCbor: Uint8Array;
   idtimestampBe8: Uint8Array;
   inner: Uint8Array;
+  ks256Attestation?: Ks256Attestation | undefined;
 }): Promise<ReceiptVerifyResult> {
-  let trustRoot;
+  let trustRoot: RootVerifyKey;
   try {
     trustRoot = await decodeTrustRootFromGenesis(input.genesisCbor);
   } catch {
     return { ok: false, stage: "parse", reason: "genesis_invalid" };
   }
 
-  const verifyKeys = es256ReceiptVerifyKeys([trustRoot]) as CryptoKey[];
-  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: {
   receiptCbor: Uint8Array;
   idtimestampBe8: Uint8Array;
   inner: Uint8Array;
-  trustKeys: CryptoKey[];
+  trustKeys: RootVerifyKey[];
+  ks256Evidence: Ks256DelegationEvidence;
 }): Promise<ReceiptVerifyResult> {
   let parsed: ReturnType<typeof parseReceipt>;
   try {
@@ -296,14 +352,31 @@ async function verifyReceiptOfflineWithLeafInnerKeys(input: {
   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): k is CryptoKey => !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: bigint;
   try {

package/src/verify-ks256-delegation.ts

@@ -0,0 +1,120 @@
+/**
+ * Offline KS256 root → delegation certificate check (plan-2610-03 D4, D5;
+ * protocol ADR-0045 amendment 2026-10-18). Receipts are always ES256, signed
+ * by a sealer's P-256 delegated key; what a KS256 root changes is how the
+ * label-1000 delegation certificate is checked against it.
+ *
+ * - An EOA root verifies by ecrecover through `@forestrie/delegation-cose`'s
+ *   `verifyDelegationCertificateKs256` with no hooks: pure, the same guarantee
+ *   as an ES256 root. delegation-cose also enforces the KS256 alg binding.
+ * - Anything ecrecover doesn't match (a contract root such as a Safe, or a
+ *   wrong signer: offline you can't tell which) fails with
+ *   `ks256_root_not_recovered`, unless the caller supplies an ERC-1271
+ *   attestation (ks256-attestation.ts) bound to this root, this digest, this
+ *   signature and the forest's genesis chain.
+ *
+ * No network and no injected callback: the chain read is a separate helper's
+ * job (forestrie-cli, mcp-resolve), as for the known accumulator.
+ */
+
+import { coseUnprotectedToMap, decodeCoseSign1 } from "@forestrie/encoding";
+import {
+  extractKs256CertificateDigest,
+  verifyDelegationCertificateKs256,
+  type Ks256CertificateDigest,
+} from "@forestrie/delegation-cose";
+import { keccak_256 } from "@noble/hashes/sha3";
+import {
+  ERC1271_MAGIC_VALUE,
+  type Ks256Attestation,
+} from "./ks256-attestation.js";
+
+/** Unprotected header label carrying the delegation certificate. */
+const DELEGATION_CERT_LABEL = 1000;
+
+/**
+ * Chain evidence a caller may supply for a KS256 contract root. `forestChainId`
+ * is read from the forest's genesis, never from the attestation or a
+ * coordinator; an attestation without it is refused.
+ */
+export type Ks256DelegationEvidence = {
+  attestation?: Ks256Attestation | undefined;
+  forestChainId?: bigint | undefined;
+};
+
+/**
+ * Check a delegation certificate against a KS256 root address.
+ *
+ * @param certBytes - The receipt's label-1000 COSE_Sign1 certificate.
+ * @param rootAddress - 20-byte root from genesis or a caller-known log key.
+ * @param evidence - Optional ERC-1271 attestation and the genesis chain id.
+ * @returns `ok`, or a stable reason: `delegation_not_ks256` (wrong alg,
+ *   WebAuthn envelope or malformed), `ks256_root_not_recovered`, or a
+ *   `ks256_attestation_*` mismatch.
+ */
+export async function verifyKs256DelegationCert(
+  certBytes: Uint8Array,
+  rootAddress: Uint8Array,
+  evidence: Ks256DelegationEvidence,
+): Promise<{ ok: true } | { ok: false; reason: string }> {
+  let parts: Ks256CertificateDigest;
+  try {
+    parts = extractKs256CertificateDigest(certBytes);
+  } catch {
+    return { ok: false, reason: "delegation_not_ks256" };
+  }
+  if (await verifyDelegationCertificateKs256(certBytes, rootAddress)) {
+    return { ok: true };
+  }
+  const { attestation, forestChainId } = evidence;
+  if (!attestation) {
+    return { ok: false, reason: "ks256_root_not_recovered" };
+  }
+  if (!bytesEqual(attestation.address, rootAddress)) {
+    return { ok: false, reason: "ks256_attestation_address_mismatch" };
+  }
+  if (!bytesEqual(attestation.digest, parts.digest)) {
+    return { ok: false, reason: "ks256_attestation_digest_mismatch" };
+  }
+  if (!bytesEqual(attestation.signatureHash, keccak_256(parts.signature))) {
+    return { ok: false, reason: "ks256_attestation_signature_mismatch" };
+  }
+  if (forestChainId === undefined) {
+    return { ok: false, reason: "ks256_attestation_chain_unbound" };
+  }
+  if (attestation.chainId !== forestChainId) {
+    return { ok: false, reason: "ks256_attestation_chain_mismatch" };
+  }
+  if (!bytesEqual(attestation.magic, ERC1271_MAGIC_VALUE)) {
+    return { ok: false, reason: "ks256_attestation_magic_invalid" };
+  }
+  return { ok: true };
+}
+
+/**
+ * Extract the KS256 delegation certificate's root address, digest and
+ * signature from a receipt: what an ERC-1271 attestation helper calls
+ * `isValidSignature` with. Does not verify anything.
+ *
+ * @param receiptCbor - COSE_Sign1 receipt bytes.
+ * @returns `null` when the receipt carries no label-1000 certificate.
+ * @throws When the certificate is not a KS256 certificate.
+ */
+export function extractKs256DelegationDigest(
+  receiptCbor: Uint8Array,
+): Ks256CertificateDigest | null {
+  const decoded = decodeCoseSign1(receiptCbor);
+  if (!decoded) throw new Error("receipt is not a COSE_Sign1");
+  const certRaw = coseUnprotectedToMap(decoded.unprotected).get(
+    DELEGATION_CERT_LABEL,
+  );
+  if (!(certRaw instanceof Uint8Array) || certRaw.length === 0) return null;
+  return extractKs256CertificateDigest(certRaw);
+}
+
+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;
+}