@forestrie/forestrie-cli 0.8.0

package/src/commands/admin-onboard-token.ts

@@ -0,0 +1,51 @@
+import { defineCommandRunner, defineForestrieCommand } from "../commoncli.js";
+import { runAdminOnboardToken } from "../main/admin-onboard-token.js";
+import { parseAdminOnboardTokenOptions } from "../options/admin-onboard-token.js";
+
+export default defineForestrieCommand({
+  meta: {
+    name: "onboard-token",
+    description:
+      "Mint a forest onboard token under the operator credential; prints only the token so it composes into onboard-genesis --onboard-token [FOR-406]",
+  },
+  args: {
+    "base-url": {
+      type: "string",
+      description: "SCRAPI origin, no trailing slash (env FORESTRIE_BASE_URL)",
+      valueHint: "url",
+    },
+    "ops-token": {
+      type: "string",
+      description:
+        "Operator credential (env CANOPY_OPS_ADMIN_TOKEN); never logged",
+      valueHint: "token",
+    },
+    label: {
+      type: "string",
+      description: "Token label recorded by the mint (default forestrie-cli)",
+      valueHint: "text",
+    },
+    deployment: {
+      type: "string",
+      description:
+        "forestrie deploy --out artifact supplying the mandatory chain binding (ADR-0059 D7)",
+      valueHint: "path",
+    },
+    "chain-id": {
+      type: "string",
+      description: "Chain id for the binding (with --univocity; or use --deployment)",
+      valueHint: "id",
+    },
+    univocity: {
+      type: "string",
+      description: "Univocity contract address for the binding",
+      valueHint: "0xaddr",
+    },
+    out: {
+      type: "string",
+      description: "Write the minted token to this path instead of stdout",
+      valueHint: "path",
+    },
+  },
+  run: defineCommandRunner(parseAdminOnboardTokenOptions, runAdminOnboardToken),
+});

package/src/commands/admin.ts

@@ -0,0 +1,20 @@
+import { defineForestrieCommand } from "../commoncli.js";
+
+/**
+ * `forestrie admin` — the operator-credential command family (ADR-0052).
+ *
+ * Participant commands never read operator secrets; anything requiring
+ * `CANOPY_OPS_ADMIN_TOKEN` (or future operator credentials) lives under
+ * this family so the split is enforced by the command tree itself.
+ */
+export default defineForestrieCommand({
+  meta: {
+    name: "admin",
+    description:
+      "Operator commands (require operator credentials, e.g. CANOPY_OPS_ADMIN_TOKEN)",
+  },
+  subCommands: {
+    "onboard-token": () =>
+      import("./admin-onboard-token.js").then((m) => m.default),
+  },
+});

package/src/commands/complete-grant.ts

@@ -0,0 +1,41 @@
+import { defineCommandRunner, defineForestrieCommand } from "../commoncli.js";
+import { runCompleteGrant } from "../main/complete-grant.js";
+import { parseCompleteGrantOptions } from "../options/complete-grant.js";
+
+export default defineForestrieCommand({
+  meta: {
+    name: "complete-grant",
+    description:
+      "Self-create the Forestrie-Grant header content from a checkpoint — grants are derivable from log data [FOR-344]",
+  },
+  args: {
+    grant: {
+      type: "string",
+      description: "Registered (uncompleted) grant, base64 file",
+      valueHint: "path",
+      required: true,
+    },
+    checkpoint: {
+      type: "string",
+      description: "Checkpoint (.sth) for the owner log",
+      valueHint: "path",
+      required: true,
+    },
+    massif: {
+      type: "string",
+      description: "Massif .log blob for local leaf/path recovery",
+      valueHint: "path",
+    },
+    idtimestamp: {
+      type: "string",
+      description: "Leaf idtimestamp when the grant lacks one",
+      valueHint: "hex|path",
+    },
+    "out-b64": {
+      type: "string",
+      description: "Completed grant base64 output path (default: stdout)",
+      valueHint: "path",
+    },
+  },
+  run: defineCommandRunner(parseCompleteGrantOptions, runCompleteGrant),
+});

package/src/commands/create-consistency-proof.ts

@@ -0,0 +1,44 @@
+import { defineCommandRunner, defineForestrieCommand } from "../commoncli.js";
+import { runCreateConsistencyProof } from "../main/create-consistency-proof.js";
+import { parseCreateConsistencyProofOptions } from "../options/create-consistency-proof.js";
+
+export default defineForestrieCommand({
+  meta: {
+    name: "create-consistency-proof",
+    description:
+      "Build a portable top-up artifact from public massif tiles: the --from-size accumulator plus per-peak inclusion paths proven at --to-size (strict deterministic CBOR, unsigned). Any party with tiles can produce it; a holder then verifies an old receipt tile-free via `verify --known-accumulator ... --consistency-proof` — the artifact can only fail against the trusted snapshot, never mint trust [FOR-368]",
+  },
+  args: {
+    massif: {
+      type: "string",
+      description:
+        "Massif blob path(s), comma-separated — must cover the nodes from --from-size through --to-size (a spanning proof needs each massif in the range)",
+      valueHint: "path[,path...]",
+      required: true,
+    },
+    "from-size": {
+      type: "string",
+      description:
+        "MMR size the proof extends FROM (the old receipt's era, e.g. an old checkpoint's tree-size-2)",
+      valueHint: "size",
+      required: true,
+    },
+    "to-size": {
+      type: "string",
+      description:
+        "MMR size the proof lands ON — must equal the holder's trusted snapshot size (fetch-accumulator anchoredSize)",
+      valueHint: "size",
+      required: true,
+    },
+    out: {
+      type: "string",
+      description: "Output path for the consistency-proof CBOR",
+      valueHint: "path",
+      required: true,
+    },
+  },
+  run: defineCommandRunner(
+    parseCreateConsistencyProofOptions,
+    runCreateConsistencyProof,
+  ),
+});

package/src/commands/create-log.ts

@@ -0,0 +1,95 @@
+import { defineCommandRunner, defineForestrieCommand } from "../commoncli.js";
+import { runCreateLog } from "../main/create-log.js";
+import { parseCreateLogOptions } from "../options/create-log.js";
+
+export default defineForestrieCommand({
+  meta: {
+    name: "create-log",
+    description:
+      "Create a log and set its owner (K(L)) — data, child auth, or self-referential root bootstrap [FOR-390]",
+  },
+  args: {
+    "base-url": {
+      type: "string",
+      description: "SCRAPI origin, no trailing slash (env FORESTRIE_BASE_URL)",
+      valueHint: "url",
+    },
+    "owner-log": {
+      type: "string",
+      description:
+        "Parent/auth log the create grant is sequenced into",
+      valueHint: "uuid",
+      required: true,
+    },
+    "new-log": {
+      type: "string",
+      description: "The log being created",
+      valueHint: "uuid",
+      required: true,
+    },
+    "auth-log": {
+      type: "boolean",
+      description: "Create a child auth log rather than a data log",
+      default: false,
+    },
+    "child-payment-required": {
+      type: "boolean",
+      description:
+        "Mark the creation grant GF_DERIVED|GF_CHILD_PAYMENT_REQUIRED: child grants registered under the new log's authority require an x402 payment (auth logs only) [adr-0062]",
+      default: false,
+    },
+    "self-referential": {
+      type: "boolean",
+      description:
+        "Root bootstrap grant (--new-log == --owner-log; binds --sign-with itself, forbids --signer-pem)",
+      default: false,
+    },
+    "signer-pem": {
+      type: "string",
+      description:
+        "PEM of the new log's owner (grantData = ES256 x||y); required unless --self-referential",
+      valueHint: "path",
+    },
+    "sign-with": {
+      type: "string",
+      description:
+        "Granting authority PEM (the parent log's K(L)) that signs the grant",
+      valueHint: "path",
+      required: true,
+    },
+    prepare: {
+      type: "boolean",
+      description:
+        "Pre-register the child's public root with the coordinator (parent-authorized, no operator token) WITHOUT sequencing, so you can `delegate` before the log exists; emits the create grant to --out-b64 [FOR-390]",
+      default: false,
+    },
+    "parent-grant-b64": {
+      type: "string",
+      description: "Parent grant credential authorizing this registration",
+      valueHint: "base64",
+    },
+    "out-b64": {
+      type: "string",
+      description: "Completed grant base64 output path (default: stdout)",
+      valueHint: "path",
+    },
+    "bootstrap-log": {
+      type: "string",
+      description:
+        "Forest bootstrap/root log id — first /register/ path segment (default: --owner-log)",
+      valueHint: "uuid",
+    },
+    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(parseCreateLogOptions, runCreateLog),
+});

package/src/commands/decode-receipt.ts

@@ -0,0 +1,20 @@
+import { defineCommandRunner, defineForestrieCommand } from "../commoncli.js";
+import { runDecodeReceipt } from "../main/decode-receipt.js";
+import { parseDecodeReceiptOptions } from "../options/decode-receipt.js";
+
+export default defineForestrieCommand({
+  meta: {
+    name: "decode-receipt",
+    description:
+      "Decode a COSE receipt — see that it is just COSE: Sign1 + MMR inclusion [FOR-346]",
+  },
+  args: {
+    receipt: {
+      type: "positional",
+      description: "COSE receipt file (omit or use `-` to read stdin)",
+      valueHint: "path",
+      required: false,
+    },
+  },
+  run: defineCommandRunner(parseDecodeReceiptOptions, runDecodeReceipt),
+});

package/src/commands/delegate.ts

@@ -0,0 +1,55 @@
+import { defineCommandRunner, defineForestrieCommand } from "../commoncli.js";
+import { runDelegate } from "../main/delegate.js";
+import { parseDelegateOptions } from "../options/delegate.js";
+
+export default defineForestrieCommand({
+  meta: {
+    name: "delegate",
+    description:
+      "Authorize a custodian-vouched sealer to publish checkpoints for a log you own (K(L)); public coordinator endpoints only [FOR-390]",
+  },
+  args: {
+    "coordinator-url": {
+      type: "string",
+      description:
+        "Delegation coordinator origin, no trailing slash (env DELEGATION_COORDINATOR_URL)",
+      valueHint: "url",
+    },
+    "log-id": {
+      type: "string",
+      description: "Target log id",
+      valueHint: "uuid",
+      required: true,
+    },
+    "sign-with": {
+      type: "string",
+      description: "ES256 log-root PEM (K(L)) that authorizes the delegation",
+      valueHint: "path",
+      required: true,
+    },
+    "known-sealer-key": {
+      type: "string",
+      description:
+        "The known key that vouches for the operator's sealer (the registrar's voucher-signing key), base64 x||y (64 bytes) (env KNOWN_SEALER_KEY)",
+      valueHint: "base64",
+    },
+    "horizon-mmr-end": {
+      type: "string",
+      description:
+        "Exclusive MMR end of the horizon lease (default 9007199254740991; mmrStart is fixed 0)",
+      valueHint: "number",
+    },
+    "ttl-seconds": {
+      type: "string",
+      description:
+        "Lease TTL in seconds (default: standing entry suggestedTtlSeconds)",
+      valueHint: "seconds",
+    },
+    "out-b64": {
+      type: "string",
+      description: "Write the submitted certificate base64 to this path",
+      valueHint: "path",
+    },
+  },
+  run: defineCommandRunner(parseDelegateOptions, runDelegate),
+});

package/src/commands/deploy.ts

@@ -0,0 +1,72 @@
+import { defineCommandRunner, defineForestrieCommand } from "../commoncli.js";
+import { runDeploy } from "../main/deploy.js";
+import { parseDeployOptions } from "../options/deploy.js";
+
+export default defineForestrieCommand({
+  meta: {
+    name: "deploy",
+    description:
+      "Deploy a univocity instance (ES256 bootstrap is the paved path; KS256 only for the Safe/ERC-1271 aside) [FOR-340]",
+  },
+  args: {
+    "bootstrap-alg": {
+      type: "string",
+      description: "Bootstrap key algorithm: es256 (paved path) or ks256",
+      valueHint: "es256|ks256",
+      default: "es256",
+    },
+    "bootstrap-es256-generate": {
+      type: "boolean",
+      description:
+        "Generate a fresh ES256 P-256 bootstrap keypair (requires --bootstrap-es256-pem-out)",
+      default: false,
+    },
+    "bootstrap-es256-pem-out": {
+      type: "string",
+      description: "Write the generated ES256 PKCS#8 PEM to this path",
+      valueHint: "path",
+    },
+    "bootstrap-es256-pem": {
+      type: "string",
+      description:
+        "Use an existing ES256 bootstrap key PEM (PKCS#8/SEC1 private or SPKI public — only the public point is bound on-chain)",
+      valueHint: "path",
+    },
+    "owner-address": {
+      type: "string",
+      description:
+        "Deployer / owner address (env OWNER_ADDRESS); must match --deployer-key when both are given",
+      valueHint: "0x…",
+    },
+    "rpc-url": {
+      type: "string",
+      description: "JSON-RPC endpoint (env RPC_URL)",
+      valueHint: "url",
+    },
+    "deployer-key": {
+      type: "string",
+      description:
+        "Funded secp256k1 private key that pays gas for the deploy tx (env DEPLOYER_KEY). Gas-only — the ES256 bootstrap key is the trust root, not this key",
+      valueHint: "0x…",
+    },
+    "release-tag": {
+      type: "string",
+      description:
+        "Univocity contract release tag for the deploy manifest (default: latest)",
+      valueHint: "tag",
+    },
+    "release-manifest": {
+      type: "string",
+      description:
+        "Local deploy-manifest JSON (bytecode digests still verified) — skips the GitHub release fetch",
+      valueHint: "path",
+    },
+    out: {
+      type: "string",
+      description:
+        "Write the deployment record JSON here (default: stdout) — { imutableUnivocity, genesisLogId, bootstrapAlg, chainId, … }",
+      valueHint: "path",
+    },
+  },
+  run: defineCommandRunner(parseDeployOptions, runDeploy),
+});

package/src/commands/fetch-accumulator.ts

@@ -0,0 +1,49 @@
+import { defineCommandRunner, defineForestrieCommand } from "../commoncli.js";
+import { runFetchAccumulator } from "../main/fetch-accumulator.js";
+import { parseFetchAccumulatorOptions } from "../options/fetch-accumulator.js";
+
+export default defineForestrieCommand({
+  meta: {
+    name: "fetch-accumulator",
+    description:
+      "Read the log's on-chain logState and cache it as a --known-accumulator snapshot (CBOR binding chainId/univocity/logId/size/block) — verify runs chain-anchored fully offline against it. The snapshot is auditable: anyone with RPC can re-run the read at that block. Trust the party that fetched it as a chain reader; never take it unauthenticated from the log operator's tile store [FOR-297]",
+  },
+  args: {
+    univocity: {
+      type: "string",
+      description: "ImutableUnivocity contract address",
+      valueHint: "address",
+      required: true,
+    },
+    "log-id": {
+      type: "string",
+      description: "Log id (UUID or hex) for the on-chain accumulator read",
+      valueHint: "uuid",
+      required: true,
+    },
+    "rpc-url": {
+      type: "string",
+      description: "JSON-RPC endpoint (default: ${env} → RPC_URL)",
+      valueHint: "url",
+    },
+    "at-block": {
+      type: "string",
+      description:
+        "Snapshot the latest anchored state at/before this block from CheckpointPublished events — historical states without an archive node [FOR-368]",
+      valueHint: "block",
+    },
+    "from-block": {
+      type: "string",
+      description:
+        "Lower bound for the --at-block event scan (the forest's deploy block; default earliest)",
+      valueHint: "block",
+    },
+    out: {
+      type: "string",
+      description: "Output path for the snapshot CBOR",
+      valueHint: "path",
+      required: true,
+    },
+  },
+  run: defineCommandRunner(parseFetchAccumulatorOptions, runFetchAccumulator),
+});

package/src/commands/onboard-genesis.ts

@@ -0,0 +1,70 @@
+import { defineCommandRunner, defineForestrieCommand } from "../commoncli.js";
+import { runOnboardGenesis } from "../main/onboard-genesis.js";
+import { parseOnboardGenesisOptions } from "../options/onboard-genesis.js";
+
+export default defineForestrieCommand({
+  meta: {
+    name: "onboard-genesis",
+    description:
+      "Operator genesis onboarding: POST the direct-sign ES256 genesis for a deployed forest under a pre-minted onboard token, wire sealing callbacks, and cache the public genesis [FOR-406]",
+  },
+  args: {
+    "base-url": {
+      type: "string",
+      description: "SCRAPI origin, no trailing slash (env FORESTRIE_BASE_URL)",
+      valueHint: "url",
+    },
+    deployment: {
+      type: "string",
+      description:
+        "deploy --out artifact (supplies imutableUnivocity + genesisLogId)",
+      valueHint: "path",
+    },
+    univocity: {
+      type: "string",
+      description: "ImutableUnivocity address (with --log-id, instead of --deployment)",
+      valueHint: "address",
+    },
+    "log-id": {
+      type: "string",
+      description: "Forest (genesis) log id (with --univocity)",
+      valueHint: "uuid",
+    },
+    "bootstrap-pem": {
+      type: "string",
+      description:
+        "ES256 bootstrap key PEM from deploy (private or public; only the public key is sent)",
+      valueHint: "path",
+      required: true,
+    },
+    "chain-id": {
+      type: "string",
+      description: "Chain id recorded in the genesis (env CHAIN_ID; default 84532)",
+      valueHint: "id",
+    },
+    "coordinator-url": {
+      type: "string",
+      description:
+        "Delegation coordinator origin; the signing-route webhook is derived per log",
+      valueHint: "url",
+    },
+    "webhook-url": {
+      type: "string",
+      description: "Explicit sealing webhook (overrides --coordinator-url derivation)",
+      valueHint: "url",
+    },
+    "onboard-token": {
+      type: "string",
+      description:
+        "Pre-minted onboard token (env ONBOARD_TOKEN) — mint with 'forestrie admin onboard-token'; x402 settlement is the future public source",
+      valueHint: "token",
+    },
+    out: {
+      type: "string",
+      description:
+        "Fetch the public genesis back to this path (the offline trust root for verify --genesis)",
+      valueHint: "path",
+    },
+  },
+  run: defineCommandRunner(parseOnboardGenesisOptions, runOnboardGenesis),
+});

package/src/commands/onboard-request.ts

@@ -0,0 +1,59 @@
+import { defineCommandRunner, defineForestrieCommand } from "../commoncli.js";
+import { runOnboardRequest } from "../main/onboard-request.js";
+import { parseOnboardRequestOptions } from "../options/onboard-request.js";
+
+export default defineForestrieCommand({
+  meta: {
+    name: "onboard-request",
+    description:
+      "Create a bootstrap-key-attested onboard request and redeem it into an onboard token (paying the x402 challenge when asked); prints only the token so it composes into onboard-genesis --onboard-token [ADR-0059 D8]",
+  },
+  args: {
+    "base-url": {
+      type: "string",
+      description: "SCRAPI origin, no trailing slash (env FORESTRIE_BASE_URL)",
+      valueHint: "url",
+    },
+    deployment: {
+      type: "string",
+      description:
+        "forestrie deploy --out artifact (chain binding + bootstrap alg)",
+      valueHint: "path",
+      required: true,
+    },
+    "bootstrap-pem": {
+      type: "string",
+      description:
+        "Bootstrap private key PEM (ES256) — signs the registrant attestation",
+      valueHint: "path",
+    },
+    "bootstrap-key-hex": {
+      type: "string",
+      description:
+        "Bootstrap private key hex (KS256) — signs the registrant attestation",
+      valueHint: "hex",
+    },
+    "contact-email": {
+      type: "string",
+      description: "Contact email for the request (env ONBOARD_CONTACT_EMAIL)",
+      valueHint: "email",
+    },
+    label: {
+      type: "string",
+      description: "Request label (default forestrie-cli)",
+      valueHint: "text",
+    },
+    "payer-key": {
+      type: "string",
+      description:
+        "x402 payer private key (env X402_PAYER_KEY); pays the redeem 402 challenge — real funds move on settlement",
+      valueHint: "hex",
+    },
+    out: {
+      type: "string",
+      description: "Write the redeemed token to this path instead of stdout",
+      valueHint: "path",
+    },
+  },
+  run: defineCommandRunner(parseOnboardRequestOptions, runOnboardRequest),
+});

package/src/commands/register-grant.ts

@@ -0,0 +1,74 @@
+import { defineCommandRunner, defineForestrieCommand } from "../commoncli.js";
+import { runRegisterGrant } from "../main/register-grant.js";
+import { parseRegisterGrantOptions } from "../options/register-grant.js";
+
+export default defineForestrieCommand({
+  meta: {
+    name: "register-grant",
+    description:
+      "Authorize a statement writer on a data log (extend-only; grant recorded in the parent auth log) [FOR-343]",
+  },
+  args: {
+    "base-url": {
+      type: "string",
+      description:
+        "SCRAPI origin, no trailing slash (env FORESTRIE_BASE_URL)",
+      valueHint: "url",
+    },
+    "owner-log": {
+      type: "string",
+      description: "Owner (auth) log the grant leaf is sequenced into",
+      valueHint: "uuid",
+      required: true,
+    },
+    "data-log": {
+      type: "string",
+      description: "Child/data log the grant authorizes",
+      valueHint: "uuid",
+      required: true,
+    },
+    "sign-with": {
+      type: "string",
+      description:
+        "PKCS#8 PEM key that signs the grant statement (the granting authority)",
+      valueHint: "path",
+      required: true,
+    },
+    "signer-pem": {
+      type: "string",
+      description:
+        "PEM of the signer being authorized (grantData = ES256 x||y)",
+      valueHint: "path",
+      required: true,
+    },
+    "parent-grant-b64": {
+      type: "string",
+      description: "Parent grant credential authorizing this registration",
+      valueHint: "base64",
+      required: true,
+    },
+    "out-b64": {
+      type: "string",
+      description: "Completed grant base64 output path (default: stdout)",
+      valueHint: "path",
+    },
+    "bootstrap-log": {
+      type: "string",
+      description:
+        "Forest bootstrap/root log id — first /register/ path segment (default: --owner-log)",
+      valueHint: "uuid",
+    },
+    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(parseRegisterGrantOptions, runRegisterGrant),
+});