@forestrie/receipt-verify 3.0.0 → 3.1.0

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);

package/dist/verify-ks256-delegation.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 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 { type Ks256CertificateDigest } from "@forestrie/delegation-cose";
+import { type Ks256Attestation } from "./ks256-attestation.js";
+/**
+ * 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 declare function verifyKs256DelegationCert(certBytes: Uint8Array, rootAddress: Uint8Array, evidence: Ks256DelegationEvidence): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+}>;
+/**
+ * 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 declare function extractKs256DelegationDigest(receiptCbor: Uint8Array): Ks256CertificateDigest | null;
+//# sourceMappingURL=verify-ks256-delegation.d.ts.map

package/dist/verify-ks256-delegation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-ks256-delegation.d.ts","sourceRoot":"","sources":["../src/verify-ks256-delegation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,EAGL,KAAK,sBAAsB,EAC5B,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,wBAAwB,CAAC;AAKhC;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,WAAW,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;IAC3C,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAsB,yBAAyB,CAC7C,SAAS,EAAE,UAAU,EACrB,WAAW,EAAE,UAAU,EACvB,QAAQ,EAAE,uBAAuB,GAChC,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAiCvD;AAED;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,UAAU,GACtB,sBAAsB,GAAG,IAAI,CAQ/B"}

package/dist/verify-ks256-delegation.js

@@ -0,0 +1,95 @@
+/**
+ * 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, } from "@forestrie/delegation-cose";
+import { keccak_256 } from "@noble/hashes/sha3";
+import { ERC1271_MAGIC_VALUE, } from "./ks256-attestation.js";
+/** Unprotected header label carrying the delegation certificate. */
+const DELEGATION_CERT_LABEL = 1000;
+/**
+ * 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, rootAddress, evidence) {
+    let parts;
+    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) {
+    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, 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;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forestrie/receipt-verify",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "license": "MIT",
   "type": "module",
   "description": "Offline SCITT grant receipt verification (ADR-0045)",
@@ -28,11 +28,13 @@
   ],
   "dependencies": {
     "@noble/hashes": "^1.7.1",
+    "@forestrie/delegation-cose": "0.4.0",
     "@forestrie/encoding": "0.9.1",
     "@forestrie/merklelog": "0.5.0",
     "@forestrie/chain-rpc": "0.3.0"
   },
   "devDependencies": {
+    "@noble/curves": "^1.9.7",
     "esbuild": "^0.24.0",
     "typescript": "^5.9.2",
     "vitest": "^3.2.4"

package/src/build-receipt-offline.ts

@@ -59,10 +59,14 @@ export type ParsedCheckpoint = {
   /**
    * Sealed tree size: the SIGNED `tree-size-2` from the checkpoint's
    * PROTECTED header (ADR-0066 D1 as amended, label -65933), not the
-   * unprotected consistency proof's declared value. `null` when the
-   * checkpoint carries no embedded consistency proof or no signed
-   * tree-size-2 — such a checkpoint is not verifiable and callers must
-   * treat it exactly as they would a checkpoint with no proof at all.
+   * unprotected consistency proof's declared value. `null` ONLY when the
+   * checkpoint is genuinely unsealed — no embedded consistency proof, or a
+   * well-formed protected header with no signed tree-size-2 label — and
+   * callers must treat that the same as a checkpoint with no proof at all.
+   * A structurally malformed consistency proof, or a protected header that
+   * is not deterministically encoded (ADR-0066 D9), is a DIFFERENT
+   * condition — {@link parseCheckpoint} throws for those rather than
+   * folding them into this `null` (review finding O3).
    */
   mmrSize: bigint | null;
   delegationCert: Uint8Array | null;
@@ -273,26 +277,23 @@ function cborBytes(value: unknown): Uint8Array {
  * validating decode that requires the signed size and the last relayed
  * proof's to agree.
  *
- * Lenient by design: an absent proof, an empty or malformed
- * consistency-proofs array, or an absent or malformed signed tree-size-2
- * all yield `null` rather than a throw, so a caller of
- * {@link parseCheckpoint} sees exactly the same "not verifiable" outcome
- * either way.
+ * Lenient only for an ABSENT proof or an absent signed tree-size-2: both
+ * yield `null`, so a caller of {@link parseCheckpoint} sees the same "not
+ * verifiable" outcome for either. A proof or protected header that IS
+ * present but malformed is a different condition and is not swallowed here
+ * — {@link decodeConsistencyProofsFromUnprotected} throws for a structurally
+ * malformed proof (including an empty consistency-proofs array), and
+ * {@link readProtectedTreeSize2} throws for a protected header that is not
+ * deterministically encoded (ADR-0066 D9); both propagate rather than
+ * folding into `null` (review finding O3: a D9 conformance failure is a
+ * sealer-side defect worth attributing, not the ordinary "no proof yet"
+ * case).
  */
 function sealedSizeFromCheckpoint(
   coseSign1: CoseSign1,
   unprotected: Map<number, unknown>,
 ): bigint | null {
-  let declared;
-  try {
-    declared = decodeConsistencyProofsFromUnprotected(unprotected);
-  } catch {
-    return null;
-  }
+  const declared = decodeConsistencyProofsFromUnprotected(unprotected);
   if (declared === null) return null;
-  try {
-    return readProtectedTreeSize2(coseSign1[0]);
-  } catch {
-    return null;
-  }
+  return readProtectedTreeSize2(coseSign1[0]);
 }

package/src/decode-trust-root-cbor.ts

@@ -44,7 +44,16 @@ function parseAlgInt(raw: unknown): number | null {
   return null;
 }
 
-function ks256RootFromAddress(address: Uint8Array): ParsedKs256RootKey {
+/**
+ * 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: Uint8Array): ParsedKs256RootKey {
+  if (address.length !== 20) {
+    throw new Error("KS256 root address must be 20 bytes");
+  }
   return { kind: "KS256", alg: COSE_ALG_KS256, address };
 }
 

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

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