@forestrie/forestrie-cli 0.9.1 → 0.11.0

package/src/lib/resolve-receipt-freshen.ts

@@ -39,6 +39,7 @@ import {
   calldataCheckpointChain,
   sthCheckpointChain,
   type CheckpointLink,
+  singleProofChain,
 } from "./checkpoint-provider.js";
 import { univocityLeafHash } from "./verify-anchored.js";
 import { bytesEqual } from "./bytes.js";
@@ -102,16 +103,11 @@ async function emitFreshened(opts: {
   const result = await freshenReceipt({
     oldReceiptBytes: opts.oldReceiptBytes,
     leafValue: opts.leafValue,
-    // `freshenReceipt`'s consistency-proof array type carries
-    // `signedTreeSize2` (checked at `.sth` decode time), but the fold itself
-    // never reads it — see `FoldableConsistencyProof`'s doc comment in
-    // checkpoint-provider.ts. Backfilled from `treeSize2` to satisfy the
-    // parameter type for calldata-sourced links, which have no per-proof
-    // signed size.
-    consistencyProofs: opts.links.map((l) => ({
-      ...l.proof,
-      signedTreeSize2: l.proof.treeSize2,
-    })),
+    // `freshenReceipt` takes chains; each link is one step, wrapped as a
+    // one-proof chain — see `singleProofChain` in checkpoint-provider.ts.
+    consistencyProofs: opts.links.map((l) =>
+      singleProofChain(l.proof, l.signedTreeSize2),
+    ),
     latestCheckpointBytes: opts.latestCheckpointBytes,
   });
 
@@ -177,7 +173,9 @@ export async function freshenFromSthChain(opts: {
     leafValue,
     links,
     latestCheckpointBytes: opts.checkpoints[opts.checkpoints.length - 1]!,
-    sourceRefs: [...(opts.sourceRefs ?? [])],
+    // One entry per LINK, as the calldata path reports: a checkpoint that
+    // relays several proofs yields several links that all name it.
+    sourceRefs: links.map((l) => l.sourceRef ?? ""),
     knownAccumulator: opts.knownAccumulator,
   });
 }

package/src/lib/verify-anchored.ts

@@ -59,7 +59,7 @@ export type AnchorCheck = OnChainLogState & {
  * - the leaf is at/after the anchored size — the entry simply is not
  *   anchored yet (`receipt_newer_than_anchored_state`).
  * Tampered receipts surface earlier (signature/inclusion) or as a
- * recomputed peak that matches no anchored state ever; the chain rungs
+ * recomputed peak that matches no anchored state ever; the chain roots
  * that PROVE the buried case land in later plan phases.
  */
 export function classifyUnanchoredPeak(

package/src/lib/verify-checkpoint-chain.ts

@@ -15,7 +15,7 @@ import type { AnchorCheck } from "./verify-anchored.js";
  * (ADR-0056: every checkpoint's embedded consistency proof spans its
  * massif's entry boundary to its seal). `@forestrie/receipt-verify`'s
  * `verifyCheckpointChain` folds that chain from size 0, authenticating the
- * accumulator at EVERY retained seal — this rung depends only on the
+ * accumulator at EVERY retained seal — this root depends only on the
  * public log store: no tiles, no RPC, no holder cache. It is the
  * complement of the `CheckpointPublished` event scan (public chain data
  * only); the two paths are independently sufficient and cross-checkable.
@@ -109,7 +109,7 @@ export type CheckpointChainAnchorCheck = AnchorCheck & {
 
 /**
  * Find the recomputed receipt peak in the authenticated chain. Newest-first
- * (mirrors the event-scan rung): the freshest cover gives the most useful
+ * (mirrors the event-scan route): the freshest cover gives the most useful
  * report, and a match at ANY link is proof — later links' signed
  * consistency proofs commit it forward. Newer-than-chain fails CLOSED with
  * a refresh remedy: retention limits coverage, never validity.

package/src/lib/verify-eventscan.ts

@@ -11,8 +11,8 @@
  * record of those accumulators (`CheckpointPublished` carries `size` and
  * `accumulator`; the contract stores nothing retrievable historically).
  *
- * This rung depends only on public blockchain data — deliberately
- * independent of the log store (the retained-checkpoint chain rung is its
+ * This route depends only on public blockchain data — deliberately
+ * independent of the log store (the retained-checkpoint chain root is its
  * complement with the opposite dependency; see plan-2607-29).
  */
 import { bytesEqual } from "./bytes.js";

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;
+  }
+}

package/src/main/onboard-genesis.ts

@@ -10,6 +10,8 @@ import {
 } from "../lib/onboard-genesis-body.js";
 import type { OnboardGenesisOptions } from "../options/onboard-genesis.js";
 
+import { responseProblemDetail } from "../lib/http-problem.js";
+
 /**
  * FOR-406 (plan-2607-27 W2): operator genesis onboarding — turn a
  * `forestrie deploy` into a usable forest. POSTs the five-label v2
@@ -138,7 +140,7 @@ export async function runOnboardGenesis(
       command: "onboard-genesis",
       message: `genesis POST rejected: HTTP ${res.status}`,
       httpStatus: res.status,
-      detail: (await res.text()).slice(0, 512),
+      detail: await responseProblemDetail(res),
     });
     return;
   }

package/src/main/onboard-request.ts

@@ -16,6 +16,8 @@ import { loadEs256SigningKey } from "../lib/sign-statement-key.js";
 import { signX402Payment } from "../lib/x402-payment.js";
 import type { OnboardRequestOptions } from "../options/onboard-request.js";
 
+import { responseProblemDetail } from "../lib/http-problem.js";
+
 /**
  * Self-service onboarding (plan-2607-43 slice 06): create → (pay) → redeem.
  *
@@ -183,7 +185,7 @@ export async function runOnboardRequest(
       reportError(out, options, {
         error: "create_failed",
         command: "onboard-request",
-        message: `request rejected: HTTP ${res.status}: ${(await res.text()).slice(0, 300)}`,
+        message: `request rejected: HTTP ${res.status}: ${await responseProblemDetail(res, 300)}`,
         httpStatus: res.status,
       });
       return;
@@ -271,7 +273,7 @@ export async function runOnboardRequest(
     reportError(out, options, {
       error: "redeem_failed",
       command: "onboard-request",
-      message: `redeem rejected: HTTP ${res.status}: ${(await res.text()).slice(0, 300)}`,
+      message: `redeem rejected: HTTP ${res.status}: ${await responseProblemDetail(res, 300)}`,
       httpStatus: res.status,
     });
     return;