@forestrie/forestrie-cli 0.8.0

package/src/lib/create-receipt-chain-verify.ts

@@ -0,0 +1,267 @@
+import { bytesEqual } from "./bytes.js";
+import {
+  computeAccumulatorPeak,
+  openMassifNodeStore,
+  peakMMRIndexes,
+  type MassifNodeStore,
+} from "@forestrie/receipt-verify";
+import {
+  fetchOnChainLogState,
+  type OnChainLogState,
+} from "./verify-anchored.js";
+
+/**
+ * Chain-anchored, report-only verification for `forestrie create-receipt`
+ * (FOR-345 phase 2, plan-2607-15 §3/§6). This is the option-B path: it emits
+ * NO signed receipt. Its selling point is receipt-free verification — the
+ * checkpoint signature was already enforced on-chain at `publishCheckpoint`
+ * time, so no `.sth` is needed at all.
+ *
+ * The computation:
+ *   1. read the on-chain `logState(bytes32) -> {accumulator, size}`;
+ *   2. build the leaf's inclusion path AT the on-chain size
+ *      (`mmrLastIndex = size - 1`) from the local massif blob and compute the
+ *      accumulator peak it commits to (`computeAccumulatorPeak`);
+ *   3. compare that peak against `accumulator[peakIndex]`, where `peakIndex`
+ *      is the same proof-length -> accumulator-slot selection the contract's
+ *      own verifier uses (returned by `computeAccumulatorPeak`).
+ *
+ * Because the path is built at the CURRENT size, the target peak is by
+ * construction a member of the current accumulator — burial cannot occur at
+ * creation time. There is NO exact-accumulator-size constraint: any leaf with
+ * `mmrIndex < size` works, given local node data up to that size (plan §3,
+ * decision 4).
+ *
+ * Pure over bytes plus exactly one `eth_call`; no signing key, no operator.
+ */
+
+/** Outcome token — the `--json` shape and exit-code mapping are a contract. */
+export type ChainVerifyOutcome =
+  | "verified"
+  | "not_yet_anchored"
+  | "wrong_massif"
+  | "coverage"
+  | "accumulator_short"
+  | "peak_mismatch";
+
+/**
+ * Where a chain-mode *operational* error (as opposed to a verification
+ * outcome) broke the run: massif parse, or the on-chain read/decode.
+ */
+export type ChainVerifyErrorStage = "parse" | "chain";
+
+/** Stable snake_case reasons for operational failures (`--json` contract). */
+export type ChainVerifyReason = "massif_parse_failed";
+
+export class ChainVerifyFailure extends Error {
+  readonly stage: ChainVerifyErrorStage;
+  readonly reason: ChainVerifyReason;
+
+  constructor(
+    stage: ChainVerifyErrorStage,
+    reason: ChainVerifyReason,
+    message: string,
+  ) {
+    super(message);
+    this.name = "ChainVerifyFailure";
+    this.stage = stage;
+    this.reason = reason;
+  }
+}
+
+/** Facts for narration / `--json` reporting (bigints stay bigint here). */
+export type ChainVerifyResult = {
+  outcome: ChainVerifyOutcome;
+  leaf: { mmrIndex: bigint };
+  massif: {
+    massifIndex: bigint;
+    massifHeight: number;
+    firstIndex: bigint;
+    lastIndex: bigint;
+  };
+  onchain: {
+    /** Anchored MMR size read from the contract. */
+    size: bigint;
+    /** Number of accumulator peaks the contract holds. */
+    peakCount: number;
+  };
+  /**
+   * Peak-check facts. Absent on `not_yet_anchored` / `coverage` (the peak was
+   * never computed) — present on `verified` and `peak_mismatch`.
+   */
+  peakCheck?: {
+    /** Inclusion path length (leaf -> accumulator peak) at the on-chain size. */
+    proofLength: number;
+    /** Accumulator slot selected for a proof of this length. */
+    peakIndex: number;
+    /** MMR index of the selected accumulator peak. */
+    peakMMRIndex: bigint;
+    /** The peak recomputed from local node data (hex). */
+    computedPeakHex: string;
+    /** The peak the contract holds at `peakIndex` (hex). */
+    onchainPeakHex: string;
+    /** True iff the two peaks match byte-for-byte. */
+    matched: boolean;
+  };
+};
+
+function errorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+function toHex(bytes: Uint8Array): string {
+  let hex = "";
+  for (const b of bytes) hex += b.toString(16).padStart(2, "0");
+  return hex;
+}
+
+
+/** Dependencies, injectable so tests can mock the on-chain read. */
+export type ChainVerifyDeps = {
+  fetchOnChainLogState: (opts: {
+    univocity: string;
+    logId: string;
+    rpcUrl: string;
+  }) => Promise<OnChainLogState>;
+};
+
+const defaultDeps: ChainVerifyDeps = { fetchOnChainLogState };
+
+/**
+ * Run the report-only chain-anchored peak check.
+ *
+ * Failure taxonomy (plan §3, plan-2607-18 W3, all reported — never thrown):
+ * - `not_yet_anchored` — `mmrIndex >= size`: the leaf postdates the last
+ *   anchor ("anchor lag"); the local massif may hold it, but the chain does
+ *   not attest it yet.
+ * - `wrong_massif` — the loaded massif blob is for a *different* massif than
+ *   the leaf: the leaf's `mmrIndex` falls outside this blob's own
+ *   `firstIndex..lastIndex` window, so its inclusion path cannot be built
+ *   from these bytes. The remedy is a different blob (the one holding the
+ *   leaf), NOT a *later* blob — which is why this is distinct from
+ *   `coverage`. Mirrors the offline builder's `leaf_not_in_massif` guard.
+ * - `coverage` — the leaf IS in this massif, but the blob does not hold nodes
+ *   up to the on-chain size (the on-chain tip lives in a later massif); a
+ *   later blob is required.
+ * - `peak_mismatch` — the computed peak differs from the anchored one: the
+ *   local node data has been tampered with (or is for the wrong log).
+ *
+ * Operational errors (bad massif bytes, RPC transport/decode) throw
+ * `ChainVerifyFailure` / propagate — the caller maps them to exit 1.
+ */
+export async function verifyChainAnchored(
+  input: {
+    massifBytes: Uint8Array;
+    mmrIndex: bigint;
+    univocity: string;
+    logId: string;
+    rpcUrl: string;
+  },
+  deps: ChainVerifyDeps = defaultDeps,
+): Promise<ChainVerifyResult> {
+  let store: MassifNodeStore;
+  try {
+    store = openMassifNodeStore(input.massifBytes);
+  } catch (err) {
+    throw new ChainVerifyFailure(
+      "parse",
+      "massif_parse_failed",
+      `massif blob is not v2 layout: ${errorMessage(err)}`,
+    );
+  }
+
+  // The on-chain read is the one networked call (throws -> operational error).
+  const state = await deps.fetchOnChainLogState({
+    univocity: input.univocity,
+    logId: input.logId,
+    rpcUrl: input.rpcUrl,
+  });
+
+  const massif = {
+    massifIndex: store.massifIndex,
+    massifHeight: store.massifHeight,
+    firstIndex: store.firstIndex,
+    lastIndex: store.lastIndex,
+  };
+  const onchain = { size: state.size, peakCount: state.accumulator.length };
+  const base = { leaf: { mmrIndex: input.mmrIndex }, massif, onchain };
+
+  // Anchor lag: the entry is newer than the last on-chain checkpoint.
+  if (input.mmrIndex >= state.size) {
+    return { outcome: "not_yet_anchored", ...base };
+  }
+
+  // Wrong massif: the loaded blob must actually hold the leaf. The leaf's own
+  // inclusion path is built from THIS blob's node data, so the leaf must fall
+  // inside `firstIndex..lastIndex`. A leaf below `firstIndex` belongs to an
+  // earlier massif; above `lastIndex`, a later one. Either way the remedy is a
+  // *different* blob (the one containing the leaf) — not a later one — so this
+  // is distinct from `coverage`. Mirrors `buildReceiptOffline`'s
+  // `leaf_not_in_massif` guard (create-receipt-derive.ts), which the chain
+  // path previously omitted (plan-2607-18 W3, V2/V3). Without it a
+  // wrong-massif blob was misreported as `coverage` ("fetch the covering
+  // massif"), a misleading remedy.
+  if (input.mmrIndex < store.firstIndex || input.mmrIndex > store.lastIndex) {
+    return { outcome: "wrong_massif", ...base };
+  }
+
+  // Coverage: the path is built at `size - 1`, so the local blob must hold
+  // the log tip up to `size - 1`. Nodes below `firstIndex` resolve through
+  // the ancestor peak stack, so only the upper bound can be short here.
+  const mmrLastIndex = state.size - 1n;
+  if (mmrLastIndex > store.lastIndex) {
+    return { outcome: "coverage", ...base };
+  }
+
+  // Build the path AT the on-chain size and compute the accumulator peak it
+  // commits to (no exact-size constraint — this works for any covered leaf).
+  let computed: Awaited<ReturnType<typeof computeAccumulatorPeak>>;
+  try {
+    computed = await computeAccumulatorPeak({
+      massifBytes: input.massifBytes,
+      mmrIndex: input.mmrIndex,
+      mmrSize: state.size,
+    });
+  } catch (err) {
+    // A throw here means the blob could not furnish a proof node up to the
+    // on-chain size despite the range check — treat as coverage, not a crash.
+    return { outcome: "coverage", ...base };
+  }
+
+  const peaks = peakMMRIndexes(mmrLastIndex);
+  const peakMMRIndex = peaks[computed.peakIndex] ?? -1n;
+  const onchainPeak = state.accumulator[computed.peakIndex];
+  if (onchainPeak === undefined) {
+    // The contract holds FEWER peaks than the selected slot: a shape/length
+    // disagreement, not a byte-level peak mismatch. Distinct reason
+    // (`accumulator_short`, plan-2607-18 W3 V4) so a truncated on-chain
+    // accumulator reads differently from tampered node data — the computed
+    // peak is fine; the chain simply has no slot to compare it against.
+    return {
+      outcome: "accumulator_short",
+      ...base,
+      peakCheck: {
+        proofLength: computed.proof.length,
+        peakIndex: computed.peakIndex,
+        peakMMRIndex,
+        computedPeakHex: toHex(computed.peak),
+        onchainPeakHex: "",
+        matched: false,
+      },
+    };
+  }
+
+  const matched = bytesEqual(computed.peak, onchainPeak);
+  return {
+    outcome: matched ? "verified" : "peak_mismatch",
+    ...base,
+    peakCheck: {
+      proofLength: computed.proof.length,
+      peakIndex: computed.peakIndex,
+      peakMMRIndex,
+      computedPeakHex: toHex(computed.peak),
+      onchainPeakHex: toHex(onchainPeak),
+      matched,
+    },
+  };
+}

package/src/lib/create-receipt-derive.ts

@@ -0,0 +1,208 @@
+import {
+  buildReceiptOffline,
+  computeAccumulatorPeak,
+  openMassifNodeStore,
+  parseCheckpoint,
+  parseReceipt,
+  peakMMRIndexes,
+  type MassifNodeStore,
+  type ParsedCheckpoint,
+} from "@forestrie/receipt-verify";
+
+/**
+ * Checkpoint-mode receipt derivation for `forestrie create-receipt`
+ * (FOR-345 phase 1, plan-2607-15 §6): stage the
+ * `@forestrie/receipt-verify` primitives so every failure is a typed
+ * `CreateReceiptFailure` with a stable stage + reason, and collect the
+ * narration facts (massif index, proof length, selected peak, cert copy)
+ * alongside the receipt bytes. Pure over bytes — no network, no key.
+ */
+
+/** Where derivation broke: artefact parsing vs. proof/receipt assembly. */
+export type CreateReceiptStage = "parse" | "derive";
+
+/** Stable snake_case reasons — the `--json` error shape is a contract. */
+export type CreateReceiptReason =
+  | "massif_parse_failed"
+  | "checkpoint_parse_failed"
+  | "checkpoint_missing_peak_receipts"
+  | "checkpoint_missing_sealed_size"
+  | "checkpoint_does_not_cover_leaf"
+  | "leaf_not_in_massif"
+  | "derive_failed";
+
+export class CreateReceiptFailure extends Error {
+  readonly stage: CreateReceiptStage;
+  readonly reason: CreateReceiptReason;
+
+  constructor(
+    stage: CreateReceiptStage,
+    reason: CreateReceiptReason,
+    message: string,
+  ) {
+    super(message);
+    this.name = "CreateReceiptFailure";
+    this.stage = stage;
+    this.reason = reason;
+  }
+}
+
+/** Facts for narration / `--json` reporting (bigints stay bigint here). */
+export type DerivedReceiptDetails = {
+  massifIndex: bigint;
+  massifHeight: number;
+  firstIndex: bigint;
+  lastIndex: bigint;
+  /** Sealed tree size the checkpoint signature commits to. */
+  sealedSize: bigint;
+  /** Inclusion path length (leaf → accumulator peak). */
+  proofLength: number;
+  /** Accumulator slot of the selected pre-signed peak receipt. */
+  peakIndex: number;
+  /** Total accumulator peaks at the sealed size. */
+  peakCount: number;
+  /** MMR index of the selected peak. */
+  peakMMRIndex: bigint;
+  /** Delegation cert (label 1000) copied from checkpoint to receipt. */
+  certCopied: boolean;
+};
+
+export type DerivedReceipt = {
+  receiptCbor: Uint8Array;
+  details: DerivedReceiptDetails;
+};
+
+function fail(
+  stage: CreateReceiptStage,
+  reason: CreateReceiptReason,
+  message: string,
+): never {
+  throw new CreateReceiptFailure(stage, reason, message);
+}
+
+function errorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/**
+ * Derive a receipt for `mmrIndex` from local massif + checkpoint bytes.
+ * The assembly itself is `buildReceiptOffline`; this wrapper pre-parses
+ * both artefacts so the precondition failures the taxonomy names —
+ * leaf-not-in-massif, checkpoint-doesn't-cover-leaf — are classified
+ * before derivation, and the checkpoint parse feeds the narration.
+ */
+export async function deriveCheckpointReceipt(input: {
+  massifBytes: Uint8Array;
+  checkpointBytes: Uint8Array;
+  mmrIndex: bigint;
+}): Promise<DerivedReceipt> {
+  const { massifBytes, checkpointBytes, mmrIndex } = input;
+
+  let checkpoint: ParsedCheckpoint;
+  try {
+    checkpoint = parseCheckpoint(checkpointBytes);
+  } catch (err) {
+    fail(
+      "parse",
+      "checkpoint_parse_failed",
+      `checkpoint is not a format-v3 COSE Sign1: ${errorMessage(err)}`,
+    );
+  }
+  if (!checkpoint.peakReceipts) {
+    fail(
+      "parse",
+      "checkpoint_missing_peak_receipts",
+      "checkpoint carries no pre-signed peak receipts (label -65931)",
+    );
+  }
+  const sealedSize = checkpoint.mmrSize;
+  if (sealedSize === null || sealedSize <= 0n) {
+    fail(
+      "parse",
+      "checkpoint_missing_sealed_size",
+      "checkpoint carries no consistency proof (cannot determine sealed size)",
+    );
+  }
+
+  let store: MassifNodeStore;
+  try {
+    store = openMassifNodeStore(massifBytes);
+  } catch (err) {
+    fail(
+      "parse",
+      "massif_parse_failed",
+      `massif blob is not v2 layout: ${errorMessage(err)}`,
+    );
+  }
+
+  if (mmrIndex >= sealedSize) {
+    fail(
+      "derive",
+      "checkpoint_does_not_cover_leaf",
+      `checkpoint does not cover the leaf: mmrIndex ${mmrIndex} >= sealed ` +
+        `size ${sealedSize} — the entry postdates this checkpoint`,
+    );
+  }
+  if (mmrIndex < store.firstIndex || mmrIndex > store.lastIndex) {
+    fail(
+      "derive",
+      "leaf_not_in_massif",
+      `leaf mmrIndex ${mmrIndex} is not in this massif blob (massif ` +
+        `${store.massifIndex} holds mmr indexes ${store.firstIndex}..` +
+        `${store.lastIndex})`,
+    );
+  }
+
+  let receiptCbor: Uint8Array;
+  try {
+    receiptCbor = buildReceiptOffline({ massifBytes, checkpointBytes, mmrIndex });
+  } catch (err) {
+    fail("derive", "derive_failed", errorMessage(err));
+  }
+
+  // Narration facts. The proof length comes from the assembled receipt.
+  //
+  // The reported peak MUST identify the exact same accumulator peak whose
+  // pre-signed receipt buildReceiptOffline attached — this narration is the
+  // demo's proof of *which* peak was signed, so it cannot drift from the
+  // builder. We therefore reuse the builder's own selection rather than
+  // recomputing it independently: computeAccumulatorPeak returns the same
+  // `peakIndex` (peakIndexForLeafProof(mmrSize, proofLen)) buildReceiptOffline
+  // indexes the -65931 array with, plus the peak hash it commits to. The
+  // -65931 array and peakMMRIndexes share the sealer's descending-height /
+  // ascending-mmr-index order (go-merklelog PeakHashes), so peakIndex maps
+  // straight into peakMMRIndexes — no inversion.
+  const proofLength = parseReceipt(receiptCbor).proof.path.length;
+  const peaks = peakMMRIndexes(sealedSize - 1n);
+  let peakIndex: number;
+  try {
+    ({ peakIndex } = await computeAccumulatorPeak({
+      massifBytes,
+      mmrIndex,
+      mmrSize: sealedSize,
+    }));
+  } catch (err) {
+    fail("derive", "derive_failed", errorMessage(err));
+  }
+  const peakMMRIndex = peaks[peakIndex];
+  if (peakMMRIndex === undefined) {
+    // Unreachable given mmrIndex < sealedSize; keep the failure typed.
+    fail("derive", "derive_failed", "no accumulator peak covers the leaf");
+  }
+
+  return {
+    receiptCbor,
+    details: {
+      massifIndex: store.massifIndex,
+      massifHeight: store.massifHeight,
+      firstIndex: store.firstIndex,
+      lastIndex: store.lastIndex,
+      sealedSize,
+      proofLength,
+      peakIndex,
+      peakCount: peaks.length,
+      peakMMRIndex,
+      certCopied: checkpoint.delegationCert !== null,
+    },
+  };
+}

package/src/lib/create-receipt-inputs.ts

@@ -0,0 +1,79 @@
+import { readFileSync } from "node:fs";
+import { decodeEntryIdHex } from "@forestrie/receipt-verify";
+import type { CreateReceiptOptions } from "../options/create-receipt.js";
+
+/**
+ * Load and resolve `forestrie create-receipt` inputs (FOR-345). Pure
+ * file/decode work — strictly no network.
+ *
+ * Leaf addressing: `--mmr-index` is used verbatim; `--entry-id` is the
+ * permanent SCRAPI entry id whose second 8 bytes ARE the big-endian
+ * mmrIndex (`decodeEntryIdHex`), so entry-id addressing is fully
+ * derivable offline — no massif index-region (urkle) lookup is involved.
+ * (Content-hash addressing is the phase-2 feature that waits on the
+ * urkle index reader, FOR-373; entry-id does not.)
+ */
+export type CreateReceiptLeaf = {
+  mmrIndex: bigint;
+  source: "mmr-index" | "entry-id";
+  /** Present with `--entry-id`: the id as given. */
+  entryId?: string;
+  /** Present with `--entry-id`: the decoded idtimestamp (decimal). */
+  idtimestamp?: bigint;
+};
+
+export type CreateReceiptArtifacts = {
+  massifBytes: Uint8Array;
+  /** Present in checkpoint mode (`--checkpoint`). */
+  checkpointBytes: Uint8Array | undefined;
+  leaf: CreateReceiptLeaf;
+};
+
+function readBytes(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}`);
+  }
+}
+
+/** Resolve the leaf mmrIndex from whichever addressing flag was given. */
+export function resolveLeaf(options: CreateReceiptOptions): CreateReceiptLeaf {
+  if (options.mmrIndex !== undefined) {
+    return { mmrIndex: options.mmrIndex, source: "mmr-index" };
+  }
+  // Options parsing guarantees exactly one of the two flags.
+  const entryId = options.entryId!;
+  let decoded: ReturnType<typeof decodeEntryIdHex>;
+  try {
+    decoded = decodeEntryIdHex(entryId);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`invalid --entry-id '${entryId}': ${message}`);
+  }
+  return {
+    mmrIndex: decoded.mmrIndex,
+    source: "entry-id",
+    entryId,
+    idtimestamp: decoded.idtimestamp,
+  };
+}
+
+/** Read massif/checkpoint artefacts from disk and resolve the leaf. */
+export function loadCreateReceiptArtifacts(
+  options: CreateReceiptOptions,
+): CreateReceiptArtifacts {
+  const leaf = resolveLeaf(options);
+  if (options.massif === undefined) {
+    // Unreachable: only tile anchors (checkpoint/chain) reach here, and options
+    // parsing requires --massif for those. Guard keeps the type honest.
+    throw new Error("--massif is required to build a receipt from tiles");
+  }
+  const massifBytes = readBytes(options.massif, "--massif");
+  const checkpointBytes =
+    options.checkpoint !== undefined
+      ? readBytes(options.checkpoint, "--checkpoint")
+      : undefined;
+  return { massifBytes, checkpointBytes, leaf };
+}