@forestrie/forestrie-cli 0.8.0

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

@@ -0,0 +1,48 @@
+import type { LooseParsedArgs } from "@forestrie/cli-kit";
+import {
+  optionalStringOption,
+  parseForestrieCommonOptions,
+  requiredStringOption,
+  type ForestrieCommonOptions,
+} from "./common.js";
+
+/** Default onboard-token label when `--label` is absent. */
+export const DEFAULT_ONBOARD_TOKEN_LABEL = "forestrie-cli";
+
+/** `forestrie admin onboard-token` — FOR-406 (plan-2607-27 W1). */
+export type AdminOnboardTokenOptions = ForestrieCommonOptions & {
+  /** SCRAPI origin, no trailing slash (`FORESTRIE_BASE_URL`). */
+  baseUrl: string;
+  /**
+   * Operator credential (`CANOPY_OPS_ADMIN_TOKEN`). The `admin` family is
+   * the operator-credential surface (ADR-0052); participant commands never
+   * read this secret.
+   */
+  opsToken: string;
+  /** Token label recorded by the mint endpoint. */
+  label: string;
+  /**
+   * Chain binding (mandatory on every token since ADR-0059 D7): either read
+   * from a `forestrie deploy --out` artifact, or given explicitly.
+   */
+  deployment: string | undefined;
+  chainId: string | undefined;
+  univocityAddr: string | undefined;
+  /** Write the minted token here instead of stdout. */
+  out: string | undefined;
+};
+
+export function parseAdminOnboardTokenOptions(
+  args: LooseParsedArgs,
+): AdminOnboardTokenOptions {
+  return {
+    ...parseForestrieCommonOptions(args),
+    baseUrl: requiredStringOption(args, "base-url", "FORESTRIE_BASE_URL"),
+    opsToken: requiredStringOption(args, "ops-token", "CANOPY_OPS_ADMIN_TOKEN"),
+    label: optionalStringOption(args, "label") ?? DEFAULT_ONBOARD_TOKEN_LABEL,
+    deployment: optionalStringOption(args, "deployment"),
+    chainId: optionalStringOption(args, "chain-id"),
+    univocityAddr: optionalStringOption(args, "univocity"),
+    out: optionalStringOption(args, "out"),
+  };
+}

package/src/options/common.ts

@@ -0,0 +1,69 @@
+import {
+  readEvaluatedStringOption,
+  resolveVerbosity,
+  type LooseParsedArgs,
+} from "@forestrie/cli-kit";
+
+/** Options shared by every `forestrie` command (after parsing). */
+export type ForestrieCommonOptions = {
+  /** Emit machine-readable JSON on stdout instead of human output. */
+  json: boolean;
+  /**
+   * Config file path, if provided (`--config` / `FORESTRIE_CONFIG`).
+   * Stub: recorded at parse time; loading lands with the implementations.
+   */
+  config?: string;
+  /** Resolved output verbosity. */
+  verbosity: number;
+};
+
+/** Resolve the tool-wide common options at parse time. */
+export function parseForestrieCommonOptions(
+  args: LooseParsedArgs,
+): ForestrieCommonOptions {
+  const config =
+    readEvaluatedStringOption(args, "config") ??
+    process.env["FORESTRIE_CONFIG"] ??
+    undefined;
+  const options: ForestrieCommonOptions = {
+    json: args["json"] === true,
+    verbosity: resolveVerbosity(args),
+  };
+  if (config !== undefined && config !== "") {
+    options.config = config;
+  }
+  return options;
+}
+
+/**
+ * Read a string option (kebab or camelCase, `${env:…}` templates
+ * evaluated), falling back to `envVar` when the flag is absent.
+ */
+export function optionalStringOption(
+  args: LooseParsedArgs,
+  name: string,
+  envVar?: string,
+): string | undefined {
+  const value =
+    readEvaluatedStringOption(args, name) ??
+    (envVar ? process.env[envVar] : undefined);
+  return value === "" ? undefined : value;
+}
+
+/**
+ * As `optionalStringOption`, but a missing value is a usage error.
+ * Options with an env fallback are enforced here rather than with
+ * citty `required: true` (which cannot see the environment).
+ */
+export function requiredStringOption(
+  args: LooseParsedArgs,
+  name: string,
+  envVar?: string,
+): string {
+  const value = optionalStringOption(args, name, envVar);
+  if (value === undefined) {
+    const hint = envVar ? ` (or set ${envVar})` : "";
+    throw new Error(`missing required option --${name}${hint}`);
+  }
+  return value;
+}

package/src/options/complete-grant.ts

@@ -0,0 +1,40 @@
+import type { LooseParsedArgs } from "@forestrie/cli-kit";
+import {
+  optionalStringOption,
+  parseForestrieCommonOptions,
+  requiredStringOption,
+  type ForestrieCommonOptions,
+} from "./common.js";
+
+/**
+ * `forestrie complete-grant` — FOR-344.
+ *
+ * Self-create the `Authorization: Forestrie-Grant` header content from a
+ * checkpoint (and possibly an idtimestamp) — grants are derivable from
+ * log data, not operator-issued.
+ */
+export type CompleteGrantOptions = ForestrieCommonOptions & {
+  /** Registered (uncompleted) grant, base64 file. */
+  grant: string;
+  /** Checkpoint (.sth) for the owner log. */
+  checkpoint: string;
+  /** Massif .log blob for local leaf/path recovery. */
+  massif: string | undefined;
+  /** Leaf idtimestamp (hex or be8 file) when the grant lacks one. */
+  idtimestamp: string | undefined;
+  /** Completed grant base64 output path (default: stdout). */
+  outB64: string | undefined;
+};
+
+export function parseCompleteGrantOptions(
+  args: LooseParsedArgs,
+): CompleteGrantOptions {
+  return {
+    ...parseForestrieCommonOptions(args),
+    grant: requiredStringOption(args, "grant"),
+    checkpoint: requiredStringOption(args, "checkpoint"),
+    massif: optionalStringOption(args, "massif"),
+    idtimestamp: optionalStringOption(args, "idtimestamp"),
+    outB64: optionalStringOption(args, "out-b64"),
+  };
+}

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

@@ -0,0 +1,63 @@
+import type { LooseParsedArgs } from "@forestrie/cli-kit";
+import {
+  parseForestrieCommonOptions,
+  requiredStringOption,
+  type ForestrieCommonOptions,
+} from "./common.js";
+
+/**
+ * `forestrie create-consistency-proof` — FOR-368 Phase 3 (plan-2607-29).
+ *
+ * Build a portable, UNSIGNED top-up artifact from public massif tiles: one
+ * inclusion path per `--from-size` peak, proven at `--to-size`, plus the
+ * base accumulator. Any party with the tiles can produce it (SCRAPI §2.4
+ * Resolve Receipt, made third-party); the holder then verifies an old
+ * receipt tile-free with `verify --known-accumulator ... --consistency-proof`.
+ * Soundness never depends on who built it — the artifact can only fail
+ * against the holder's trusted snapshot, never mint trust.
+ */
+
+export type CreateConsistencyProofOptions = ForestrieCommonOptions & {
+  /** Massif blob paths, comma-separated (a spanning proof needs each). */
+  massifs: string[];
+  fromSize: bigint;
+  toSize: bigint;
+  out: string;
+};
+
+function requiredSize(args: LooseParsedArgs, name: string): bigint {
+  const raw = requiredStringOption(args, name);
+  let value: bigint;
+  try {
+    value = BigInt(raw);
+  } catch {
+    throw new Error(`--${name} must be an MMR size (integer)`);
+  }
+  if (value <= 0n) {
+    throw new Error(`--${name} must be a positive MMR size`);
+  }
+  return value;
+}
+
+export function parseCreateConsistencyProofOptions(
+  args: LooseParsedArgs,
+): CreateConsistencyProofOptions {
+  const massifs = requiredStringOption(args, "massif")
+    .split(",")
+    .map((f) => f.trim())
+    .filter((f) => f !== "");
+  if (massifs.length === 0) {
+    throw new Error("--massif requires at least one massif blob path");
+  }
+  const options: CreateConsistencyProofOptions = {
+    ...parseForestrieCommonOptions(args),
+    massifs,
+    fromSize: requiredSize(args, "from-size"),
+    toSize: requiredSize(args, "to-size"),
+    out: requiredStringOption(args, "out"),
+  };
+  if (options.toSize <= options.fromSize) {
+    throw new Error("--to-size must be greater than --from-size");
+  }
+  return options;
+}

package/src/options/create-log.ts

@@ -0,0 +1,99 @@
+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 create-log` — FOR-390 / ADR-0052.
+ *
+ * Create a log and set its owner (K(L)). The create grant is sequenced into
+ * the parent/auth log (`--owner-log`); `--new-log` is the log being created.
+ * Absorbs the create / self-referential / auth-log shapes removed from
+ * `register-grant` (which is now writer-only).
+ */
+export type CreateLogOptions = ForestrieCommonOptions & {
+  /** SCRAPI origin (`FORESTRIE_BASE_URL`). */
+  baseUrl: string;
+  /** Parent/auth log the create grant is sequenced into. */
+  ownerLog: string;
+  /** The log being created. */
+  newLog: string;
+  /** Create a child auth log rather than a data log. */
+  authLog: boolean;
+  /**
+   * Mark the creation grant `GF_DERIVED | GF_CHILD_PAYMENT_REQUIRED`
+   * (adr-0062): child grants registered under the new log's authority require
+   * an x402 payment. Auth-shaped grants only.
+   */
+  childPaymentRequired: boolean;
+  /** Root bootstrap self-referential grant (`--new-log == --owner-log`). */
+  selfReferential: boolean;
+  /** PEM of the new log's owner (grantData = ES256 x||y); required unless self-referential. */
+  signerPem: string | undefined;
+  /** Granting authority PEM (the parent log's K(L)) that signs the grant. */
+  signWith: string;
+  /**
+   * Pre-register the child log's public root with the delegation coordinator
+   * (parent-authorized, ADR-0053) WITHOUT sequencing the create leaf, so the
+   * owner can `delegate` (pre-sign) before the log exists. Emits the create
+   * grant to `--out-b64` for the later real `create-log`.
+   */
+  prepare: boolean;
+  /** Parent grant credential authorizing this registration. */
+  parentGrantB64: string | undefined;
+  /** 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`.
+   */
+  bootstrapLog: string;
+  /** Overall receipt wait budget, milliseconds (`--timeout` seconds). */
+  timeoutMs: number;
+  /** Poll pacing, milliseconds (`--poll-interval` seconds). */
+  pollIntervalMs: number;
+};
+
+export function parseCreateLogOptions(args: LooseParsedArgs): CreateLogOptions {
+  const ownerLog = requiredStringOption(args, "owner-log");
+  const options: CreateLogOptions = {
+    ...parseForestrieCommonOptions(args),
+    baseUrl: requiredStringOption(args, "base-url", "FORESTRIE_BASE_URL"),
+    ownerLog,
+    newLog: requiredStringOption(args, "new-log"),
+    authLog: args["auth-log"] === true,
+    childPaymentRequired: args["child-payment-required"] === true,
+    selfReferential: args["self-referential"] === true,
+    signerPem: optionalStringOption(args, "signer-pem"),
+    signWith: requiredStringOption(args, "sign-with"),
+    prepare: args["prepare"] === true,
+    parentGrantB64: optionalStringOption(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,
+    ),
+  };
+  if (options.selfReferential && options.parentGrantB64 !== undefined) {
+    throw new Error(
+      "--self-referential and --parent-grant-b64 are mutually exclusive (the bootstrap leaf has no parent)",
+    );
+  }
+  if (!options.selfReferential && options.parentGrantB64 === undefined) {
+    throw new Error(
+      "either --parent-grant-b64 or --self-referential is required",
+    );
+  }
+  return options;
+}

package/src/options/create-receipt.ts

@@ -0,0 +1,243 @@
+import type { LooseParsedArgs } from "@forestrie/cli-kit";
+import {
+  optionalStringOption,
+  parseForestrieCommonOptions,
+  requiredStringOption,
+  type ForestrieCommonOptions,
+} from "./common.js";
+
+/**
+ * `forestrie resolve-receipt` (alias `create-receipt`) — FOR-345 / FOR-418.
+ *
+ * ONE receipt producer; the source is chosen by the flags present, not a
+ * `--mode` (plan-2607-32 D3). Three sources, mutually exclusive:
+ *
+ * - **tiles** (`--massif`): rebuild the leaf→peak path from a massif blob and
+ *   either attach it to a checkpoint's pre-signed peak receipt (`--checkpoint`,
+ *   offline) or verify the computed peak against the on-chain accumulator
+ *   (`--univocity` + `--log-id` + `--rpc-url`, report-only). Leaf addressing:
+ *   exactly one of `--mmr-index` / `--entry-id`.
+ * - **`.sth` chain** (`--checkpoint-chain`): tile-free FRESHEN of a stale
+ *   `--receipt` — fold the retained checkpoint chain, extend the receipt's old
+ *   path to the current peak, re-emit under the chain's own tail checkpoint.
+ * - **calldata** (`--rpc-url`/`--univocity`/`--log-id` + `--checkpoint`):
+ *   tile-free FRESHEN reading the climb material from the on-chain
+ *   `publishCheckpoint` calldata; emission borrows the separately-supplied
+ *   latest `--checkpoint` (calldata carries no per-peak receipts).
+ *
+ * Both freshen sources re-anchor to the current accumulator; the trust posture
+ * (freshness vs signer provenance) is chosen at verify — see the receipt trust model:
+ * https://github.com/forestrie/protocol/blob/main/spec/receipt-trust-model.md
+ * Freshen recomputes the leaf value exactly as `verify` does, from `--payload`
+ * (statement receipts) or the committed grant (`--committed-grant` /
+ * `--committed-grant-file`) + `--entry-id`.
+ *
+ * Multiple sources → error ("choose one source"); an under-specified source →
+ * error naming what's missing. No implicit pick — every ambiguous invocation
+ * fails closed with guidance.
+ */
+export type CreateReceiptOptions = ForestrieCommonOptions & {
+  anchor: "checkpoint" | "chain" | "freshen-sth" | "freshen-calldata";
+  /** Tiles source: massif .log blob holding the leaf and its proof nodes. */
+  massif: string | undefined;
+  /** MMR index of the leaf to prove (`--mmr-index` addressing, tiles source). */
+  mmrIndex: bigint | undefined;
+  /** Permanent SCRAPI entry id (leaf addressing / freshen idtimestamp). */
+  entryId: string | undefined;
+  /** Checkpoint (.sth) with pre-signed peak receipts (tiles + `--checkpoint`). */
+  checkpoint: string | undefined;
+  /** ImutableUnivocity contract address (tiles + chain-anchored mode). */
+  univocity: string | undefined;
+  /** Log id for the on-chain accumulator read (chain mode). */
+  logId: string | undefined;
+  /** JSON-RPC endpoint (`RPC_URL`, chain mode). */
+  rpcUrl: string | undefined;
+  /** Stale receipt to freshen (`.sth`-chain / calldata source). */
+  receipt: string | undefined;
+  /** Retained `.sth` checkpoint chain (dir or comma-separated files). */
+  checkpointChain: string | undefined;
+  /** Committed grant, base64 (freshen leaf-value source, grant receipts). */
+  committedGrant: string | undefined;
+  /** Committed grant CBOR file (freshen leaf-value source, grant receipts). */
+  committedGrantFile: string | undefined;
+  /** Registered statement payload (freshen leaf-value source, statement
+   * receipts) — the leaf ContentHash is `SHA-256(payload)`, as in `verify`. */
+  payload: string | undefined;
+  /** Receipt output path (default: stdout). */
+  out: string | undefined;
+  /** Rewrite the `--receipt` file in place with the freshened receipt (freshen
+   * only; mutually exclusive with `--out`). */
+  inPlace: boolean;
+  /** Trusted accumulator snapshot (`fetch-accumulator` output) to bind the
+   * freshened state against — anchors freshness (not signer provenance), fails
+   * closed on mismatch; freshen only. See the receipt trust model:
+   * https://github.com/forestrie/protocol/blob/main/spec/receipt-trust-model.md */
+  knownAccumulator: string | undefined;
+};
+
+function parseMMRIndex(raw: string): bigint {
+  if (!/^\d+$/.test(raw)) {
+    throw new Error(
+      `invalid --mmr-index '${raw}' (expected a non-negative integer)`,
+    );
+  }
+  return BigInt(raw);
+}
+
+export function parseCreateReceiptOptions(
+  args: LooseParsedArgs,
+): CreateReceiptOptions {
+  const massif = optionalStringOption(args, "massif");
+  const receipt = optionalStringOption(args, "receipt");
+  const checkpointChain = optionalStringOption(args, "checkpoint-chain");
+  const checkpoint = optionalStringOption(args, "checkpoint");
+  const univocity = optionalStringOption(args, "univocity");
+  const logId = optionalStringOption(args, "log-id");
+  const rpcUrl = optionalStringOption(args, "rpc-url", "RPC_URL");
+  const committedGrant = optionalStringOption(args, "committed-grant");
+  const committedGrantFile = optionalStringOption(args, "committed-grant-file");
+  const payload = optionalStringOption(args, "payload");
+  const entryId = optionalStringOption(args, "entry-id");
+  const out = optionalStringOption(args, "out");
+  const inPlace = args["in-place"] === true;
+  const knownAccumulator = optionalStringOption(args, "known-accumulator");
+  const common = parseForestrieCommonOptions(args);
+
+  const base = {
+    massif,
+    checkpoint,
+    univocity,
+    logId,
+    rpcUrl,
+    receipt,
+    checkpointChain,
+    committedGrant,
+    committedGrantFile,
+    payload,
+    entryId,
+    out,
+    inPlace,
+    knownAccumulator,
+  };
+
+  if (inPlace && out !== undefined) {
+    throw new Error("choose --out or --in-place, not both");
+  }
+
+  // Source selection is exclusive: tiles (--massif) vs freshen (--receipt).
+  if (massif !== undefined && receipt !== undefined) {
+    throw new Error(
+      "choose one source: --massif (build from tiles) or --receipt (freshen a stale receipt) — not both",
+    );
+  }
+  if (inPlace && receipt === undefined) {
+    throw new Error(
+      "--in-place only applies to freshen (--receipt) — there is no receipt file to rewrite",
+    );
+  }
+  if (knownAccumulator !== undefined && receipt === undefined) {
+    throw new Error(
+      "--known-accumulator only applies to freshen (--receipt)",
+    );
+  }
+
+  // --- FRESHEN source (--receipt + a tile-free chain) ---
+  if (receipt !== undefined) {
+    // Leaf value: a statement payload (--payload, as in `verify`) or a committed
+    // grant (--committed-grant/-file, as in `verify-grant`) — exactly one.
+    const hasGrant =
+      committedGrant !== undefined || committedGrantFile !== undefined;
+    const hasPayload = payload !== undefined;
+    if (hasGrant && hasPayload) {
+      throw new Error(
+        "choose one leaf source: --payload (statement) or --committed-grant/--committed-grant-file (grant)",
+      );
+    }
+    if (!hasGrant && !hasPayload) {
+      throw new Error(
+        "freshen needs the leaf's content: --payload (statement) or --committed-grant/--committed-grant-file (grant)",
+      );
+    }
+    if (hasPayload && entryId === undefined) {
+      throw new Error(
+        "freshen from --payload needs the SCRAPI entry id (idtimestamp): --entry-id",
+      );
+    }
+    if (committedGrantFile !== undefined && entryId === undefined) {
+      throw new Error(
+        "freshen from a raw grant file needs the SCRAPI entry id (idtimestamp): --entry-id",
+      );
+    }
+    const hasSth = checkpointChain !== undefined;
+    const hasCalldata =
+      univocity !== undefined || rpcUrl !== undefined || logId !== undefined;
+    if (hasSth && hasCalldata) {
+      throw new Error(
+        "choose one freshen source: --checkpoint-chain (.sth) or --rpc-url/--univocity/--log-id (calldata)",
+      );
+    }
+    if (hasSth) {
+      return { ...common, ...base, anchor: "freshen-sth", mmrIndex: undefined };
+    }
+    if (hasCalldata) {
+      if (univocity === undefined || logId === undefined || rpcUrl === undefined) {
+        throw new Error(
+          "calldata freshen requires --univocity, --log-id and --rpc-url",
+        );
+      }
+      if (checkpoint === undefined) {
+        throw new Error(
+          "calldata freshen requires --checkpoint (the latest .sth) for emission — calldata carries no pre-signed peak receipts",
+        );
+      }
+      return {
+        ...common,
+        ...base,
+        anchor: "freshen-calldata",
+        mmrIndex: undefined,
+      };
+    }
+    throw new Error(
+      "freshen (--receipt) needs a tile-free source: --checkpoint-chain (.sth) or --rpc-url/--univocity/--log-id (calldata)",
+    );
+  }
+
+  // --- TILES source (--massif) ---
+  if (massif === undefined) {
+    throw new Error(
+      "a source is required: --massif (build from tiles) or --receipt + --checkpoint-chain (freshen)",
+    );
+  }
+  const rawMMRIndex = optionalStringOption(args, "mmr-index");
+  if ((rawMMRIndex === undefined) === (entryId === undefined)) {
+    throw new Error(
+      "exactly one of --mmr-index or --entry-id is required to address the leaf",
+    );
+  }
+  const mmrIndex =
+    rawMMRIndex !== undefined ? parseMMRIndex(rawMMRIndex) : undefined;
+
+  let anchor: "checkpoint" | "chain";
+  if (checkpoint !== undefined && univocity === undefined) {
+    anchor = "checkpoint";
+  } else if (checkpoint === undefined && univocity !== undefined) {
+    if (logId === undefined || rpcUrl === undefined) {
+      throw new Error(
+        "chain-anchored mode requires --univocity, --log-id and --rpc-url",
+      );
+    }
+    anchor = "chain";
+  } else {
+    throw new Error(
+      "exactly one of --checkpoint (offline) or --univocity (chain-anchored) is required",
+    );
+  }
+
+  return {
+    ...common,
+    ...base,
+    anchor,
+    massif: requiredStringOption(args, "massif"),
+    mmrIndex,
+  };
+}

package/src/options/decode-receipt.ts

@@ -0,0 +1,25 @@
+import type { LooseParsedArgs } from "@forestrie/cli-kit";
+import {
+  parseForestrieCommonOptions,
+  type ForestrieCommonOptions,
+} from "./common.js";
+
+/** `forestrie decode-receipt` — FOR-346. */
+export type DecodeReceiptOptions = ForestrieCommonOptions & {
+  /**
+   * COSE receipt file to decode (Sign1 + MMR inclusion).
+   * Omitted or `-`: read the receipt CBOR from stdin.
+   */
+  receipt?: string;
+};
+
+export function parseDecodeReceiptOptions(
+  args: LooseParsedArgs,
+): DecodeReceiptOptions {
+  const options: DecodeReceiptOptions = parseForestrieCommonOptions(args);
+  const receipt = typeof args["receipt"] === "string" ? args["receipt"] : "";
+  if (receipt !== "") {
+    options.receipt = receipt;
+  }
+  return options;
+}

package/src/options/delegate.ts

@@ -0,0 +1,93 @@
+import type { LooseParsedArgs } from "@forestrie/cli-kit";
+import {
+  optionalStringOption,
+  parseForestrieCommonOptions,
+  requiredStringOption,
+  type ForestrieCommonOptions,
+} from "./common.js";
+
+/** Default horizon MMR end — effectively unbounded (Number.MAX_SAFE_INTEGER). */
+export const DEFAULT_HORIZON_MMR_END = Number.MAX_SAFE_INTEGER;
+
+/**
+ * `forestrie delegate` — FOR-390 / ADR-0052.
+ *
+ * Authorize a custodian-vouched sealer to publish checkpoints for a log the
+ * caller owns (K(L)). Public coordinator endpoints only — no operator token,
+ * no RPC. The registrar voucher is verified against a caller-known
+ * registrar key before the delegation certificate is bound (fail closed).
+ */
+export type DelegateOptions = ForestrieCommonOptions & {
+  /** Delegation coordinator origin (`DELEGATION_COORDINATOR_URL`). */
+  coordinatorUrl: string;
+  /** Target log id (UUID). */
+  logId: string;
+  /** ES256 log-root PEM (K(L)) that authorizes the delegation. */
+  signWith: string;
+  /** The known key that vouches for the operator's sealer — the registrar's
+   * voucher-signing key, base64 `x||y` (`KNOWN_SEALER_KEY`). */
+  knownSealerKey: string;
+  /** Exclusive MMR end of the horizon lease (mmrStart is fixed 0). */
+  horizonMmrEnd: number;
+  /** Lease TTL seconds; defaults to the standing entry's suggestedTtlSeconds. */
+  ttlSeconds: number | undefined;
+  /** When set, write the submitted certificate base64 to this path. */
+  outB64: string | undefined;
+};
+
+/** Read `--<name>` as a finite number; a missing flag yields `fallback`. */
+function numberOption(
+  args: LooseParsedArgs,
+  name: string,
+  fallback: number | undefined,
+): number | undefined {
+  const raw = optionalStringOption(args, name);
+  if (raw === undefined) return fallback;
+  const value = Number(raw);
+  if (!Number.isFinite(value)) {
+    throw new Error(`--${name} must be a number`);
+  }
+  return value;
+}
+
+export function parseDelegateOptions(args: LooseParsedArgs): DelegateOptions {
+  const horizonMmrEnd = numberOption(
+    args,
+    "horizon-mmr-end",
+    DEFAULT_HORIZON_MMR_END,
+  ) as number;
+  // The horizon binds a durable on-chain delegation scope [0, mmrEnd) — reject
+  // non-integer / out-of-range values before they flow into cert + on-chain
+  // encoding (ADR-0050 V4). MMR indices are non-negative safe integers.
+  if (!Number.isSafeInteger(horizonMmrEnd) || horizonMmrEnd <= 0) {
+    throw new Error(
+      "--horizon-mmr-end must be a positive integer no larger than 2^53-1",
+    );
+  }
+  const ttlSeconds = numberOption(args, "ttl-seconds", undefined);
+  if (
+    ttlSeconds !== undefined &&
+    (!Number.isSafeInteger(ttlSeconds) || ttlSeconds <= 0)
+  ) {
+    throw new Error("--ttl-seconds must be a positive integer");
+  }
+  const options: DelegateOptions = {
+    ...parseForestrieCommonOptions(args),
+    coordinatorUrl: requiredStringOption(
+      args,
+      "coordinator-url",
+      "DELEGATION_COORDINATOR_URL",
+    ),
+    logId: requiredStringOption(args, "log-id"),
+    signWith: requiredStringOption(args, "sign-with"),
+    knownSealerKey: requiredStringOption(
+      args,
+      "known-sealer-key",
+      "KNOWN_SEALER_KEY",
+    ),
+    horizonMmrEnd,
+    ttlSeconds,
+    outB64: optionalStringOption(args, "out-b64"),
+  };
+  return options;
+}