@forestrie/forestrie-cli 0.10.0 → 0.11.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forestrie/forestrie-cli",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "description": "forestrie — participant CLI for forestrie transparency logs (SCITT / COSE receipts)",
   "keywords": [
     "forestrie",
@@ -66,12 +66,12 @@
   "dependencies": {
     "@forestrie/chain-rpc": "^0.3.0",
     "@forestrie/cli-kit": "^0.1.1",
-    "@forestrie/delegation-cose": "^0.3.2",
+    "@forestrie/delegation-cose": "0.4.0",
     "@forestrie/deploy-core": "^0.7.1",
     "@forestrie/encoding": "^0.9.1",
     "@forestrie/grant-builder": "^0.5.0",
     "@forestrie/merklelog": "^0.5.0",
-    "@forestrie/receipt-verify": "^3.0.1",
+    "@forestrie/receipt-verify": "3.1.0",
     "@forestrie/scrapi-client": "^0.2.2",
     "citty": "^0.2.2",
     "viem": "^2.31.0"

package/src/command.ts

@@ -45,6 +45,8 @@ export default defineForestrieCommand({
       import("./commands/verify-grant.js").then((m) => m.default),
     "fetch-accumulator": () =>
       import("./commands/fetch-accumulator.js").then((m) => m.default),
+    "fetch-ks256-attestation": () =>
+      import("./commands/fetch-ks256-attestation.js").then((m) => m.default),
     "create-consistency-proof": () =>
       import("./commands/create-consistency-proof.js").then((m) => m.default),
   },

package/src/commands/fetch-ks256-attestation.ts

@@ -0,0 +1,52 @@
+import { defineCommandRunner, defineForestrieCommand } from "../commoncli.js";
+import { runFetchKs256Attestation } from "../main/fetch-ks256-attestation.js";
+import { parseFetchKs256AttestationOptions } from "../options/fetch-ks256-attestation.js";
+
+export default defineForestrieCommand({
+  meta: {
+    name: "fetch-ks256-attestation",
+    description:
+      "Ask a KS256 contract root (a Safe) over ERC-1271 whether it signs the receipt's delegation certificate, and cache the block-bound answer as a --ks256-attestation artifact (CBOR binding chainId/address/digest/signature hash/block) — verify then accepts the contract-rooted receipt offline as valid under the contract's signers at that block. The answer is only as trustworthy as the RPC you name; for more confidence run it against several independent RPCs with the same --block and check they agree on the block hash. Auditable: anyone with RPC can re-run the call at that block. An EOA root needs no attestation (verify recovers it)",
+  },
+  args: {
+    receipt: {
+      type: "string",
+      description: "Receipt carrying the KS256 delegation certificate (label 1000)",
+      valueHint: "path",
+      required: true,
+    },
+    root: {
+      type: "string",
+      description:
+        "Contract root address (0x + 40 hex); overrides the genesis root",
+      valueHint: "address",
+    },
+    genesis: {
+      type: "string",
+      description:
+        "Forest genesis (genesis.cbor): supplies the KS256 root unless --root is given, and the chain id the RPC must match",
+      valueHint: "path",
+    },
+    "rpc-url": {
+      type: "string",
+      description: "JSON-RPC endpoint (default: ${env} → RPC_URL)",
+      valueHint: "url",
+    },
+    block: {
+      type: "string",
+      description:
+        "Block number to pin the calls to, or 'latest' (default). The attestation speaks for the contract's signers at this block, so pick one near the receipt's time for an authorised-at-issuance reading; old blocks need an archive node",
+      valueHint: "number|latest",
+    },
+    out: {
+      type: "string",
+      description: "Output path for the attestation CBOR",
+      valueHint: "path",
+      required: true,
+    },
+  },
+  run: defineCommandRunner(
+    parseFetchKs256AttestationOptions,
+    runFetchKs256Attestation,
+  ),
+});

package/src/commands/verify-grant.ts

@@ -18,8 +18,14 @@ export default defineForestrieCommand({
     "known-log-key": {
       type: "string",
       description:
-        "Caller-known log OWNER key (the delegation issuer), base64 x||y (64 bytes) (env KNOWN_LOG_KEY). Offline signer-provenance anchor that replaces --genesis; asserts (does not prove) the key-to-log binding — --genesis roots it in the forest genesis document's bootstrap key (the root log, or a delegation directly under it), while the accumulator roots (--known-accumulator / --rpc-url) supply split-view (freshness is a weaker, separate axis bearing only on coverage). See https://github.com/forestrie/protocol/blob/main/spec/receipt-trust-model.md",
-      valueHint: "base64",
+        "Caller-known log OWNER key (the delegation issuer): base64 x||y (64-byte ES256 key) or a 20-byte KS256 address (0x + 40 hex, or base64) (env KNOWN_LOG_KEY). Offline signer-provenance anchor that replaces --genesis (give --genesis too and it only supplies the forest chain id an attestation must match); asserts (does not prove) the key-to-log binding — --genesis roots it in the forest genesis document's bootstrap key (the root log, or a delegation directly under it), while the accumulator roots (--known-accumulator / --rpc-url) supply split-view (freshness is a weaker, separate axis bearing only on coverage). See https://github.com/forestrie/protocol/blob/main/spec/receipt-trust-model.md",
+      valueHint: "base64|0xaddress",
+    },
+    "ks256-attestation": {
+      type: "string",
+      description:
+        "ERC-1271 attestation (CBOR from `forestrie fetch-ks256-attestation`) for a KS256 contract root such as a Safe: the delegation certificate then verifies offline as valid under the contract's signers at the attested block, not as a signature by one key. Needs the forest chain id from --genesis. verify never calls the chain. Trust: an attestation is unsigned and only as good as whoever fetched it — accept one only from a party you would trust to read the chain for you, or fetch it yourself",
+      valueHint: "path",
     },
     receipt: {
       type: "string",

package/src/commands/verify.ts

@@ -18,8 +18,14 @@ export default defineForestrieCommand({
     "known-log-key": {
       type: "string",
       description:
-        "Caller-known log OWNER key (the delegation issuer), base64 x||y (64 bytes) (env KNOWN_LOG_KEY). Offline signer-provenance anchor that replaces --genesis; asserts (does not prove) the key-to-log binding — --genesis roots it in the forest genesis document's bootstrap key (the root log, or a delegation directly under it), while the accumulator roots (--known-accumulator / --rpc-url) supply split-view (freshness is a weaker, separate axis bearing only on coverage). See https://github.com/forestrie/protocol/blob/main/spec/receipt-trust-model.md",
-      valueHint: "base64",
+        "Caller-known log OWNER key (the delegation issuer): base64 x||y (64-byte ES256 key) or a 20-byte KS256 address (0x + 40 hex, or base64) (env KNOWN_LOG_KEY). Offline signer-provenance anchor that replaces --genesis (give --genesis too and it only supplies the forest chain id an attestation must match); asserts (does not prove) the key-to-log binding — --genesis roots it in the forest genesis document's bootstrap key (the root log, or a delegation directly under it), while the accumulator roots (--known-accumulator / --rpc-url) supply split-view (freshness is a weaker, separate axis bearing only on coverage). See https://github.com/forestrie/protocol/blob/main/spec/receipt-trust-model.md",
+      valueHint: "base64|0xaddress",
+    },
+    "ks256-attestation": {
+      type: "string",
+      description:
+        "ERC-1271 attestation (CBOR from `forestrie fetch-ks256-attestation`) for a KS256 contract root such as a Safe: the delegation certificate then verifies offline as valid under the contract's signers at the attested block, not as a signature by one key. Needs the forest chain id from --genesis. verify never calls the chain. Trust: an attestation is unsigned and only as good as whoever fetched it — accept one only from a party you would trust to read the chain for you, or fetch it yourself",
+      valueHint: "path",
     },
     receipt: {
       type: "string",

package/src/lib/known-log-key.ts

@@ -0,0 +1,35 @@
+import {
+  knownLogKeyFromBytes,
+  type RootVerifyKey,
+} from "@forestrie/receipt-verify";
+
+/** The accepted `--known-log-key` forms, for error messages and help. */
+export const KNOWN_LOG_KEY_FORMS =
+  "base64 x||y (64-byte ES256 public key) or a 20-byte KS256 address (0x + 40 hex, or base64)";
+
+/**
+ * Parse the caller-known log OWNER key (`--known-log-key`). Forms:
+ *
+ * - base64 of 64 bytes: an ES256 public key, x||y;
+ * - `0x` + 40 hex, or base64 of 20 bytes: a KS256 (Ethereum) address.
+ *
+ * Length alone decides the algorithm (via `knownLogKeyFromBytes`, the same
+ * rule univocity applies). Either way the caller ASSERTS the key owns the log.
+ */
+export async function parseKnownLogKey(value: string): Promise<RootVerifyKey> {
+  const v = value.trim();
+  const bytes = /^0x[0-9a-fA-F]{40}$/.test(v)
+    ? new Uint8Array(Buffer.from(v.slice(2), "hex"))
+    : new Uint8Array(Buffer.from(v, "base64"));
+  if (bytes.length !== 64 && bytes.length !== 20) {
+    throw new Error(
+      `--known-log-key must be ${KNOWN_LOG_KEY_FORMS}; decoded ${bytes.length} bytes`,
+    );
+  }
+  return knownLogKeyFromBytes(bytes);
+}
+
+/** True for a KS256 root (a `ParsedKs256RootKey`, not a WebCrypto key). */
+export function isKs256Root(key: RootVerifyKey): boolean {
+  return !(key instanceof CryptoKey);
+}

package/src/lib/verify-inputs.ts

@@ -64,7 +64,7 @@ export type LoadedVerifyArtifacts = Omit<
   "genesisCbor"
 > & { genesisCbor: Uint8Array | undefined };
 
-function readBytes(path: string, flag: string): Uint8Array {
+export function readBytes(path: string, flag: string): Uint8Array {
   try {
     return new Uint8Array(readFileSync(path));
   } catch (err) {

package/src/lib/verify-report.ts

@@ -2,6 +2,7 @@ import type {
   ReceiptVerifyResult,
   ReceiptVerifyStage,
 } from "@forestrie/receipt-verify";
+import type { Ks256Attestation } from "@forestrie/receipt-verify";
 import type { AnchorCheck } from "./verify-anchored.js";
 
 /**
@@ -110,6 +111,46 @@ export function knownKeyStageRows(result: ReceiptVerifyResult): StageRow[] {
   });
 }
 
+/**
+ * KS256 root facts for the report: whether the root is a KS256 address, how
+ * it was supplied, and any attestation given (with whether the certificate
+ * needed it, i.e. did not verify by ecrecover alone).
+ */
+export type Ks256ReportInfo = {
+  ks256Root: boolean;
+  knownKey: boolean;
+  attestation?: Ks256Attestation;
+  attestationUsed?: boolean;
+};
+
+/** Reword the parse/signature rows for a KS256 root or an attestation. */
+export function applyKs256Rows(
+  rows: StageRow[],
+  info: Ks256ReportInfo,
+): StageRow[] {
+  const att = info.attestation;
+  return rows.map((row) => {
+    if (row.status !== "ok") return row;
+    if (row.stage === "parse" && info.ks256Root) {
+      return {
+        ...row,
+        reason: `receipt COSE decodes; ${info.knownKey ? "caller-known log key" : "genesis trust root"} loads (KS256 address)`,
+      };
+    }
+    if (row.stage === "signature" && info.ks256Root) {
+      const anchorName = info.knownKey ? "caller-known log key" : "genesis root";
+      return {
+        ...row,
+        reason:
+          att !== undefined && info.attestationUsed === true
+            ? `delegation certificate valid under the contract's signers at block ${att.blockNumber} (ERC-1271 attestation; chain ${att.chainId}) — not a signature by one key`
+            : `delegation certificate recovers to the KS256 ${anchorName} (ecrecover)`,
+      };
+    }
+    return row;
+  });
+}
+
 export function stageRows(result: ReceiptVerifyResult): StageRow[] {
   if (result.ok) {
     return VERIFY_STAGES.map((stage) => ({ stage, status: "ok" }));
@@ -185,6 +226,19 @@ export type VerifyReport = {
   reason?: string;
   stages: StageRow[];
   anchor?: AnchorReport;
+  /** KS256 root and ERC-1271 attestation facts (present for a KS256 root). */
+  ks256?: {
+    root: boolean;
+    /** An unused attestation reports `used: false` only: its fields were
+     * never checked against anything, so they are not echoed. */
+    attestation?: {
+      used: boolean;
+      chainId?: string;
+      address?: string;
+      blockNumber?: string;
+      blockHash?: string;
+    };
+  };
 };
 
 /** Extra anchor facts present only for known-accumulator checks. */
@@ -203,6 +257,7 @@ export function buildVerifyReport(opts: {
   logId?: string | undefined;
   /** Anchor-only mode: rows that reflect the skipped signature stage. */
   stagesOverride?: StageRow[] | undefined;
+  ks256?: Ks256ReportInfo | undefined;
 }): VerifyReport {
   const report: VerifyReport = {
     command: "verify",
@@ -214,6 +269,25 @@ export function buildVerifyReport(opts: {
   if (opts.result.reason !== undefined) {
     report.reason = opts.result.reason;
   }
+  if (opts.ks256 !== undefined) {
+    const att = opts.ks256.attestation;
+    report.ks256 = {
+      root: opts.ks256.ks256Root,
+      ...(att !== undefined && opts.ks256.attestationUsed !== true
+        ? { attestation: { used: false } }
+        : att !== undefined
+        ? {
+            attestation: {
+              used: true,
+              chainId: att.chainId.toString(),
+              address: toHex(att.address),
+              blockNumber: att.blockNumber.toString(),
+              blockHash: toHex(att.blockHash),
+            },
+          }
+        : {}),
+    };
+  }
   if (opts.anchor !== undefined) {
     const anchor: AnchorReport = {
       univocity: opts.univocity ?? "",
@@ -263,3 +337,7 @@ export function buildVerifyReport(opts: {
   }
   return report;
 }
+
+function toHex(bytes: Uint8Array): string {
+  return `0x${Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("")}`;
+}

package/src/main/fetch-ks256-attestation.ts

@@ -0,0 +1,245 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import type { Out } from "@forestrie/cli-kit/reporting";
+import {
+  bytesToHex,
+  encodeIsValidSignatureCall,
+  ethRpc,
+  hexAddressToBytes,
+  normalizeHexAddress,
+} from "@forestrie/chain-rpc";
+import {
+  decodeChainBindingFromGenesis,
+  decodeTrustRootFromGenesis,
+  encodeKs256Attestation,
+  ERC1271_MAGIC_VALUE,
+  extractKs256DelegationDigest,
+} from "@forestrie/receipt-verify";
+import { keccak256 } from "viem";
+import type { FetchKs256AttestationOptions } from "../options/fetch-ks256-attestation.js";
+import { isKs256Root } from "../lib/known-log-key.js";
+
+/** `--json` success shape on stdout — stable for demo scripting. */
+export type FetchKs256AttestationReport = {
+  command: "fetch-ks256-attestation";
+  chainId: string;
+  address: string;
+  digest: string;
+  blockNumber: string;
+  blockHash: string;
+  out: string;
+};
+
+export type FetchKs256AttestationErrorReport = {
+  error: "fetch_ks256_attestation_failed";
+  command: "fetch-ks256-attestation";
+  message: string;
+};
+
+function readFile(path: string, flag: string): Uint8Array {
+  try {
+    return new Uint8Array(readFileSync(path));
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`cannot read ${flag} '${path}': ${message}`);
+  }
+}
+
+function hexToBigint(v: unknown, what: string): bigint {
+  if (typeof v !== "string" || !/^0x[0-9a-fA-F]+$/.test(v)) {
+    throw new Error(`${what}: expected a hex quantity, got ${String(v)}`);
+  }
+  return BigInt(v);
+}
+
+function hexToBytes32(v: unknown, what: string): Uint8Array {
+  if (typeof v !== "string" || !/^0x[0-9a-fA-F]{64}$/.test(v)) {
+    throw new Error(`${what}: expected a 32-byte hex value, got ${String(v)}`);
+  }
+  return new Uint8Array(Buffer.from(v.slice(2), "hex"));
+}
+
+/**
+ * Pin to one block, then: refuse an EOA root (no code), and require the
+ * contract's `isValidSignature(digest, signature)` to return the ERC-1271
+ * magic value for the certificate's own digest and signature. Nothing is
+ * written unless every check passes.
+ */
+export async function runFetchKs256Attestation(
+  out: Out,
+  options: FetchKs256AttestationOptions,
+): Promise<void> {
+  try {
+    const receiptCbor = readFile(options.receipt, "--receipt");
+    const genesisCbor =
+      options.genesis !== undefined
+        ? readFile(options.genesis, "--genesis")
+        : undefined;
+
+    let root: Uint8Array;
+    if (options.root !== undefined) {
+      const normalized = normalizeHexAddress(options.root);
+      if (normalized === null) {
+        throw new Error(`--root is not a valid address: '${options.root}'`);
+      }
+      root = hexAddressToBytes(normalized);
+    } else {
+      const trust = await decodeTrustRootFromGenesis(genesisCbor!);
+      if (!isKs256Root(trust)) {
+        throw new Error(
+          "the genesis root is not a KS256 address (an ES256 root needs no attestation)",
+        );
+      }
+      root = (trust as { address: Uint8Array }).address;
+    }
+
+    let genesisChainId: bigint | undefined;
+    if (genesisCbor !== undefined) {
+      genesisChainId = BigInt(decodeChainBindingFromGenesis(genesisCbor).chainId);
+    }
+
+    let parts: ReturnType<typeof extractKs256DelegationDigest>;
+    try {
+      parts = extractKs256DelegationDigest(receiptCbor);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      throw new Error(`the receipt's delegation certificate is not KS256: ${message}`);
+    }
+    if (parts === null) {
+      throw new Error("receipt carries no delegation certificate");
+    }
+
+    const chainId = hexToBigint(
+      await ethRpc(options.rpcUrl, "eth_chainId", []),
+      "eth_chainId",
+    );
+    if (genesisChainId !== undefined && chainId !== genesisChainId) {
+      throw new Error(
+        `RPC chain id ${chainId} differs from the genesis chain id ${genesisChainId}`,
+      );
+    }
+
+    const blockTag =
+      options.block === "latest" ? "latest" : `0x${options.block.toString(16)}`;
+    const block = (await ethRpc(options.rpcUrl, "eth_getBlockByNumber", [
+      blockTag,
+      false,
+    ])) as { number?: unknown; hash?: unknown } | null;
+    if (block === null || typeof block !== "object") {
+      throw new Error(`eth_getBlockByNumber returned no block for ${blockTag}`);
+    }
+    const blockNumber = hexToBigint(block.number, "block number");
+    if (options.block !== "latest" && blockNumber !== options.block) {
+      throw new Error(
+        `RPC returned block ${blockNumber} for --block ${options.block}`,
+      );
+    }
+    const blockHash = hexToBytes32(block.hash, "block hash");
+    // EIP-1898: read state at exactly the recorded block hash, so the
+    // attestation's blockHash is the state actually read (a reorg or a
+    // load-balanced RPC cannot answer from another block).
+    const pinned = {
+      blockHash: `0x${bytesToHex(blockHash)}`,
+      requireCanonical: true,
+    };
+    const rootHex = `0x${bytesToHex(root)}`;
+
+    const code = await ethRpc(options.rpcUrl, "eth_getCode", [rootHex, pinned]);
+    if (typeof code !== "string" || code === "0x" || code === "") {
+      throw new Error(
+        `${rootHex} has no contract code at block ${blockNumber}: an EOA root needs no attestation (verify recovers it by ecrecover)`,
+      );
+    }
+
+    let ret: unknown;
+    try {
+      ret = await ethRpc(options.rpcUrl, "eth_call", [
+        {
+          to: rootHex,
+          data: encodeIsValidSignatureCall(parts.digest, parts.signature),
+        },
+        pinned,
+      ]);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      // ethRpc surfaces only the JSON-RPC error message (not its code), so a
+      // revert is recognised by message; anything else (e.g. header not
+      // found) is an RPC failure that says nothing about the contract.
+      if (/revert/i.test(message)) {
+        throw new Error(
+          `${rootHex} did not validate the certificate signature (isValidSignature reverted: ${message})`,
+        );
+      }
+      throw new Error(
+        `RPC error on isValidSignature eth_call at block ${blockNumber}: ${message}`,
+      );
+    }
+    // Exactly one 32-byte word: bytes4 magic, left-aligned, zero padded.
+    // Anything else (extra data, dirty padding, a calldata echo from a
+    // fallback — the magic is also the selector) is not an attestation.
+    const expectedWord = `0x${bytesToHex(ERC1271_MAGIC_VALUE)}${"00".repeat(28)}`;
+    if (typeof ret !== "string" || !/^0x[0-9a-fA-F]{64}$/.test(ret)) {
+      throw new Error(
+        `isValidSignature did not return exactly one 32-byte word: ${String(ret)}`,
+      );
+    }
+    if (ret.toLowerCase() !== expectedWord) {
+      throw new Error(
+        `${rootHex} did not validate the certificate signature: isValidSignature returned ${ret}, not the ERC-1271 magic value word ${expectedWord}`,
+      );
+    }
+    const magic = ERC1271_MAGIC_VALUE.slice();
+
+    const signatureHash = new Uint8Array(
+      Buffer.from(keccak256(parts.signature).slice(2), "hex"),
+    );
+    writeFileSync(
+      options.out,
+      encodeKs256Attestation({
+        version: 1,
+        chainId,
+        address: root,
+        digest: parts.digest,
+        signatureHash,
+        blockNumber,
+        blockHash,
+        magic,
+      }),
+    );
+
+    if (options.json) {
+      const report: FetchKs256AttestationReport = {
+        command: "fetch-ks256-attestation",
+        chainId: chainId.toString(),
+        address: rootHex,
+        digest: `0x${bytesToHex(parts.digest)}`,
+        blockNumber: blockNumber.toString(),
+        blockHash: `0x${bytesToHex(blockHash)}`,
+        out: options.out,
+      };
+      out.out(JSON.stringify(report, null, 2));
+    } else {
+      out.print(
+        "fetch-ks256-attestation: %s signs digest 0x%s at block %s (chain %s)",
+        rootHex,
+        bytesToHex(parts.digest),
+        blockNumber.toString(),
+        chainId.toString(),
+      );
+      out.out(`wrote ERC-1271 attestation: ${options.out}`);
+    }
+    process.exitCode = 0;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (options.json) {
+      const report: FetchKs256AttestationErrorReport = {
+        error: "fetch_ks256_attestation_failed",
+        command: "fetch-ks256-attestation",
+        message,
+      };
+      out.out(JSON.stringify(report, null, 2));
+    } else {
+      out.warn("forestrie fetch-ks256-attestation: %s", message);
+    }
+    process.exitCode = 1;
+  }
+}