@forestrie/forestrie-cli 0.8.0

package/src/options/deploy.ts

@@ -0,0 +1,105 @@
+import type { LooseParsedArgs } from "@forestrie/cli-kit";
+import {
+  optionalStringOption,
+  parseForestrieCommonOptions,
+  requiredStringOption,
+  type ForestrieCommonOptions,
+} from "./common.js";
+
+export type BootstrapAlg = "es256" | "ks256";
+
+/** Default univocity contract release tag (deploy-core resolves `latest`). */
+export const DEFAULT_DEPLOY_RELEASE_TAG = "latest";
+
+/** `forestrie deploy` — FOR-340. */
+export type DeployOptions = ForestrieCommonOptions & {
+  /** Bootstrap key algorithm. ES256 is the paved path; KS256 is the Safe/ERC-1271 aside. */
+  bootstrapAlg: BootstrapAlg;
+  /** Generate a fresh ES256 P-256 bootstrap keypair. */
+  bootstrapEs256Generate: boolean;
+  /** Where to write the generated ES256 PKCS#8 PEM. */
+  bootstrapEs256PemOut: string | undefined;
+  /** Existing ES256 bootstrap key PEM (PKCS#8/SEC1 private or SPKI public). */
+  bootstrapEs256Pem: string | undefined;
+  /** Deployer / owner address (`OWNER_ADDRESS`). */
+  ownerAddress: string | undefined;
+  /** JSON-RPC endpoint (`RPC_URL`). */
+  rpcUrl: string;
+  /**
+   * Funded secp256k1 key that signs and pays gas for the deploy
+   * transaction (`DEPLOYER_KEY`). Gas-only: it has no role in the log's
+   * trust model — the bootstrap key (ES256) is what the contract binds.
+   * Normalized to a 0x-prefixed 32-byte hex string.
+   */
+  deployerKey: `0x${string}`;
+  /** Univocity contract release tag for the deploy manifest (default `latest`). */
+  releaseTag: string;
+  /** Local deploy-manifest JSON path — skips the GitHub release fetch. */
+  releaseManifest: string | undefined;
+  /** Deployment record output path (default: stdout). */
+  out: string | undefined;
+};
+
+/** Validate/normalize a 32-byte secp256k1 private key hex string. */
+function parseDeployerKey(raw: string): `0x${string}` {
+  const hex = raw.startsWith("0x") ? raw.slice(2) : raw;
+  if (!/^[0-9a-fA-F]{64}$/.test(hex)) {
+    throw new Error(
+      "--deployer-key must be a 32-byte hex secp256k1 private key (0x…64 hex chars)",
+    );
+  }
+  return `0x${hex.toLowerCase()}` as `0x${string}`;
+}
+
+export function parseDeployOptions(args: LooseParsedArgs): DeployOptions {
+  const alg = optionalStringOption(args, "bootstrap-alg") ?? "es256";
+  if (alg !== "es256" && alg !== "ks256") {
+    throw new Error(
+      `invalid --bootstrap-alg '${alg}' (expected es256 or ks256)`,
+    );
+  }
+
+  const generate = args["bootstrap-es256-generate"] === true;
+  const pemOut = optionalStringOption(args, "bootstrap-es256-pem-out");
+  const pem = optionalStringOption(args, "bootstrap-es256-pem");
+
+  if (alg === "es256") {
+    if (generate && pem !== undefined) {
+      throw new Error(
+        "--bootstrap-es256-generate and --bootstrap-es256-pem are mutually exclusive",
+      );
+    }
+    if (generate && pemOut === undefined) {
+      throw new Error(
+        "--bootstrap-es256-generate requires --bootstrap-es256-pem-out (the generated private key must be kept — it signs the root grant)",
+      );
+    }
+    if (!generate && pemOut !== undefined) {
+      throw new Error(
+        "--bootstrap-es256-pem-out is only meaningful with --bootstrap-es256-generate",
+      );
+    }
+    if (!generate && pem === undefined) {
+      throw new Error(
+        "es256 bootstrap needs a key: pass --bootstrap-es256-generate (with --bootstrap-es256-pem-out) or --bootstrap-es256-pem <path>",
+      );
+    }
+  }
+
+  return {
+    ...parseForestrieCommonOptions(args),
+    bootstrapAlg: alg,
+    bootstrapEs256Generate: generate,
+    bootstrapEs256PemOut: pemOut,
+    bootstrapEs256Pem: pem,
+    ownerAddress: optionalStringOption(args, "owner-address", "OWNER_ADDRESS"),
+    rpcUrl: requiredStringOption(args, "rpc-url", "RPC_URL"),
+    deployerKey: parseDeployerKey(
+      requiredStringOption(args, "deployer-key", "DEPLOYER_KEY"),
+    ),
+    releaseTag:
+      optionalStringOption(args, "release-tag") ?? DEFAULT_DEPLOY_RELEASE_TAG,
+    releaseManifest: optionalStringOption(args, "release-manifest"),
+    out: optionalStringOption(args, "out"),
+  };
+}

package/src/options/fetch-accumulator.ts

@@ -0,0 +1,62 @@
+import type { LooseParsedArgs } from "@forestrie/cli-kit";
+import {
+  optionalStringOption,
+  parseForestrieCommonOptions,
+  requiredStringOption,
+  type ForestrieCommonOptions,
+} from "./common.js";
+
+/**
+ * `forestrie fetch-accumulator` (FOR-297 D5): read the log's on-chain
+ * `logState` and cache it as a structured snapshot artifact — the
+ * `--known-accumulator` input for fully offline chain-anchored verification.
+ * The snapshot binds `(chainId, univocity, logId, size, block)` so the read
+ * is auditable and falsifiable: anyone with RPC can re-run it at that block.
+ */
+export type FetchAccumulatorOptions = ForestrieCommonOptions & {
+  /** ImutableUnivocity contract address. */
+  univocity: string;
+  /** Log id (UUID or hex). */
+  logId: string;
+  /** JSON-RPC endpoint (`RPC_URL`) — the trusted chain reader. */
+  rpcUrl: string;
+  /** Output path for the snapshot CBOR. */
+  out: string;
+  /** Snapshot the latest anchored state at/before this block, sourced
+   * from CheckpointPublished events (FOR-368; no archive node needed). */
+  atBlock: bigint | undefined;
+  /** Lower bound for the event scan (`--at-block` mode). */
+  fromBlock: bigint | undefined;
+};
+
+function optionalBlockOption(
+  args: LooseParsedArgs,
+  name: string,
+): bigint | undefined {
+  const raw = optionalStringOption(args, name);
+  if (raw === undefined) return undefined;
+  let value: bigint;
+  try {
+    value = BigInt(raw);
+  } catch {
+    throw new Error(`--${name} must be a block number`);
+  }
+  if (value < 0n) {
+    throw new Error(`--${name} must be a non-negative block number`);
+  }
+  return value;
+}
+
+export function parseFetchAccumulatorOptions(
+  args: LooseParsedArgs,
+): FetchAccumulatorOptions {
+  return {
+    ...parseForestrieCommonOptions(args),
+    univocity: requiredStringOption(args, "univocity"),
+    logId: requiredStringOption(args, "log-id"),
+    rpcUrl: requiredStringOption(args, "rpc-url", "RPC_URL"),
+    out: requiredStringOption(args, "out"),
+    atBlock: optionalBlockOption(args, "at-block"),
+    fromBlock: optionalBlockOption(args, "from-block"),
+  };
+}

package/src/options/onboard-genesis.ts

@@ -0,0 +1,74 @@
+import type { LooseParsedArgs } from "@forestrie/cli-kit";
+import {
+  optionalStringOption,
+  parseForestrieCommonOptions,
+  requiredStringOption,
+  type ForestrieCommonOptions,
+} from "./common.js";
+
+/** Default chain id (Base Sepolia) when `--chain-id`/`CHAIN_ID` absent. */
+export const DEFAULT_CHAIN_ID = "84532";
+
+/** `forestrie onboard-genesis` — FOR-406 (plan-2607-27 W2). */
+export type OnboardGenesisOptions = ForestrieCommonOptions & {
+  /** SCRAPI origin, no trailing slash (`FORESTRIE_BASE_URL`). */
+  baseUrl: string;
+  /** deploy's `--out` JSON; supplies univocity + logId when set. */
+  deployment: string | undefined;
+  /** ImutableUnivocity contract address (from `--deployment` when absent). */
+  univocity: string | undefined;
+  /** Forest (genesis) log id (from `--deployment` when absent). */
+  logId: string | undefined;
+  /** ES256 bootstrap key PEM (private or public; only the pubkey is used). */
+  bootstrapPem: string;
+  /** Chain id recorded in the genesis (`CHAIN_ID`, default 84532). */
+  chainId: string;
+  /** Delegation coordinator origin; signing-route webhook is derived. */
+  coordinatorUrl: string | undefined;
+  /** Explicit webhook override (wins over `--coordinator-url`). */
+  webhookUrl: string | undefined;
+  /**
+   * Pre-minted onboard token (`ONBOARD_TOKEN`) — from
+   * `forestrie admin onboard-token` today, x402 settlement (ARC-0015) in
+   * future. This command never touches the operator credential.
+   */
+  onboardToken: string;
+  /** Fetch the public genesis back to this path after onboarding. */
+  out: string | undefined;
+};
+
+export function parseOnboardGenesisOptions(
+  args: LooseParsedArgs,
+): OnboardGenesisOptions {
+  const deployment = optionalStringOption(args, "deployment");
+  const univocity = optionalStringOption(args, "univocity");
+  const logId = optionalStringOption(args, "log-id");
+  if (deployment === undefined && (univocity === undefined || logId === undefined)) {
+    throw new Error(
+      "onboard-genesis needs --deployment <deployment.json> (from deploy --out) " +
+        "or both --univocity and --log-id",
+    );
+  }
+  const coordinatorUrl = optionalStringOption(args, "coordinator-url");
+  const webhookUrl = optionalStringOption(args, "webhook-url");
+  if (coordinatorUrl === undefined && webhookUrl === undefined) {
+    throw new Error(
+      "onboard-genesis needs --coordinator-url (signing-route webhook derived) " +
+        "or an explicit --webhook-url",
+    );
+  }
+  return {
+    ...parseForestrieCommonOptions(args),
+    baseUrl: requiredStringOption(args, "base-url", "FORESTRIE_BASE_URL"),
+    deployment,
+    univocity,
+    logId,
+    bootstrapPem: requiredStringOption(args, "bootstrap-pem"),
+    chainId:
+      optionalStringOption(args, "chain-id", "CHAIN_ID") ?? DEFAULT_CHAIN_ID,
+    coordinatorUrl,
+    webhookUrl,
+    onboardToken: requiredStringOption(args, "onboard-token", "ONBOARD_TOKEN"),
+    out: optionalStringOption(args, "out"),
+  };
+}

package/src/options/onboard-request.ts

@@ -0,0 +1,57 @@
+import type { LooseParsedArgs } from "@forestrie/cli-kit";
+import {
+  optionalStringOption,
+  parseForestrieCommonOptions,
+  requiredStringOption,
+  type ForestrieCommonOptions,
+} from "./common.js";
+
+/** Default request label when `--label` is absent. */
+export const DEFAULT_ONBOARD_REQUEST_LABEL = "forestrie-cli";
+
+/**
+ * `forestrie onboard-request` — the self-service front door (plan-2607-43
+ * slice 06): create a bootstrap-key-attested onboard request and redeem it
+ * into an onboard token, paying the x402 challenge when the deployment asks.
+ */
+export type OnboardRequestOptions = ForestrieCommonOptions & {
+  /** SCRAPI origin, no trailing slash (`FORESTRIE_BASE_URL`). */
+  baseUrl: string;
+  /** `forestrie deploy --out` artifact — the chain binding + alg source. */
+  deployment: string;
+  /** Bootstrap private key PEM (ES256 deployments) — signs the attestation. */
+  bootstrapPem: string | undefined;
+  /** Bootstrap private key hex (KS256 deployments) — signs the attestation. */
+  bootstrapKeyHex: string | undefined;
+  /** Contact email recorded on the request (`ONBOARD_CONTACT_EMAIL`). */
+  contactEmail: string;
+  label: string;
+  /**
+   * x402 payer key (`X402_PAYER_KEY`). Optional: without it, only requests
+   * the deployment approves (ops/auto) can redeem; with it, a 402 challenge
+   * at redeem is paid. REAL funds move on settlement.
+   */
+  payerKey: string | undefined;
+  /** Write the redeemed token here instead of stdout. */
+  out: string | undefined;
+};
+
+export function parseOnboardRequestOptions(
+  args: LooseParsedArgs,
+): OnboardRequestOptions {
+  return {
+    ...parseForestrieCommonOptions(args),
+    baseUrl: requiredStringOption(args, "base-url", "FORESTRIE_BASE_URL"),
+    deployment: requiredStringOption(args, "deployment"),
+    bootstrapPem: optionalStringOption(args, "bootstrap-pem"),
+    bootstrapKeyHex: optionalStringOption(args, "bootstrap-key-hex"),
+    contactEmail: requiredStringOption(
+      args,
+      "contact-email",
+      "ONBOARD_CONTACT_EMAIL",
+    ),
+    label: optionalStringOption(args, "label") ?? DEFAULT_ONBOARD_REQUEST_LABEL,
+    payerKey: optionalStringOption(args, "payer-key", "X402_PAYER_KEY"),
+    out: optionalStringOption(args, "out"),
+  };
+}

package/src/options/register-grant.ts

@@ -0,0 +1,72 @@
+import type { LooseParsedArgs } from "@forestrie/cli-kit";
+import {
+  optionalStringOption,
+  parseForestrieCommonOptions,
+  requiredStringOption,
+  type ForestrieCommonOptions,
+} from "./common.js";
+import {
+  DEFAULT_POLL_INTERVAL_SECONDS,
+  DEFAULT_TIMEOUT_SECONDS,
+  durationOptionMs,
+} from "./register.js";
+
+/**
+ * `forestrie register-grant` — FOR-343 (writer-only; ADR-0052).
+ *
+ * Authorizes ONE statement writer on an existing data log (extend-only).
+ * Several signers on one data log means several grants, each naming that log.
+ * Grant leaves are sequenced into the OWNER (auth) log; the data log holds
+ * only statements. Log creation and bootstrap shapes live in `create-log`.
+ */
+export type RegisterGrantOptions = ForestrieCommonOptions & {
+  /** SCRAPI origin (`FORESTRIE_BASE_URL`). */
+  baseUrl: string;
+  /** Owner (auth) log the grant leaf is sequenced into. */
+  ownerLog: string;
+  /** Child/data log the grant authorizes. */
+  dataLog: string;
+  /** PKCS#8 PEM key that signs the grant statement (the granting authority). */
+  signWith: string;
+  /** PEM of the signer being authorized (grantData = ES256 x||y). */
+  signerPem: string;
+  /** Parent grant credential authorizing this registration. */
+  parentGrantB64: string;
+  /** Completed grant base64 output path (default: stdout). */
+  outB64: string | undefined;
+  /**
+   * Forest bootstrap/root log id — first `/register/` path segment
+   * (grant genesis lookup is keyed by the forest root). Defaults to
+   * `--owner-log`, which is correct whenever the owner IS the root (the
+   * self-referential bootstrap and first-level child grants).
+   */
+  bootstrapLog: string;
+  /** Overall receipt wait budget, milliseconds (`--timeout` seconds). */
+  timeoutMs: number;
+  /** Poll pacing, milliseconds (`--poll-interval` seconds). */
+  pollIntervalMs: number;
+};
+
+export function parseRegisterGrantOptions(
+  args: LooseParsedArgs,
+): RegisterGrantOptions {
+  const ownerLog = requiredStringOption(args, "owner-log");
+  const options: RegisterGrantOptions = {
+    ...parseForestrieCommonOptions(args),
+    baseUrl: requiredStringOption(args, "base-url", "FORESTRIE_BASE_URL"),
+    ownerLog,
+    dataLog: requiredStringOption(args, "data-log"),
+    signWith: requiredStringOption(args, "sign-with"),
+    signerPem: requiredStringOption(args, "signer-pem"),
+    parentGrantB64: requiredStringOption(args, "parent-grant-b64"),
+    outB64: optionalStringOption(args, "out-b64"),
+    bootstrapLog: optionalStringOption(args, "bootstrap-log") ?? ownerLog,
+    timeoutMs: durationOptionMs(args, "timeout", DEFAULT_TIMEOUT_SECONDS),
+    pollIntervalMs: durationOptionMs(
+      args,
+      "poll-interval",
+      DEFAULT_POLL_INTERVAL_SECONDS,
+    ),
+  };
+  return options;
+}

package/src/options/register.ts

@@ -0,0 +1,71 @@
+import type { LooseParsedArgs } from "@forestrie/cli-kit";
+import {
+  optionalStringOption,
+  parseForestrieCommonOptions,
+  requiredStringOption,
+  type ForestrieCommonOptions,
+} from "./common.js";
+
+/** Default overall receipt wait (`--timeout`), seconds. */
+export const DEFAULT_TIMEOUT_SECONDS = 60;
+/** Default poll pacing (`--poll-interval`), seconds. */
+export const DEFAULT_POLL_INTERVAL_SECONDS = 1;
+
+/** `forestrie register` — FOR-342. */
+export type RegisterOptions = ForestrieCommonOptions & {
+  /** SCRAPI origin, no trailing slash (`FORESTRIE_BASE_URL`). */
+  baseUrl: string;
+  /** Target log id (UUID). */
+  logId: string;
+  /**
+   * COSE Sign1 signed statement file to register; `-` or absent reads
+   * the statement bytes from stdin.
+   */
+  statement: string | undefined;
+  /** `Authorization: Forestrie-Grant` bearer credential (`GRANT_B64`). */
+  grantB64: string;
+  /** Receipt output path (default: human/JSON summary only). */
+  out: string | undefined;
+  /** Overall receipt wait budget, milliseconds (`--timeout` seconds). */
+  timeoutMs: number;
+  /** Poll pacing, milliseconds (`--poll-interval` seconds). */
+  pollIntervalMs: number;
+};
+
+/**
+ * Read `--<name>` as a positive (fractional allowed) number of seconds,
+ * returning milliseconds; a missing flag yields the default. Shared with
+ * `register-grant`, which follows the same 303 receipt-redirect contract.
+ */
+export function durationOptionMs(
+  args: LooseParsedArgs,
+  name: string,
+  defaultSeconds: number,
+): number {
+  const raw = optionalStringOption(args, name);
+  if (raw === undefined) {
+    return Math.round(defaultSeconds * 1000);
+  }
+  const seconds = Number(raw);
+  if (!Number.isFinite(seconds) || seconds <= 0) {
+    throw new Error(`--${name} must be a positive number of seconds`);
+  }
+  return Math.round(seconds * 1000);
+}
+
+export function parseRegisterOptions(args: LooseParsedArgs): RegisterOptions {
+  return {
+    ...parseForestrieCommonOptions(args),
+    baseUrl: requiredStringOption(args, "base-url", "FORESTRIE_BASE_URL"),
+    logId: requiredStringOption(args, "log-id"),
+    statement: optionalStringOption(args, "statement"),
+    grantB64: requiredStringOption(args, "grant-b64", "GRANT_B64"),
+    out: optionalStringOption(args, "out"),
+    timeoutMs: durationOptionMs(args, "timeout", DEFAULT_TIMEOUT_SECONDS),
+    pollIntervalMs: durationOptionMs(
+      args,
+      "poll-interval",
+      DEFAULT_POLL_INTERVAL_SECONDS,
+    ),
+  };
+}

package/src/options/sign-statement.ts

@@ -0,0 +1,64 @@
+import type { LooseParsedArgs } from "@forestrie/cli-kit";
+import {
+  optionalStringOption,
+  parseForestrieCommonOptions,
+  requiredStringOption,
+  type ForestrieCommonOptions,
+} from "./common.js";
+
+/** `forestrie sign-statement` — FOR-341. */
+export type SignStatementOptions = ForestrieCommonOptions & {
+  /** ES256 P-256 private signing key path (SEC1/PKCS#8 PEM or JWK). */
+  key: string;
+  /** Payload file to wrap as the COSE Sign1 payload (`-` = stdin). */
+  payload: string;
+  /** Payload content type (COSE `content type` header, label 3, protected). */
+  contentType: string;
+  /**
+   * Issuer (CWT claim 1): literal StringOrURI, or `ckt` for the RFC 9679
+   * thumbprint URI. Default (unset): hex kid (devdocs ADR-0055).
+   * An explicit empty string is preserved so the run layer can reject it
+   * through the structured error path (a silent default substitution
+   * would sign a different issuer than the caller asked for).
+   */
+  iss: string | undefined;
+  /** Subject (CWT claim 2). Default (unset): `sha-256:<hex>` of payload. */
+  sub: string | undefined;
+  /**
+   * Issued-at (CWT claim 6), raw: `now` or unix-seconds digits. Validated
+   * and resolved in the run layer so a bad value produces the structured
+   * error report, not a parse-time stack trace.
+   */
+  iat: string | undefined;
+  /** Signed statement output path (default: stdout). */
+  out: string | undefined;
+};
+
+export function parseSignStatementOptions(
+  args: LooseParsedArgs,
+): SignStatementOptions {
+  return {
+    ...parseForestrieCommonOptions(args),
+    key: requiredStringOption(args, "key"),
+    payload: requiredStringOption(args, "payload"),
+    contentType:
+      optionalStringOption(args, "content-type") ?? "application/json",
+    iss: claimStringOption(args, "iss"),
+    sub: claimStringOption(args, "sub"),
+    iat: optionalStringOption(args, "iat"),
+    out: optionalStringOption(args, "out"),
+  };
+}
+
+/**
+ * As `optionalStringOption`, but an explicit `""` survives (that helper
+ * folds it into "unset", which for signed-claim inputs would silently
+ * substitute the default).
+ */
+function claimStringOption(
+  args: LooseParsedArgs,
+  name: string,
+): string | undefined {
+  if (args[name] === "") return "";
+  return optionalStringOption(args, name);
+}