@forestrie/forestrie-cli 0.8.0

package/src/commands/register.ts

@@ -0,0 +1,54 @@
+import { defineCommandRunner, defineForestrieCommand } from "../commoncli.js";
+import { runRegister } from "../main/register.js";
+import { parseRegisterOptions } from "../options/register.js";
+
+export default defineForestrieCommand({
+  meta: {
+    name: "register",
+    description:
+      "Register a signed statement via SCRAPI and download the receipt (any SCRAPI client, plain COSE Sign1) [FOR-342]",
+  },
+  args: {
+    "base-url": {
+      type: "string",
+      description:
+        "SCRAPI origin, no trailing slash (env FORESTRIE_BASE_URL)",
+      valueHint: "url",
+    },
+    "log-id": {
+      type: "string",
+      description: "Target log id (UUID)",
+      valueHint: "uuid",
+      required: true,
+    },
+    statement: {
+      type: "string",
+      description:
+        "COSE Sign1 signed statement file ('-' or omitted: read stdin)",
+      valueHint: "path",
+    },
+    "grant-b64": {
+      type: "string",
+      description:
+        "Authorization: Forestrie-Grant bearer credential, base64 (env GRANT_B64)",
+      valueHint: "base64",
+    },
+    out: {
+      type: "string",
+      description: "Write the receipt bytes to this path",
+      valueHint: "path",
+    },
+    timeout: {
+      type: "string",
+      description: "Overall receipt wait budget in seconds (default 60)",
+      valueHint: "seconds",
+    },
+    "poll-interval": {
+      type: "string",
+      description:
+        "Pacing between registration/receipt polls in seconds (default 1; Retry-After wins when longer)",
+      valueHint: "seconds",
+    },
+  },
+  run: defineCommandRunner(parseRegisterOptions, runRegister),
+});

package/src/commands/resolve-receipt.ts

@@ -0,0 +1,101 @@
+import { defineCommandRunner, defineForestrieCommand } from "../commoncli.js";
+import { runCreateReceipt } from "../main/create-receipt.js";
+import { parseCreateReceiptOptions } from "../options/create-receipt.js";
+
+export default defineForestrieCommand({
+  meta: {
+    name: "resolve-receipt",
+    description:
+      "Produce or freshen a COSE receipt (SCRAPI §2.4) — source by flags: --massif (tiles), --receipt + --checkpoint-chain (.sth freshen), or --receipt + --rpc-url/--univocity/--log-id + --checkpoint (calldata freshen). Freshen re-anchors a stale receipt to the current accumulator; the trust posture is set at verify (https://github.com/forestrie/protocol/blob/main/spec/receipt-trust-model.md) [FOR-345/FOR-418]. Alias: create-receipt.",
+  },
+  args: {
+    // --- tiles source (--massif) ---
+    massif: {
+      type: "string",
+      description: "Massif .log blob holding the leaf and its proof nodes (tiles source)",
+      valueHint: "path",
+    },
+    "mmr-index": {
+      type: "string",
+      description:
+        "MMR index of the leaf to prove (tiles source; exactly one of --mmr-index / --entry-id)",
+      valueHint: "n",
+    },
+    checkpoint: {
+      type: "string",
+      description:
+        "Checkpoint (.sth) with pre-signed peak receipts (tiles source, offline mode)",
+      valueHint: "path",
+    },
+    univocity: {
+      type: "string",
+      description:
+        "ImutableUnivocity contract address (tiles source, chain-anchored; needs --log-id and --rpc-url)",
+      valueHint: "0x…",
+    },
+    "log-id": {
+      type: "string",
+      description: "Log id for the on-chain accumulator read (chain-anchored mode)",
+      valueHint: "uuid",
+    },
+    "rpc-url": {
+      type: "string",
+      description: "JSON-RPC endpoint (env RPC_URL; chain-anchored mode)",
+      valueHint: "url",
+    },
+    // --- freshen source (--receipt + a tile-free chain) ---
+    receipt: {
+      type: "string",
+      description: "Stale receipt to freshen tile-free (freshen source)",
+      valueHint: "path",
+    },
+    "checkpoint-chain": {
+      type: "string",
+      description:
+        "Retained .sth checkpoint chain — a directory or comma-separated files (freshen source; the freshened receipt is emitted under the chain's own tail checkpoint)",
+      valueHint: "dir|files",
+    },
+    "committed-grant": {
+      type: "string",
+      description:
+        "Committed grant, base64 — recomputes the leaf value (freshen source)",
+      valueHint: "b64",
+    },
+    "committed-grant-file": {
+      type: "string",
+      description:
+        "Committed grant CBOR file — recomputes the leaf value (freshen; needs --entry-id)",
+      valueHint: "path",
+    },
+    payload: {
+      type: "string",
+      description:
+        "Registered statement payload — the leaf ContentHash (freshen statement receipts; alternative to --committed-grant, needs --entry-id)",
+      valueHint: "path",
+    },
+    // --- shared ---
+    "entry-id": {
+      type: "string",
+      description:
+        "Permanent SCRAPI entry id (leaf addressing for tiles; idtimestamp for freshen), 32 hex chars",
+      valueHint: "hex",
+    },
+    out: {
+      type: "string",
+      description: "Receipt output path (default: stdout)",
+      valueHint: "path",
+    },
+    "in-place": {
+      type: "boolean",
+      description:
+        "Rewrite the --receipt file with the freshened receipt (freshen only; mutually exclusive with --out)",
+    },
+    "known-accumulator": {
+      type: "string",
+      description:
+        "Trusted accumulator snapshot (fetch-accumulator output) — binds the freshened state to a trusted chain read, failing closed on mismatch (freshen only; anchors freshness, not signer provenance — https://github.com/forestrie/protocol/blob/main/spec/receipt-trust-model.md)",
+      valueHint: "path",
+    },
+  },
+  run: defineCommandRunner(parseCreateReceiptOptions, runCreateReceipt),
+});

package/src/commands/sign-statement.ts

@@ -0,0 +1,53 @@
+import { defineCommandRunner, defineForestrieCommand } from "../commoncli.js";
+import { runSignStatement } from "../main/sign-statement.js";
+import { parseSignStatementOptions } from "../options/sign-statement.js";
+
+export default defineForestrieCommand({
+  meta: {
+    name: "sign-statement",
+    description:
+      "Produce a SCITT signed statement: plain COSE Sign1 (ES256) with alg, content type, kid and CWT claims (iss/sub, label 15) all in the protected header [FOR-341, FOR-371]",
+  },
+  args: {
+    key: {
+      type: "string",
+      description: "ES256 P-256 private signing key (PEM or JWK file)",
+      valueHint: "path",
+      required: true,
+    },
+    payload: {
+      type: "string",
+      description: "Payload file to sign ('-' reads stdin)",
+      valueHint: "path",
+      required: true,
+    },
+    "content-type": {
+      type: "string",
+      description: "Payload content type (protected COSE header, label 3)",
+      default: "application/json",
+    },
+    iss: {
+      type: "string",
+      description:
+        "Issuer (CWT claim 1, protected label 15): a StringOrURI, or 'ckt' for the RFC 9679 key-thumbprint URI (default: hex kid)",
+    },
+    sub: {
+      type: "string",
+      description:
+        "Subject (CWT claim 2, protected label 15): what the statement speaks about (default: sha-256:<hex> of the payload)",
+      valueHint: "string-or-uri",
+    },
+    iat: {
+      type: "string",
+      description:
+        "Issued-at (CWT claim 6): unix seconds or 'now' (default: omitted, keeping output deterministic)",
+      valueHint: "now|seconds",
+    },
+    out: {
+      type: "string",
+      description: "Signed statement output path (default: stdout)",
+      valueHint: "path",
+    },
+  },
+  run: defineCommandRunner(parseSignStatementOptions, runSignStatement),
+});

package/src/commands/verify-grant.ts

@@ -0,0 +1,89 @@
+import { defineCommandRunner, defineForestrieCommand } from "../commoncli.js";
+import { runVerifyGrant } from "../main/verify.js";
+import { parseVerifyGrantOptions } from "../options/verify.js";
+
+export default defineForestrieCommand({
+  meta: {
+    name: "verify-grant",
+    description:
+      "Verify a forestrie authority/grant receipt offline. A thin wrapper over `verify`: it derives the grant commitment preimage from a structured grant and verifies it as the leaf payload. The receipt is a standard COSE Receipt; only the payload is forestrie-specific (matches the on-chain univocity accumulator) [FOR-347]",
+  },
+  args: {
+    genesis: {
+      type: "string",
+      description:
+        "Cached public genesis (genesis.cbor) — genesis-derived offline trust root (or supply --known-log-key instead)",
+      valueHint: "path",
+    },
+    "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 derives it from the grant chain, while the accumulator anchors (--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",
+    },
+    receipt: {
+      type: "string",
+      description: "COSE receipt file to verify",
+      valueHint: "path",
+      required: true,
+    },
+    "committed-grant": {
+      type: "string",
+      description:
+        "Grant committed at the receipt's leaf, base64 (env GRANT_B64); or use --committed-grant-file + --entry-id",
+      valueHint: "base64",
+    },
+    "committed-grant-file": {
+      type: "string",
+      description: "Grant CBOR file (alternative to --committed-grant)",
+      valueHint: "path",
+    },
+    "entry-id": {
+      type: "string",
+      description: "Entry id within the grant CBOR (with --committed-grant-file)",
+      valueHint: "id",
+    },
+    univocity: {
+      type: "string",
+      description:
+        "ImutableUnivocity contract address — enables the chain-anchored check (with --log-id and --rpc-url)",
+      valueHint: "address",
+    },
+    "log-id": {
+      type: "string",
+      description: "Log id (UUID or hex) for the on-chain accumulator read",
+      valueHint: "uuid",
+    },
+    "rpc-url": {
+      type: "string",
+      description:
+        "JSON-RPC endpoint for the chain-anchored check (default: ${env} → RPC_URL)",
+      valueHint: "url",
+    },
+    "known-accumulator": {
+      type: "string",
+      description:
+        "Cached on-chain accumulator snapshot (CBOR from `forestrie fetch-accumulator`) — the chain-anchored check fully offline, no --rpc-url. Never source it unauthenticated from the log operator's tile store (that re-internalises operator trust). Older receipts extend to a newer snapshot via --massif; newer receipts fail closed",
+      valueHint: "path",
+    },
+    massif: {
+      type: "string",
+      description:
+        "Local massif blob — enables proof-path extension when the receipt predates the --known-accumulator snapshot",
+      valueHint: "path",
+    },
+    "consistency-proof": {
+      type: "string",
+      description:
+        "Portable top-up artifact (`forestrie create-consistency-proof`) — tile-free extension of an older receipt into the --known-accumulator snapshot. Untrusted input: it can only fail, never mint trust [FOR-368]",
+      valueHint: "path",
+    },
+    "checkpoint-chain": {
+      type: "string",
+      description:
+        "Retained .sth checkpoint chain — a directory of .sth objects or comma-separated files in chain order. Folds the chain from size 0, authenticating the accumulator at every retained seal from the public log store alone (no tiles, no RPC); the receipt peak may match ANY link [FOR-368]",
+      valueHint: "dir|paths",
+    },
+  },
+  run: defineCommandRunner(parseVerifyGrantOptions, runVerifyGrant),
+});

package/src/commands/verify.ts

@@ -0,0 +1,92 @@
+import { defineCommandRunner, defineForestrieCommand } from "../commoncli.js";
+import { runVerify } from "../main/verify.js";
+import { parseVerifyOptions } from "../options/verify.js";
+
+export default defineForestrieCommand({
+  meta: {
+    name: "verify",
+    description:
+      "Verify a receipt offline against the cached checkpoint (ES256; no network) — the standard, SCITT-compatible closer. Give the EXACT registered payload (--payload, e.g. the signed statement) + its --entry-id. Add --univocity/--log-id/--rpc-url to also check the on-chain accumulator [FOR-347]",
+  },
+  args: {
+    genesis: {
+      type: "string",
+      description:
+        "Cached public genesis (genesis.cbor) — genesis-derived offline trust root (or supply --known-log-key instead)",
+      valueHint: "path",
+    },
+    "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 derives it from the grant chain, while the accumulator anchors (--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",
+    },
+    receipt: {
+      type: "string",
+      description: "COSE receipt file to verify",
+      valueHint: "path",
+      required: true,
+    },
+    payload: {
+      type: "string",
+      description:
+        "The EXACT registered payload whose SHA-256 the leaf commits (e.g. the signed statement COSE). A standard COSE Receipt proves leaf = SHA-256(idtimestamp || SHA-256(payload))",
+      valueHint: "path",
+      required: true,
+    },
+    "entry-id": {
+      type: "string",
+      description: "SCRAPI entry id — supplies the leaf idtimestamp",
+      valueHint: "id",
+      required: true,
+    },
+    univocity: {
+      type: "string",
+      description:
+        "ImutableUnivocity contract address — enables the chain-anchored check (with --log-id and --rpc-url)",
+      valueHint: "address",
+    },
+    "log-id": {
+      type: "string",
+      description: "Log id (UUID or hex) for the on-chain accumulator read",
+      valueHint: "uuid",
+    },
+    "rpc-url": {
+      type: "string",
+      description:
+        "JSON-RPC endpoint for the chain-anchored check (default: ${env} → RPC_URL)",
+      valueHint: "url",
+    },
+    "from-block": {
+      type: "string",
+      description:
+        "Lower bound for the buried-peak CheckpointPublished history scan (the forest's deploy block; default earliest) [FOR-368]",
+      valueHint: "block",
+    },
+    "known-accumulator": {
+      type: "string",
+      description:
+        "Cached on-chain accumulator snapshot (CBOR from `forestrie fetch-accumulator`) — the chain-anchored check fully offline, no --rpc-url. Never source it unauthenticated from the log operator's tile store (that re-internalises operator trust). Older receipts extend to a newer snapshot via --massif; newer receipts fail closed",
+      valueHint: "path",
+    },
+    massif: {
+      type: "string",
+      description:
+        "Local massif blob — enables proof-path extension when the receipt predates the --known-accumulator snapshot",
+      valueHint: "path",
+    },
+    "consistency-proof": {
+      type: "string",
+      description:
+        "Portable top-up artifact (`forestrie create-consistency-proof`) — tile-free extension of an older receipt into the --known-accumulator snapshot. Untrusted input: it can only fail, never mint trust [FOR-368]",
+      valueHint: "path",
+    },
+    "checkpoint-chain": {
+      type: "string",
+      description:
+        "Retained .sth checkpoint chain — a directory of .sth objects or comma-separated files in chain order. Folds the chain from size 0, authenticating the accumulator at every retained seal from the public log store alone (no tiles, no RPC); the receipt peak may match ANY link [FOR-368]",
+      valueHint: "dir|paths",
+    },
+  },
+  run: defineCommandRunner(parseVerifyOptions, runVerify),
+});

package/src/commoncli.ts

@@ -0,0 +1,34 @@
+/**
+ * Tool-wide CLI flags and command wiring for the `forestrie` binary.
+ *
+ * citty does not pass parent flags into subcommand `run({ args })`, so
+ * `commonArgs` is merged into every command via `defineForestrieCommand`
+ * (see univocity-tools docs/agents/cli.md — the pattern source).
+ */
+import type { ArgsDef, CommandDef } from "citty";
+import { defineAppCommand, verbosityArgs } from "@forestrie/cli-kit";
+
+export { defineCommandRunner } from "@forestrie/cli-kit";
+
+/** Flags shared by every `forestrie` command. */
+export const commonArgs = {
+  ...verbosityArgs,
+  json: {
+    type: "boolean",
+    description: "Machine-readable JSON output on stdout",
+    default: false,
+  },
+  config: {
+    type: "string",
+    description:
+      "Config file path (default: ${env} → FORESTRIE_CONFIG). Stub — config loading lands with the subcommand implementations.",
+    valueHint: "path",
+  },
+} as const satisfies ArgsDef;
+
+/** Wrap `defineCommand` so every node in the tree gets `commonArgs`. */
+export function defineForestrieCommand<T extends ArgsDef>(
+  def: CommandDef<T>,
+): CommandDef<T> {
+  return defineAppCommand(commonArgs, def);
+}

package/src/decode-receipt.ts

@@ -0,0 +1,56 @@
+/**
+ * Public library entry: the pure COSE-receipt decoder and renderer that
+ * backs `forestrie decode-receipt`.
+ *
+ * Imported as `@forestrie/forestrie-cli/decode-receipt`. Everything here
+ * is runtime-neutral — no `node:*`, no `Bun.*`, no I/O, no network. It
+ * takes receipt bytes and returns a display model (plus a text
+ * rendering of it), so it runs unchanged in Node, Bun, Deno, a worker
+ * or a browser. The only dependencies are `@forestrie/receipt-verify`
+ * (the load-bearing receipt parse) and `@forestrie/encoding`.
+ *
+ * Decoding is display only: it does NOT verify signatures or inclusion.
+ * That is `forestrie verify` / `@forestrie/receipt-verify`.
+ */
+
+export {
+  DecodeReceiptError,
+  bytesToHex,
+  decodeReceipt,
+  toJson,
+  type DecodeReceiptStage,
+  type DecodedClaim,
+  type DecodedHeaderEntry,
+  type DecodedReceipt,
+  type Json,
+} from "./lib/decode-receipt-decode.js";
+
+export { renderReceipt } from "./lib/decode-receipt-render.js";
+
+export {
+  ALG_NAMES,
+  COSE_KEY_PARAM_NAMES,
+  COSE_SIGN1_TAG,
+  CWT_CLAIMS_LABEL,
+  CWT_CLAIM_NAMES,
+  DELEGATION_CERT_LABEL,
+  HEADER_LABELS,
+  PROOFS_CONSISTENCY_KEY,
+  PROOFS_INCLUSION_KEY,
+  PROOF_KIND_NAMES,
+  SEAL_PEAK_RECEIPTS_LABEL,
+  VDS_LABEL,
+  VDS_NAMES,
+  VERIFIABLE_PROOFS_LABEL,
+  headerLabelInfo,
+  type LabelInfo,
+} from "./lib/decode-receipt-labels.js";
+
+export {
+  CborDecodeError,
+  decodeCborMap,
+  decodeCborValue,
+  isCborTagged,
+  type CborTagged,
+  type CborValue,
+} from "./lib/decode-receipt-cbor.js";

package/src/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Package entry for `@forestrie/forestrie-cli`.
+ *
+ * This package is primarily a CLI (`forestrie`). Its one supported
+ * library surface is the pure receipt decoder/renderer, re-exported
+ * here and also reachable directly as
+ * `@forestrie/forestrie-cli/decode-receipt` — prefer the subpath, it is
+ * the stable name and will not grow unrelated exports.
+ */
+export * from "./decode-receipt.js";

package/src/lib/bytes.ts

@@ -0,0 +1,7 @@
+/** Constant-time byte-string equality (shared; FOR-418 R6 dedup). */
+export function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  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;
+}