@forestrie/forestrie-cli 0.9.1 → 0.11.0

package/src/main/verify.ts

@@ -1,9 +1,10 @@
 import { readFileSync } from "node:fs";
 import type { Out } from "@forestrie/cli-kit/reporting";
 import {
+  decodeKs256Attestation,
   decodeTrustRootFromGenesis,
   grantCommitmentHashFromGrant,
-  importEs256PublicKeyFromGrantDataXy64,
+  type Ks256Attestation,
   verifyCheckpointChain,
   verifyGrantReceiptOffline,
   verifyGrantReceiptOfflineWithKeys,
@@ -38,8 +39,12 @@ import {
 import {
   loadPayloadVerifyArtifacts,
   loadVerifyArtifacts,
+  readBytes,
 } from "../lib/verify-inputs.js";
+import { isKs256Root, parseKnownLogKey } from "../lib/known-log-key.js";
 import {
+  applyKs256Rows,
+  type Ks256ReportInfo,
   anchorOnlyStageRows,
   buildVerifyReport,
   knownKeyStageRows,
@@ -170,7 +175,9 @@ async function checkCheckpointChainAnchor(
 ): Promise<CheckpointChainAnchorCheck> {
   const rootKeys: CryptoKey[] = [];
   if (ctx.knownLogKey !== undefined) {
-    rootKeys.push(await importKnownLogKey(ctx.knownLogKey));
+    const known = await parseKnownLogKey(ctx.knownLogKey);
+    if (isKs256Root(known)) throw new Error(KS256_CHECKPOINT_CHAIN_REFUSAL);
+    rootKeys.push(known as CryptoKey);
   }
   if (genesisCbor !== undefined) {
     const root = await decodeTrustRootFromGenesis(genesisCbor);
@@ -261,20 +268,48 @@ function printAnchorRow(
   }
 }
 
+const KS256_CHECKPOINT_CHAIN_REFUSAL =
+  "--checkpoint-chain verifies checkpoint signatures, which need an ES256 trust root: a KS256 (20-byte address) known log key cannot root them";
+
 /**
- * Import the caller-known log OWNER key (`--known-log-key`, base64 x||y).
- * The value is the delegation-cert issuer's key, NOT the sealer key — the
- * label-1000 cert still resolves under it, so the anchor survives sealer
- * rotation and the cert-validation path is exercised (FOR-297 D1).
+ * Load `--ks256-attestation` (decode failure is an input error). Undefined
+ * when the flag is absent.
  */
-async function importKnownLogKey(knownLogKey: string): Promise<CryptoKey> {
-  const bytes = new Uint8Array(Buffer.from(knownLogKey, "base64"));
-  if (bytes.length !== 64) {
-    throw new Error(
-      `--known-log-key must be base64 x||y (64 bytes), decoded ${bytes.length}`,
-    );
+function loadAttestation(path: string | undefined): Ks256Attestation | undefined {
+  if (path === undefined) return undefined;
+  const bytes = readBytes(path, "--ks256-attestation");
+  try {
+    return decodeKs256Attestation(bytes);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`--ks256-attestation '${path}' is not a valid attestation: ${message}`);
+  }
+}
+
+/** Root algorithm and attestation facts for the report. */
+async function ks256Info(
+  options: VerifyReportContext & { ks256Attestation?: string | undefined },
+  genesisCbor: Uint8Array | undefined,
+  knownKey: Awaited<ReturnType<typeof parseKnownLogKey>> | undefined,
+  attestation: Ks256Attestation | undefined,
+  used: boolean,
+): Promise<Ks256ReportInfo | undefined> {
+  let ks256Root = false;
+  if (knownKey !== undefined) {
+    ks256Root = isKs256Root(knownKey);
+  } else if (genesisCbor !== undefined) {
+    try {
+      ks256Root = isKs256Root(await decodeTrustRootFromGenesis(genesisCbor));
+    } catch {
+      // The offline verify already reported an unreadable genesis.
+    }
   }
-  return importEs256PublicKeyFromGrantDataXy64(bytes);
+  if (!ks256Root && attestation === undefined) return undefined;
+  return {
+    ks256Root,
+    knownKey: knownKey !== undefined,
+    ...(attestation !== undefined ? { attestation, attestationUsed: used } : {}),
+  };
 }
 
 /**
@@ -485,6 +520,7 @@ async function finishVerify(
   artifacts: { genesisCbor: Uint8Array | undefined; receiptCbor: Uint8Array },
   result: ReceiptVerifyResult,
   anchorLeaf?: AnchorLeaf,
+  ks256?: Ks256ReportInfo,
 ): Promise<void> {
   // FOR-297 approach C: in a chain-anchored mode (live read OR cached
   // known-accumulator snapshot), a delegation the offline verifier cannot
@@ -516,7 +552,11 @@ async function finishVerify(
       // checkpoint-chain checks always work from the recomputed peak.
       let recomputedPeak: Uint8Array | undefined;
       if (
-        (ctx.knownLogKey !== undefined || ctx.anchor !== "chain") &&
+        // A KS256 root cannot locate a detached peak by signature trial
+        // (no_es256_trust_key), so it always works from the recomputed peak.
+        (ctx.knownLogKey !== undefined ||
+          ctx.anchor !== "chain" ||
+          ks256?.ks256Root === true) &&
         anchorLeaf !== undefined
       ) {
         const recomputed = await recomputeReceiptPeak({
@@ -595,8 +635,9 @@ async function finishVerify(
 
   const ok =
     result.ok && (ctx.anchor === "offline" || anchor?.anchored === true);
-  const rows =
+  const baseRows =
     ctx.knownLogKey !== undefined ? knownKeyStageRows(result) : stageRows(result);
+  const rows = ks256 !== undefined ? applyKs256Rows(baseRows, ks256) : baseRows;
 
   if (ctx.json) {
     const report = buildVerifyReport({
@@ -613,7 +654,10 @@ async function finishVerify(
       anchor,
       univocity: ctx.univocity,
       logId: ctx.logId,
-      ...(ctx.knownLogKey !== undefined ? { stagesOverride: rows } : {}),
+      ...(ctx.knownLogKey !== undefined || ks256 !== undefined
+        ? { stagesOverride: rows }
+        : {}),
+      ...(ks256 !== undefined ? { ks256 } : {}),
     });
     out.out(JSON.stringify(report, null, 2));
   } else {
@@ -674,46 +718,89 @@ export async function runVerify(
   options: VerifyOptions,
 ): Promise<void> {
   let artifacts: ReturnType<typeof loadPayloadVerifyArtifacts>;
+  let attestation: Ks256Attestation | undefined;
+  let knownKey: Awaited<ReturnType<typeof parseKnownLogKey>> | undefined;
   try {
     artifacts = loadPayloadVerifyArtifacts(options);
+    attestation = loadAttestation(options.ks256Attestation);
+    knownKey = await parseKnownKeyForRun(options);
   } catch (err) {
     reportRunError(out, options, "input", err);
     return;
   }
 
-  let result: ReceiptVerifyResult;
-  try {
-    if (options.knownLogKey !== undefined) {
-      // FOR-297 D1: caller-known log owner key replaces the genesis roots.
-      const knownKey = await importKnownLogKey(options.knownLogKey);
-      result = remapKnownKeyFailure(
-        await verifyReceiptOfflineWithKeys({
+  const run = (att: Ks256Attestation | undefined) =>
+    knownKey !== undefined
+      ? // FOR-297 D1: caller-known log owner key replaces the genesis roots.
+        // Genesis, if also given, only supplies the forest chain id.
+        verifyReceiptOfflineWithKeys({
           receiptCbor: artifacts.receiptCbor,
           payload: artifacts.payload,
           idtimestampBe8: artifacts.idtimestampBe8,
           trustKeys: [knownKey],
-        }),
-      );
-    } else {
-      // Parsing guarantees --genesis when --known-log-key is absent.
-      result = await verifyReceiptOffline({
-        ...artifacts,
-        genesisCbor: artifacts.genesisCbor!,
-      });
-    }
+          ...(att !== undefined ? { ks256Attestation: att } : {}),
+          ...(artifacts.genesisCbor !== undefined
+            ? { forestGenesisCbor: artifacts.genesisCbor }
+            : {}),
+        }).then(remapKnownKeyFailure)
+      : // Parsing guarantees --genesis when --known-log-key is absent.
+        verifyReceiptOffline({
+          receiptCbor: artifacts.receiptCbor,
+          payload: artifacts.payload,
+          idtimestampBe8: artifacts.idtimestampBe8,
+          genesisCbor: artifacts.genesisCbor!,
+          ...(att !== undefined ? { ks256Attestation: att } : {}),
+        });
+
+  let result: ReceiptVerifyResult;
+  let ks256: Ks256ReportInfo | undefined;
+  try {
+    result = await run(attestation);
+    ks256 = await ks256Info(
+      options,
+      artifacts.genesisCbor,
+      knownKey,
+      attestation,
+      // The attestation was needed only if the certificate does not verify
+      // by ecrecover alone.
+      attestation !== undefined && result.ok ? !(await run(undefined)).ok : false,
+    );
   } catch (err) {
     reportRunError(out, options, "verify", err);
     return;
   }
 
-  await finishVerify(out, options, artifacts, result, {
-    idtimestampBe8: artifacts.idtimestampBe8,
-    inner: async () =>
-      new Uint8Array(
-        // Copy pins the generic to ArrayBuffer for the dom BufferSource type.
-        await crypto.subtle.digest("SHA-256", new Uint8Array(artifacts.payload)),
-      ),
-  });
+  await finishVerify(
+    out,
+    options,
+    artifacts,
+    result,
+    {
+      idtimestampBe8: artifacts.idtimestampBe8,
+      inner: async () =>
+        new Uint8Array(
+          // Copy pins the generic to ArrayBuffer for the dom BufferSource type.
+          await crypto.subtle.digest("SHA-256", new Uint8Array(artifacts.payload)),
+        ),
+    },
+    ks256,
+  );
+}
+
+/**
+ * Parse `--known-log-key`, refusing a KS256 key where the chosen anchor mode
+ * needs ES256 checkpoint signatures.
+ */
+async function parseKnownKeyForRun(options: {
+  knownLogKey: string | undefined;
+  anchor: string;
+}): Promise<Awaited<ReturnType<typeof parseKnownLogKey>> | undefined> {
+  if (options.knownLogKey === undefined) return undefined;
+  const key = await parseKnownLogKey(options.knownLogKey);
+  if (isKs256Root(key) && options.anchor === "checkpoints") {
+    throw new Error(KS256_CHECKPOINT_CHAIN_REFUSAL);
+  }
+  return key;
 }
 
 /**
@@ -728,40 +815,62 @@ export async function runVerifyGrant(
   options: VerifyGrantOptions,
 ): Promise<void> {
   let artifacts: ReturnType<typeof loadVerifyArtifacts>;
+  let attestation: Ks256Attestation | undefined;
+  let knownKey: Awaited<ReturnType<typeof parseKnownLogKey>> | undefined;
   try {
     artifacts = loadVerifyArtifacts(options);
+    attestation = loadAttestation(options.ks256Attestation);
+    knownKey = await parseKnownKeyForRun(options);
   } catch (err) {
     reportRunError(out, options, "input", err);
     return;
   }
 
-  let result: ReceiptVerifyResult;
-  try {
-    if (options.knownLogKey !== undefined) {
-      // FOR-297 D1: caller-known log owner key replaces the genesis roots.
-      const knownKey = await importKnownLogKey(options.knownLogKey);
-      result = remapKnownKeyFailure(
-        await verifyGrantReceiptOfflineWithKeys({
+  const run = (att: Ks256Attestation | undefined) =>
+    knownKey !== undefined
+      ? verifyGrantReceiptOfflineWithKeys({
           receiptCbor: artifacts.receiptCbor,
           grant: artifacts.grant,
           idtimestampBe8: artifacts.idtimestampBe8,
           trustKeys: [knownKey],
-        }),
-      );
-    } else {
-      // Parsing guarantees --genesis when --known-log-key is absent.
-      result = await verifyGrantReceiptOffline({
-        ...artifacts,
-        genesisCbor: artifacts.genesisCbor!,
-      });
-    }
+          ...(att !== undefined ? { ks256Attestation: att } : {}),
+          ...(artifacts.genesisCbor !== undefined
+            ? { forestGenesisCbor: artifacts.genesisCbor }
+            : {}),
+        }).then(remapKnownKeyFailure)
+      : verifyGrantReceiptOffline({
+          receiptCbor: artifacts.receiptCbor,
+          grant: artifacts.grant,
+          idtimestampBe8: artifacts.idtimestampBe8,
+          genesisCbor: artifacts.genesisCbor!,
+          ...(att !== undefined ? { ks256Attestation: att } : {}),
+        });
+
+  let result: ReceiptVerifyResult;
+  let ks256: Ks256ReportInfo | undefined;
+  try {
+    result = await run(attestation);
+    ks256 = await ks256Info(
+      options,
+      artifacts.genesisCbor,
+      knownKey,
+      attestation,
+      attestation !== undefined && result.ok ? !(await run(undefined)).ok : false,
+    );
   } catch (err) {
     reportRunError(out, options, "verify", err);
     return;
   }
 
-  await finishVerify(out, options, artifacts, result, {
-    idtimestampBe8: artifacts.idtimestampBe8,
-    inner: () => grantCommitmentHashFromGrant(artifacts.grant),
-  });
+  await finishVerify(
+    out,
+    options,
+    artifacts,
+    result,
+    {
+      idtimestampBe8: artifacts.idtimestampBe8,
+      inner: () => grantCommitmentHashFromGrant(artifacts.grant),
+    },
+    ks256,
+  );
 }

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

@@ -0,0 +1,60 @@
+import type { LooseParsedArgs } from "@forestrie/cli-kit";
+import {
+  optionalStringOption,
+  parseForestrieCommonOptions,
+  requiredStringOption,
+  type ForestrieCommonOptions,
+} from "./common.js";
+
+/**
+ * `forestrie fetch-ks256-attestation` (plan-2610-03 D4): 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 for offline `verify`. The twin of `fetch-accumulator`.
+ */
+export type FetchKs256AttestationOptions = ForestrieCommonOptions & {
+  /** Receipt whose label-1000 KS256 delegation certificate is attested. */
+  receipt: string;
+  /** Contract root address override (`0x` + 40 hex). */
+  root: string | undefined;
+  /** Forest genesis: supplies the KS256 root (unless `--root`) and chain id. */
+  genesis: string | undefined;
+  /** JSON-RPC endpoint (`RPC_URL`) — the trusted chain reader. */
+  rpcUrl: string;
+  /** Block to pin the calls to; `latest` resolves to the current block. */
+  block: bigint | "latest";
+  /** Output path for the attestation CBOR. */
+  out: string;
+};
+
+export function parseFetchKs256AttestationOptions(
+  args: LooseParsedArgs,
+): FetchKs256AttestationOptions {
+  const root = optionalStringOption(args, "root");
+  const genesis = optionalStringOption(args, "genesis");
+  if (root === undefined && genesis === undefined) {
+    throw new Error(
+      "--root (contract address) and/or --genesis (KS256 bootstrap root) is required",
+    );
+  }
+  const blockRaw = optionalStringOption(args, "block") ?? "latest";
+  let block: bigint | "latest";
+  if (blockRaw === "latest") {
+    block = "latest";
+  } else if (/^[0-9]+$/.test(blockRaw)) {
+    block = BigInt(blockRaw);
+  } else {
+    throw new Error(
+      "--block must be a non-negative decimal block number or 'latest'",
+    );
+  }
+  return {
+    ...parseForestrieCommonOptions(args),
+    receipt: requiredStringOption(args, "receipt"),
+    root,
+    genesis,
+    rpcUrl: requiredStringOption(args, "rpc-url", "RPC_URL"),
+    block,
+    out: requiredStringOption(args, "out"),
+  };
+}

package/src/options/verify.ts

@@ -23,22 +23,28 @@ import {
  * Both add `--univocity --log-id --rpc-url` for the chain-anchored check (the
  * only networked path).
  *
- * Trust anchors (FOR-297 ladder; each rung needs strictly less trust):
- * 1. `--known-log-key` — caller-known log OWNER key: offline, no genesis;
- *    the key↔log binding is asserted by the key's provenance, not proven;
- *    no lifecycle visibility, no split-view protection.
- * 2. `--genesis` — genesis-derived roots (the grant-chain walk, approach A,
- *    will derive per-log bindings from genesis + public tiles).
- * 3. `--known-accumulator` — cached, auditable chain read: contract-enforced
- *    state (signature + grant chain + split-view for covered entries),
- *    fully offline; `--massif` (tiles) or `--consistency-proof` (portable
- *    top-up artifact) extends older receipts to a newer snapshot.
- * 4. `--checkpoint-chain` — retained `.sth` fold (FOR-368): authenticated
- *    accumulator at every retained seal from the public log store alone;
- *    signatures root in rung 1/2 trust.
- * 5. `--rpc-url` — live chain read: rung 3 plus freshness (the RPC provider
- *    is itself a trusted chain reader); buried peaks resolve via the
- *    CheckpointPublished history scan (public chain data only).
+ * Trust roots (protocol: spec/receipt-trust-model.md). They are alternatives,
+ * not an ordering — each answers a different subset of the four trust
+ * questions, and the report says which root was used:
+ * - `--known-log-key` — the known log key root: an owner key the caller holds
+ *   out of band; offline, no genesis; the key↔log binding is asserted by the
+ *   key's provenance, not proven; no split-view protection.
+ * - `--genesis` — the genesis root: the forest genesis document's bootstrap
+ *   key, which roots the root log or a delegation directly under it. A deeper
+ *   child log's authority needs the off-chain grant-chain walk, which no
+ *   verifier implements (spec/implementation-status.md).
+ * - `--known-accumulator` — the known accumulator root, from a cached,
+ *   auditable chain read: the contract-anchored state, fully offline;
+ *   `--massif` (tiles) or `--consistency-proof` (portable top-up artifact)
+ *   extends older receipts to a newer snapshot.
+ * - `--checkpoint-chain` — the checkpoint chain root: a retained fold of
+ *   checkpoint objects, an authenticated accumulator at every retained seal
+ *   from the public log store alone; signatures root in the genesis or known
+ *   log key root.
+ * - `--rpc-url` — the known accumulator root from a live chain read, plus
+ *   freshness (the RPC provider is itself a trusted chain reader); buried
+ *   peaks resolve via the CheckpointPublished history scan (public chain
+ *   data only).
  */
 
 type AnchorFields = {
@@ -73,14 +79,21 @@ type AnchorFields = {
   /** Lower bound for the CheckpointPublished history scan (FOR-368). */
   fromBlock: bigint | undefined;
   /**
-   * Caller-known log OWNER key (the delegation-cert issuer), base64 `x||y`
-   * (64 bytes, `KNOWN_LOG_KEY`) — FOR-297 D1. An offline trust anchor that
-   * replaces the genesis-derived roots: the "known hosts" rung of the trust
-   * ladder. It asserts (does not prove) the key↔log binding, and gives no
+   * Caller-known log OWNER key (the delegation-cert issuer), `KNOWN_LOG_KEY`
+   * — FOR-297 D1: base64 `x||y` (64-byte ES256 key), or a 20-byte KS256
+   * address (`0x` + 40 hex, or base64). With `--genesis` alongside, genesis
+   * supplies only the forest chain id an attestation must match. An offline trust anchor that
+   * replaces the genesis root: the known log key root of the trust model.
+   * It asserts (does not prove) the key↔log binding, and gives no
    * grant-lifecycle visibility or split-view protection — the grant-chain
    * walk (approach A) derives the binding; chain anchors add split-view.
    */
   knownLogKey: string | undefined;
+  /**
+   * ERC-1271 attestation file (`forestrie fetch-ks256-attestation`) for a
+   * KS256 contract root. Read and decoded by the runner; never fetches.
+   */
+  ks256Attestation: string | undefined;
 };
 
 function parseAnchorFields(args: LooseParsedArgs): AnchorFields {
@@ -151,6 +164,7 @@ function parseAnchorFields(args: LooseParsedArgs): AnchorFields {
     logId,
     rpcUrl,
     knownLogKey,
+    ks256Attestation: optionalStringOption(args, "ks256-attestation"),
     knownAccumulator,
     massif,
     checkpointChain,