@forestrie/forestrie-cli 0.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robin Bryce
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,425 @@
+# forestrie-cli
+
+`forestrie` — the **participant CLI** for forestrie transparency logs
+(SCITT / COSE receipts). Ships two ways — an npm package that runs on Node
+(`npx @forestrie/forestrie-cli`) and a dependency-free static binary on
+every GitHub release — both hosting the subcommands a participant needs to
+deploy, sign, register, and verify against a forestrie log:
+
+| Subcommand | What it does |
+|---|---|
+| `deploy` | Deploy a univocity instance (ES256 bootstrap is the paved path) |
+| `sign-statement` | Produce a SCITT signed statement (plain COSE Sign1 with CWT claims) |
+| `register` | Register a signed statement via SCRAPI, download the receipt |
+| `register-grant` | Authorize a signer for a child/data log (one grant per signer) |
+| `complete-grant` | Self-create the `Forestrie-Grant` header from a checkpoint |
+| `resolve-receipt` | Produce or freshen a COSE receipt — from tiles, or tile-free from a `.sth`/calldata chain (alias: `create-receipt`) |
+| `decode-receipt` | Decode a COSE receipt — it is just COSE: Sign1 + MMR inclusion |
+| `verify` | Verify a receipt offline — the same closer for every other subcommand |
+| `fetch-accumulator` | Cache the on-chain accumulator as a `--known-accumulator` snapshot |
+
+**Status:** subcommands not yet implemented declare their real argument
+surface and parse it, then exit non-zero with a structured `not_implemented`
+error. `--json` emits that report as JSON on stdout. Implementations land
+per-subcommand.
+
+## Install from npm
+
+```bash
+npx @forestrie/forestrie-cli --help          # no install
+npm install -g @forestrie/forestrie-cli      # then: forestrie --help
+forestrie verify --help
+```
+
+**Runtime:** the npm package is a **Node** program — Node **>= 20.10** and
+nothing else. Bun is the development and static-binary toolchain, not a
+runtime requirement: nothing under `src/` uses a Bun-only API, and
+`dist/cli.js` is built with `--target node`. If you would rather have no
+runtime at all, take the static binary below.
+
+## Install from a release
+
+Every [GitHub release](https://github.com/forestrie/forestrie-cli/releases)
+attaches prebuilt static binaries — `forestrie-darwin-arm64` and
+`forestrie-linux-x64` — each with a `.sha256` sidecar. No runtime is
+needed; just download, verify, and run:
+
+```bash
+target=darwin-arm64   # or: linux-x64
+base=https://github.com/forestrie/forestrie-cli/releases/latest/download
+curl -fsSLO "${base}/forestrie-${target}"
+curl -fsSLO "${base}/forestrie-${target}.sha256"
+shasum -a 256 -c "forestrie-${target}.sha256"
+chmod +x "forestrie-${target}"
+./forestrie-${target} --help
+```
+
+Releases are cut by pushing a `v*` tag; the workflow fails closed unless
+the tag matches the `package.json` version
+([release.yml](https://github.com/forestrie/forestrie-cli/blob/main/.github/workflows/release.yml)).
+The same tag publishes the npm package
+([publish.yml](https://github.com/forestrie/forestrie-cli/blob/main/.github/workflows/publish.yml)),
+with npm trusted publishing and provenance attestation.
+
+## Install from source
+
+Requires [Bun](https://bun.sh) (pinned in `mise.toml`; `mise install`
+works). All dependencies install **tokenless** from public npmjs — no
+registry auth, no `.npmrc`:
+
+```bash
+bun install
+bun run typecheck && bun test
+bun run dev -- --help          # run from source
+```
+
+## Build the static binary
+
+```bash
+bun run build:binary            # host platform → dist/forestrie
+bun run build:binary:linux-x64  # → dist/forestrie-linux-x64
+bun run build:binary:darwin-arm64
+./dist/forestrie --help
+```
+
+## Conventions
+
+- Human output by default; `--json` for machine-readable output on stdout.
+- `-v` / `--verbosity` per `@forestrie/cli-kit` reporting (`-1` silences
+  stderr feedback; stdout stays pipeable).
+- Env fallbacks: `FORESTRIE_BASE_URL`, `RPC_URL`, `GRANT_B64`,
+  `OWNER_ADDRESS`, `DEPLOYER_KEY`, `FORESTRIE_CONFIG`; any string flag also
+  accepts `${env:VAR}` / `${env}` whole-value templates.
+- **ES256 is the paved path end-to-end**; KS256 appears only in the
+  Safe / ERC-1271 aside.
+
+## Usage
+
+Minimal example per subcommand. `$FORESTRIE_BASE_URL`, `$RPC_URL`, and
+`$GRANT_B64` are the env fallbacks from [Conventions](#conventions).
+
+### `deploy`
+
+```bash
+forestrie deploy \
+  --bootstrap-alg es256 \
+  --bootstrap-es256-generate --bootstrap-es256-pem-out bootstrap.es256.pem \
+  --owner-address 0xYourDeployer \
+  --rpc-url "$RPC_URL" \
+  --out deployment.json
+```
+
+```
+ImutableUnivocity deployed at: 0xAbC…123
+genesisLogId: 0f9a1c7e-…-…
+chainId: 84532  txHash: 0x9f…21
+wrote deployment record to deployment.json
+```
+
+### `sign-statement`
+
+```bash
+forestrie sign-statement \
+  --key alice.es256.pem \
+  --payload statement.json --content-type application/json \
+  --out statement.cose
+```
+
+```
+signed statement: plain COSE Sign1 (ES256)
+  kid:       241115ab754013fcbf2e88544a369009d5d7de7f54497ad640ef28ad6237392c
+  iss:       241115ab754013fcbf2e88544a369009d5d7de7f54497ad640ef28ad6237392c
+  sub:       sha-256:9c3f8a5d0e6b17c4a2f1d8e05b6c93a7714f2e8d90ab35c6e1d47f80b92c5a13
+  payload:   45 bytes (application/json)
+  statement: 253 bytes -> statement.cose
+```
+
+Statements carry SCITT CWT claims (protected COSE header label 15,
+covered by the signature). Defaults keep signing zero-config and
+deterministic; every claim is settable:
+
+- `--iss <string-or-uri>` — issuer (CWT claim 1). Default: the
+  lowercase hex kid. The keyword `ckt` derives the RFC 9679 COSE Key
+  Thumbprint URI (`urn:ietf:params:oauth:ckt:sha-256:…`) from the
+  signing key — which also means a literal issuer named `ckt` is not
+  expressible.
+- `--sub <string-or-uri>` — subject the statement speaks about (CWT
+  claim 2). Default: `sha-256:<hex>` of the payload bytes.
+- `--iat now|<unix-seconds>` — issued-at (CWT claim 6). Omitted by
+  default so repeated signing of the same payload is byte-identical.
+
+Empty `--iss`/`--sub` values are rejected rather than silently
+replaced with the defaults.
+
+### `register`
+
+```bash
+forestrie register \
+  --base-url "$FORESTRIE_BASE_URL" \
+  --log-id "$LOG_ID" \
+  --statement statement.cose \
+  --grant-b64 "$GRANT_B64" \
+  --out receipt.cbor
+```
+
+```
+entryId: 0202020202020202…0001
+statusUrl: https://.../register/.../entries/…
+receiptUrl: …/receipt
+wrote receipt (612 bytes) to receipt.cbor
+```
+
+### `register-grant`
+
+```bash
+forestrie register-grant \
+  --base-url "$FORESTRIE_BASE_URL" \
+  --owner-log "$OWNER_LOG_ID" --data-log "$DATA_LOG_ID" \
+  --sign-with bootstrap.es256.pem \
+  --out-b64 grant.b64
+```
+
+```
+ownerLog: 0f9a1c7e-…-… (grant leaf)
+dataLog: 8c2e4b…-… (authorized)
+signer: 04a91f…
+entryId: …
+wrote completed grant base64 to grant.b64
+```
+
+### `complete-grant`
+
+```bash
+forestrie complete-grant \
+  --grant grant.b64 \
+  --checkpoint checkpoint.sth --massif massif.log \
+  --out-b64 grant.completed.b64
+```
+
+```
+complete-grant: leaf       — mmrIndex 0 (recovered from massif)
+complete-grant: entry id   — 01010101010101010000000000000000 (idtimestamp from massif)
+complete-grant: proof      — 1 node(s) to peak 1/2
+complete-grant: checkpoint — sealed size 4, delegation cert copied: no
+complete-grant: receipt    — 118 bytes attached (header 396)
+```
+
+Self-creates the `Forestrie-Grant` header from a checkpoint, without an
+operator round-trip: it locates the grant's leaf in the local `--massif` blob
+by its commitment hash (recovering the `mmrIndex` and the sequenced
+idtimestamp), rebuilds the inclusion receipt against the checkpoint's pre-signed
+peak, and attaches the receipt + idtimestamp — the same completed bearer
+`register-grant` produces online. `--massif` is required (it carries the leaf);
+`--idtimestamp <hex|path>` is a fallback for the rare massif with no index
+region.
+
+### `resolve-receipt`
+
+One receipt producer (SCRAPI §2.4 "Resolve Receipt"; `create-receipt` is a
+kept alias). The **source is chosen by the flags present**, not a `--mode`;
+passing more than one source, or an under-specified one, errors with guidance.
+
+```bash
+# from tiles: rebuild the leaf→peak path from a massif and a checkpoint
+forestrie resolve-receipt \
+  --massif massif.log --checkpoint checkpoint.sth \
+  --mmr-index 0 \
+  --out receipt.cbor
+```
+
+```
+resolve-receipt: massif     — index 0 (height 3, mmr indexes 0..3)
+resolve-receipt: leaf       — mmrIndex 0 (from --mmr-index)
+resolve-receipt: checkpoint — sealed size 4, 2 peak(s)
+resolve-receipt: proof      — 1 node(s) to peak 1/2 (mmrIndex 2)
+resolve-receipt: receipt    — 144 bytes -> receipt.cbor
+```
+
+Add `--univocity <address> --log-id <id> --rpc-url $RPC_URL` for a
+chain-anchored (report-only) verification instead of a checkpoint-based
+receipt.
+
+#### Freshen a stale receipt (tile-free)
+
+When log growth buries the peak a receipt commits to, **freshen** re-anchors
+it to the current sealed state without tiles. `resolve-receipt --receipt
+<stale>` plus a tile-free source extends the receipt's old inclusion path to
+the latest peak and re-emits it. The leaf value is recomputed exactly as
+`verify` does, from the same leaf inputs: `--payload <statement>` for statement
+receipts, or `--committed-grant`/`--committed-grant-file` for grant receipts
+(both with `--entry-id`).
+
+```bash
+# a STATEMENT receipt from a retained .sth chain (emitted under the chain's tail)
+forestrie resolve-receipt \
+  --receipt stale.cbor --checkpoint-chain ./checkpoints/ \
+  --payload statement.cose --entry-id <hex> \
+  --in-place
+
+# a GRANT receipt, same chain source
+forestrie resolve-receipt \
+  --receipt stale.cbor --checkpoint-chain ./checkpoints/ \
+  --committed-grant-file grant.cbor --entry-id <hex> \
+  --in-place
+
+# from on-chain publishCheckpoint calldata; calldata carries no peak receipts,
+# so the latest .sth is supplied for emission, and --known-accumulator binds
+# the folded state to a trusted snapshot
+forestrie resolve-receipt \
+  --receipt stale.cbor \
+  --rpc-url $RPC_URL --univocity <address> --log-id <id> \
+  --checkpoint latest.sth --known-accumulator accumulator.cbor \
+  --committed-grant-file grant.cbor --entry-id <hex> \
+  --out fresh.cbor
+```
+
+`--in-place` rewrites the `--receipt` file (mutually exclusive with `--out`;
+crash-safe — written to a sibling temp then atomically renamed). The freshened
+receipt is a native receipt that verifies with plain `verify` against the
+current state, and freshen fails closed (it never emits a receipt whose
+recomputed peak does not match the folded latest accumulator).
+
+#### Bind the freshened state (`--known-accumulator`)
+
+Both freshen sources fold a consistency-proof chain to the current accumulator;
+they differ only in the **emission checkpoint**. `--checkpoint-chain` emits under
+the chain's own tail (self-contained — reach for it by default). The calldata
+source borrows a **separately-supplied** latest `--checkpoint`, so pass
+**`--known-accumulator <snapshot>`** (a `fetch-accumulator` capture) to bind the
+folded state to a trusted chain read: freshen asserts it **equals your snapshot
+at the same size** and fails closed otherwise (this also catches a lying/stale
+RPC). `--known-accumulator` works with either source.
+
+`--known-accumulator` anchors **freshness** — that the leaf roots into the
+genuine current log — which is a *different* question from who sealed the state
+or whether the log's authority chains back to genesis. Freshen never re-opens
+those; it re-anchors an already-issued receipt to the current accumulator. Which
+anchor proves what is the trust model: see
+**[the trust model](https://github.com/forestrie/protocol/blob/main/spec/receipt-trust-model.md#freshen-and-the-attestor)**.
+
+### `decode-receipt`
+
+```bash
+forestrie decode-receipt receipt.cbor
+```
+
+```
+COSE_Sign1 — tagged 18 (COSE_Sign1) — 304 bytes
+├─ protected: 1 (alg): -7 — ES256   4 (kid): 6c6c6c6c…
+├─ unprotected: inclusion proof — mmr index 5, path length 3
+├─ payload: detached — recomputed from the inclusion path at verify time
+└─ signature: 64 bytes
+```
+
+### `verify`
+
+```bash
+forestrie verify \
+  --genesis genesis.cbor --receipt receipt.cbor --committed-grant "$GRANT_B64"
+```
+
+```
+verify: parse     ok      — receipt COSE decodes; genesis trust root loads (ES256)
+verify: signature ok      — checkpoint signature verifies under the genesis trust key
+verify: inclusion ok      — proof path recomputes the checkpoint peak
+verify: binding   ok      — leaf binds the grant commitment at the receipt idtimestamp
+PASS: receipt verified offline against the cached checkpoint
+```
+
+Add `--univocity <address> --log-id <id> --rpc-url $RPC_URL` to check the
+receipt's peak against the on-chain accumulator instead of the checkpoint
+signature — no operator trust required.
+
+#### Trust anchors (FOR-297)
+
+`verify` takes four named trust anchors — pass whichever you hold:
+
+- **`--known-log-key`** — a caller-known log owner key (base64 `x||y`, env
+  `KNOWN_LOG_KEY`); fully offline, checks the signature under a key you trust
+  out of band (the SCITT / SSH-known-hosts posture).
+- **`--genesis`** — a cached `genesis.cbor` (the univocity-instance root
+  registration). Roots a receipt whose signer chains to that root owner; for a
+  child log deeper in the hierarchy, reaching genesis is the grant-chain walk
+  (still open) or the on-chain path below.
+- **`--known-accumulator`** — a cached chain read (`forestrie fetch-accumulator`):
+  verifies the peak against the on-chain accumulator, no operator trust and no
+  signature needed. Never source it unauthenticated from the operator's tile
+  store. Older receipts extend to a newer snapshot via `--massif`.
+- **`--rpc-url`** — a live chain read; same as `--known-accumulator`, current.
+
+What each actually proves — and how forestrie separates **split-view** (is this
+a single, un-forked history) from **sealing** (who signed this state) from
+**authority** (does the log chain to genesis, via grants — not `genesis.cbor`)
+from **attribution** (who was authorised to sign this leaf) — is the trust
+model: see
+**[the trust model](https://github.com/forestrie/protocol/blob/main/spec/receipt-trust-model.md)**.
+The receipt never expires, and the anchor never needs to be current — only
+trusted.
+
+Note that **freshness is not one of the four**. It is a weaker axis that bears
+only on *coverage* — whether a given accumulator snapshot reaches your leaf —
+and collapsing it into split-view is the specific confusion the trust model
+warns against. Split-view is the load-bearing property; currency is at most the
+`--rpc-url` "as of now" delta.
+
+### `fetch-accumulator`
+
+```bash
+forestrie fetch-accumulator \
+  --univocity "$UNIVOCITY" --log-id "$LOG_ID" --rpc-url "$RPC_URL" \
+  --out accumulator.cbor
+```
+
+Reads `logState(logId)` pinned to a block and writes the
+`--known-accumulator` snapshot: canonical CBOR binding
+`(chainId, univocity, logId, size, blockNumber, blockHash)` — anyone with
+RPC can re-run the read at that block and confirm or disprove it.
+
+## Use as a library: `decode-receipt`
+
+The receipt decoder behind `forestrie decode-receipt` is exported as a
+subpath so other tools can render receipts without shelling out to the CLI
+or vendoring a copy:
+
+```ts
+import {
+  decodeReceipt,
+  renderReceipt,
+  HEADER_LABELS,
+} from "@forestrie/forestrie-cli/decode-receipt";
+
+const decoded = decodeReceipt(receiptBytes);  // Uint8Array in
+console.log(renderReceipt(decoded));          // the annotated tree
+console.log(JSON.stringify(decoded, null, 2)); // the same model as --json
+```
+
+The entry point is pure: no `node:*`, no `Bun.*`, no I/O and no network, so
+it runs unchanged in Node, Bun, Deno, a worker or a browser. Its only
+dependencies are `@forestrie/receipt-verify` (the load-bearing receipt
+parse) and `@forestrie/encoding`. Ships with `.d.ts`.
+
+Also exported: `DecodeReceiptError` (carries the failing `stage`), the
+display-model types (`DecodedReceipt`, `DecodedHeaderEntry`, `DecodedClaim`,
+`Json`), the label tables (`HEADER_LABELS`, `ALG_NAMES`, `VDS_NAMES`,
+`CWT_CLAIM_NAMES`, `COSE_KEY_PARAM_NAMES`, `PROOF_KIND_NAMES`,
+`headerLabelInfo`) and the minimal CBOR reader (`decodeCborValue`,
+`decodeCborMap`, `isCborTagged`). The bare `@forestrie/forestrie-cli`
+specifier re-exports the same surface; prefer the subpath.
+
+Decoding is **display only** — it does not check signatures or inclusion.
+That is `forestrie verify` (and `@forestrie/receipt-verify` in-process).
+
+## Built on (published packages)
+
+The binary is buildable from **published packages only** (plan-2607-12) —
+all public on npmjs under the `@forestrie` scope, MIT licensed per-package,
+installable without auth:
+
+`@forestrie/cli-kit` · `@forestrie/deploy-core` · `@forestrie/encoding` ·
+`@forestrie/grant-builder` · `@forestrie/scrapi-client` ·
+`@forestrie/receipt-verify` · `@forestrie/merklelog` ·
+`@forestrie/delegation-cose` · `viem` (deploy tx signing/submission)
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/TRUST-MODEL.md

@@ -0,0 +1,8 @@
+# Forestrie receipt trust model — moved
+
+Moved to `forestrie/protocol`:
+**[`spec/receipt-trust-model.md`](https://github.com/forestrie/protocol/blob/main/spec/receipt-trust-model.md)**
+(anchors preserved, including
+[`#freshen-and-the-attestor`](https://github.com/forestrie/protocol/blob/main/spec/receipt-trust-model.md#freshen-and-the-attestor)).
+
+Per-command recipes remain in [README.md](./README.md).