@forestrie/forestrie-cli 0.8.0

package/src/lib/deploy-artifact.ts

@@ -0,0 +1,79 @@
+/**
+ * ImutableUnivocity creation-bytecode acquisition for `forestrie deploy`
+ * (FOR-340).
+ *
+ * Default path: fetch the deploy-manifest + sha256 sidecar from the
+ * univocity GitHub release (deploy-core `fetchUnivocityReleaseManifest`,
+ * `latest` resolved via the GitHub API), verify the manifest bytes
+ * against the sidecar, then verify every embedded bytecode digest.
+ *
+ * `--release-manifest <path>` swaps the fetch for a local file (offline /
+ * test escape hatch). The sidecar step is skipped — the file is operator
+ * supplied — but the embedded per-contract sha256 digests are still
+ * verified by `verifyAndParseImutableManifest`.
+ */
+import { readFileSync } from "node:fs";
+import {
+  fetchUnivocityReleaseManifest,
+  verifyAndParseImutableManifest,
+  verifyManifestBytesWithSidecar,
+  type DeployManifest,
+} from "@forestrie/deploy-core";
+import type { Hex } from "viem";
+import { errorMessage } from "./sign-statement-key.js";
+
+/** Verified deployable artifact. */
+export type ImutableDeployArtifact = {
+  manifest: DeployManifest;
+  /** ImutableUnivocity creation bytecode (digest-verified). */
+  creationBytecode: Hex;
+  /** Manifest releaseId (release tag for fetched manifests). */
+  releaseId: string;
+  source: "release" | "file";
+};
+
+export type LoadImutableArtifactInput = {
+  /** Local deploy-manifest JSON path; overrides the release fetch. */
+  manifestPath?: string | undefined;
+  /** Release tag (`latest` or `vX.Y.Z`) when fetching. */
+  releaseTag: string;
+};
+
+/** Load + verify the ImutableUnivocity deploy artifact. */
+export async function loadImutableArtifact(
+  input: LoadImutableArtifactInput,
+): Promise<ImutableDeployArtifact> {
+  if (input.manifestPath !== undefined) {
+    let raw: string;
+    try {
+      raw = readFileSync(input.manifestPath, "utf8");
+    } catch (err) {
+      throw new Error(
+        `cannot read deploy manifest ${input.manifestPath}: ${errorMessage(err)}`,
+      );
+    }
+    const { manifest, artifact } = await verifyAndParseImutableManifest(raw);
+    return {
+      manifest,
+      creationBytecode: artifact.bytecode,
+      releaseId: manifest.releaseId,
+      source: "file",
+    };
+  }
+
+  const fetched = await fetchUnivocityReleaseManifest(input.releaseTag);
+  await verifyManifestBytesWithSidecar(
+    new TextEncoder().encode(fetched.raw),
+    fetched.sidecar,
+  );
+  const { manifest, artifact } = await verifyAndParseImutableManifest(
+    fetched.raw,
+    { expectedReleaseId: fetched.releaseTag },
+  );
+  return {
+    manifest,
+    creationBytecode: artifact.bytecode,
+    releaseId: manifest.releaseId,
+    source: "release",
+  };
+}

package/src/lib/deploy-bootstrap.ts

@@ -0,0 +1,100 @@
+/**
+ * ES256 bootstrap key resolution for `forestrie deploy` (FOR-340).
+ *
+ * The bootstrap key is the log's trust root: its public P-256 point
+ * (`x||y`, 64 bytes) is bound into the ImutableUnivocity constructor.
+ * Only the PUBLIC coordinates go on-chain, so — unlike sign-statement's
+ * `loadEs256SigningKey` (src/lib/sign-statement-key.ts), which needs the
+ * private scalar — this resolver uses `@forestrie/deploy-core`'s
+ * `resolveBootstrapKey`, which also accepts public-only SPKI PEMs.
+ */
+import { readFileSync } from "node:fs";
+import { writeOutputFile } from "./fsio.js";
+import {
+  generateEs256BootstrapKey,
+  resolveBootstrapKey,
+  type BootstrapKey,
+} from "@forestrie/deploy-core";
+import { drainOpenSslErrorQueue } from "./openssl-error-queue.js";
+import { errorMessage } from "./sign-statement-key.js";
+
+/** Resolved ES256 bootstrap key ready for constructor encoding. */
+export type ResolvedDeployBootstrap = {
+  /** deploy-core bootstrap key: `algId` (COSE -7) + 64-byte `x||y`. */
+  bootstrap: BootstrapKey;
+  /** Path the generated PKCS#8 PEM was written to (generate mode only). */
+  pemOut?: string;
+};
+
+/** Inputs already validated by `parseDeployOptions`. */
+export type DeployBootstrapInput = {
+  /** Generate a fresh keypair (requires `pemOut`). */
+  generate: boolean;
+  /** Where to persist the generated PKCS#8 PEM. */
+  pemOut?: string | undefined;
+  /** Existing key PEM path (mutually exclusive with `generate`). */
+  pemPath?: string | undefined;
+};
+
+/** Test seam: PEM persistence (real file write by default). */
+export type WritePem = (path: string, pem: string) => Promise<unknown>;
+
+/**
+ * Resolve or generate the ES256 bootstrap key.
+ *
+ * Generate mode writes the PKCS#8 private key PEM to `pemOut` BEFORE the
+ * deploy transaction is built: if the write fails, nothing is deployed
+ * with an unrecoverable trust root.
+ */
+export async function resolveDeployBootstrapKey(
+  input: DeployBootstrapInput,
+  writePem: WritePem = writeOutputFile,
+): Promise<ResolvedDeployBootstrap> {
+  if (input.generate) {
+    if (input.pemOut === undefined) {
+      throw new Error("--bootstrap-es256-generate requires --bootstrap-es256-pem-out");
+    }
+    const generated = await generateEs256BootstrapKey();
+    try {
+      await writePem(input.pemOut, generated.pem);
+    } catch (err) {
+      throw new Error(
+        `cannot write bootstrap PEM to ${input.pemOut}: ${errorMessage(err)}`,
+      );
+    }
+    const bootstrap = await resolveBootstrapKey({
+      alg: "es256",
+      x: generated.x,
+      y: generated.y,
+    });
+    return { bootstrap, pemOut: input.pemOut };
+  }
+
+  if (input.pemPath === undefined) {
+    throw new Error(
+      "es256 bootstrap needs --bootstrap-es256-generate or --bootstrap-es256-pem",
+    );
+  }
+  let pem: string;
+  try {
+    pem = readFileSync(input.pemPath, "utf8");
+  } catch (err) {
+    throw new Error(
+      `cannot read bootstrap PEM ${input.pemPath}: ${errorMessage(err)}`,
+    );
+  }
+  let bootstrap: BootstrapKey;
+  try {
+    bootstrap = await resolveBootstrapKey({ alg: "es256", pem });
+  } catch (err) {
+    // deploy-core parses via `crypto.subtle.importKey`; on bun a failed
+    // import over malformed DER leaves a stale entry on the OpenSSL error
+    // queue that would poison the next node:crypto PEM parse (FOR-343).
+    // Drain it here so the failure stays contained to this call.
+    drainOpenSslErrorQueue();
+    throw new Error(
+      `${input.pemPath}: not a usable ES256 (P-256) key PEM: ${errorMessage(err)}`,
+    );
+  }
+  return { bootstrap };
+}

package/src/lib/deploy-flow.ts

@@ -0,0 +1,184 @@
+/**
+ * Deploy transaction construction + submission flow for `forestrie
+ * deploy` (FOR-340).
+ *
+ * ES256 / EOA paved path: a DIRECT contract-creation transaction (no
+ * `to`) whose data is the ImutableUnivocity creation bytecode followed
+ * by `abi.encode(int64 bootstrapAlg, bytes bootstrapKey)` — built by
+ * deploy-core `buildImutableDeploymentData`. The deployed address comes
+ * from `receipt.contractAddress`. (The Safe/CreateCall CREATE2 path is
+ * the pre-provisioned KS256 aside and is deliberately NOT driven here.)
+ */
+import {
+  buildImutableDeploymentData,
+  type BootstrapKey,
+} from "@forestrie/deploy-core";
+import { getAddress, type Address, type Hex } from "viem";
+import { genesisLogIdFromImutableAddress } from "./deploy-genesis-log-id.js";
+
+/**
+ * Failure stage taxonomy:
+ * - `network` — the RPC endpoint could not be reached / transport error
+ * - `deploy` — the chain rejected or reverted the deploy transaction
+ */
+export type DeployFlowStage = "network" | "deploy";
+
+/** Structured deploy failure; `stage` maps onto the `--json` error codes. */
+export class DeployFlowError extends Error {
+  readonly stage: DeployFlowStage;
+  readonly detail?: string;
+  readonly txHash?: Hex;
+
+  constructor(
+    stage: DeployFlowStage,
+    message: string,
+    extra: { detail?: string; txHash?: Hex; cause?: unknown } = {},
+  ) {
+    super(message, extra.cause === undefined ? undefined : { cause: extra.cause });
+    this.name = "DeployFlowError";
+    this.stage = stage;
+    if (extra.detail !== undefined) this.detail = extra.detail;
+    if (extra.txHash !== undefined) this.txHash = extra.txHash;
+  }
+}
+
+/** Receipt subset the flow needs. */
+export type DeployReceipt = {
+  status: "success" | "reverted";
+  contractAddress: string | null;
+};
+
+/**
+ * Minimal RPC surface for the flow — the seam mocked by unit tests.
+ * The real implementation (viem over `--rpc-url`) is in
+ * `deploy-rpc.ts`.
+ */
+export type DeployRpc = {
+  /** Deployer (gas) account address derived from `--deployer-key`. */
+  readonly from: Address;
+  getChainId(): Promise<number>;
+  /** Send the contract-creation tx (`to` omitted); resolves to the tx hash. */
+  sendDeployTransaction(data: Hex): Promise<Hex>;
+  waitForReceipt(hash: Hex): Promise<DeployReceipt>;
+};
+
+export type DeployFlowInput = {
+  /** Digest-verified ImutableUnivocity creation bytecode. */
+  creationBytecode: Hex;
+  /** Resolved bootstrap key (constructor args). */
+  bootstrap: BootstrapKey;
+};
+
+export type DeployFlowResult = {
+  chainId: number;
+  /** Deployed ImutableUnivocity address (checksummed). */
+  imutableUnivocity: Address;
+  /** Root/bootstrap log UUID derived from the address. */
+  genesisLogId: string;
+  txHash: Hex;
+  from: Address;
+  /** Full creation-tx data (bytecode + encoded constructor args). */
+  deploymentData: Hex;
+};
+
+/** Creation-tx data: bytecode ++ abi.encode(int64 alg, bytes key). */
+export function buildDeploymentData(
+  creationBytecode: Hex,
+  bootstrap: BootstrapKey,
+): Hex {
+  return buildImutableDeploymentData(
+    creationBytecode,
+    bootstrap.algId,
+    bootstrap.key,
+  );
+}
+
+/** True when `err` (or a cause below it) is an RPC transport failure. */
+export function isTransportError(err: unknown): boolean {
+  for (let e: unknown = err; e instanceof Error; e = e.cause) {
+    if (
+      e.name === "HttpRequestError" ||
+      e.name === "TimeoutError" ||
+      e.name === "SocketClosedError" ||
+      e.name === "WebSocketRequestError" ||
+      (e instanceof TypeError && /fetch|connect/i.test(e.message))
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function stageFor(err: unknown, fallback: DeployFlowStage): DeployFlowStage {
+  return isTransportError(err) ? "network" : fallback;
+}
+
+function detailOf(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/** Build, submit and confirm the deploy transaction. */
+export async function runDeployFlow(
+  rpc: DeployRpc,
+  input: DeployFlowInput,
+): Promise<DeployFlowResult> {
+  let chainId: number;
+  try {
+    chainId = await rpc.getChainId();
+  } catch (err) {
+    throw new DeployFlowError("network", "cannot reach the RPC endpoint", {
+      detail: detailOf(err),
+      cause: err,
+    });
+  }
+
+  const deploymentData = buildDeploymentData(
+    input.creationBytecode,
+    input.bootstrap,
+  );
+
+  let txHash: Hex;
+  try {
+    txHash = await rpc.sendDeployTransaction(deploymentData);
+  } catch (err) {
+    throw new DeployFlowError(
+      stageFor(err, "deploy"),
+      "deploy transaction submission failed",
+      { detail: detailOf(err), cause: err },
+    );
+  }
+
+  let receipt: DeployReceipt;
+  try {
+    receipt = await rpc.waitForReceipt(txHash);
+  } catch (err) {
+    throw new DeployFlowError(
+      stageFor(err, "deploy"),
+      "deploy transaction was not confirmed",
+      { detail: detailOf(err), txHash, cause: err },
+    );
+  }
+
+  if (receipt.status !== "success") {
+    throw new DeployFlowError("deploy", "deploy transaction reverted", {
+      txHash,
+    });
+  }
+  if (receipt.contractAddress == null) {
+    throw new DeployFlowError(
+      "deploy",
+      "deploy receipt has no contractAddress (not a contract-creation tx?)",
+      { txHash },
+    );
+  }
+
+  const imutableUnivocity = getAddress(receipt.contractAddress);
+  return {
+    chainId,
+    imutableUnivocity,
+    genesisLogId: genesisLogIdFromImutableAddress(imutableUnivocity),
+    txHash,
+    from: rpc.from,
+    deploymentData,
+  };
+}

package/src/lib/deploy-genesis-log-id.ts

@@ -0,0 +1,29 @@
+/**
+ * Genesis (root/bootstrap) logId derivation for `forestrie deploy`
+ * (FOR-340).
+ *
+ * The root log's UUID is the first 16 bytes of the deployed
+ * ImutableUnivocity contract address, formatted 8-4-4-4-12 (the last 4
+ * address bytes are dropped). This is a cross-repo contract with the
+ * canopy naming scheme; the same derivation lives in univocity-tools
+ * `@univocity-tools/deployer-common` `genesisLogIdFromImutableAddress`
+ * (unpublished — mirrored here rather than depended on; graduating it
+ * into `@forestrie/deploy-core` is a univocity-tools follow-up).
+ *
+ * Test vector (shared with deployer-common):
+ * `0x1528b86fF561f617602356efdbD05908a07AA788` →
+ * `1528b86f-f561-f617-6023-56efdbd05908`.
+ */
+import { getAddress } from "viem";
+
+/** Derive the root/bootstrap log UUID from an ImutableUnivocity address. */
+export function genesisLogIdFromImutableAddress(address: string): string {
+  let normalized: string;
+  try {
+    normalized = getAddress(address);
+  } catch {
+    throw new Error(`expected 20-byte address, got ${address}`);
+  }
+  const h = normalized.slice(2).toLowerCase();
+  return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20, 32)}`;
+}

package/src/lib/deploy-rpc.ts

@@ -0,0 +1,40 @@
+/**
+ * Real `DeployRpc` implementation for `forestrie deploy` (FOR-340):
+ * viem public + wallet clients over the `--rpc-url` HTTP transport,
+ * signing locally with the funded `--deployer-key` (gas-only — the
+ * ES256 bootstrap key is the trust root, not this key).
+ *
+ * Mirrors univocity-tools deployer-common's `createRpcClients` /
+ * `executeProposal` EOA path: `sendTransaction` with `chain: null` and
+ * no `to` is a plain contract-creation transaction.
+ */
+import { createPublicClient, createWalletClient, http, type Hex } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import type { DeployRpc } from "./deploy-flow.js";
+
+/** viem-backed `DeployRpc` over a JSON-RPC HTTP endpoint. */
+export function createDeployRpc(rpcUrl: string, deployerKey: Hex): DeployRpc {
+  const account = privateKeyToAccount(deployerKey);
+  const transport = http(rpcUrl);
+  const publicClient = createPublicClient({ transport });
+  const walletClient = createWalletClient({ account, transport });
+
+  return {
+    from: account.address,
+    getChainId: () => publicClient.getChainId(),
+    sendDeployTransaction: (data) =>
+      walletClient.sendTransaction({
+        account,
+        chain: null,
+        data,
+        value: 0n,
+      }),
+    waitForReceipt: async (hash) => {
+      const receipt = await publicClient.waitForTransactionReceipt({ hash });
+      return {
+        status: receipt.status,
+        contractAddress: receipt.contractAddress ?? null,
+      };
+    },
+  };
+}

package/src/lib/deployment-record.ts

@@ -0,0 +1,65 @@
+import { readFileSync } from "node:fs";
+
+/**
+ * A `forestrie deploy --out` artifact. Single shared reader (FOR-480):
+ * `onboard-genesis`, `admin onboard-token`, and `onboard-request` all resolve
+ * their chain binding from the same file the deploy wrote, so the binding is
+ * stated exactly once per ceremony.
+ */
+export type DeploymentRecord = {
+  imutableUnivocity: string;
+  genesisLogId: string;
+  /**
+   * Bare decimal string (the file stores a JSON number; coerced here).
+   * Optional: hand-crafted two-field artifacts remain valid for
+   * onboard-genesis, which sources chainId from its own flag.
+   */
+  chainId?: string | undefined;
+  bootstrapAlg?: "es256" | "ks256" | undefined;
+  txHash?: string | undefined;
+};
+
+export function readDeploymentRecord(path: string): DeploymentRecord {
+  const parsed = JSON.parse(readFileSync(path, "utf8")) as {
+    imutableUnivocity?: string;
+    genesisLogId?: string;
+    chainId?: number | string;
+    bootstrapAlg?: string;
+    txHash?: string;
+  };
+  const imutableUnivocity = parsed.imutableUnivocity?.trim();
+  const genesisLogId = parsed.genesisLogId?.trim();
+  if (!imutableUnivocity || !genesisLogId) {
+    throw new Error(
+      `${path}: expected imutableUnivocity and genesisLogId ` +
+        "(a forestrie deploy --out artifact)",
+    );
+  }
+  const chainIdRaw = parsed.chainId;
+  const chainId =
+    typeof chainIdRaw === "number"
+      ? String(chainIdRaw)
+      : (chainIdRaw?.trim() ?? "");
+  if (chainId && !/^[0-9]+$/.test(chainId)) {
+    throw new Error(`${path}: expected a numeric chainId`);
+  }
+  const bootstrapAlg =
+    parsed.bootstrapAlg === "es256" || parsed.bootstrapAlg === "ks256"
+      ? parsed.bootstrapAlg
+      : undefined;
+  const record: DeploymentRecord = { imutableUnivocity, genesisLogId };
+  if (chainId) record.chainId = chainId;
+  if (bootstrapAlg !== undefined) record.bootstrapAlg = bootstrapAlg;
+  const txHash = parsed.txHash?.trim();
+  if (txHash) record.txHash = txHash;
+  return record;
+}
+
+/** 40-hex lowercase address body (no 0x) from a deployment address. */
+export function univocityAddrHex(record: Pick<DeploymentRecord, "imutableUnivocity">): string {
+  const hex = record.imutableUnivocity.trim().toLowerCase().replace(/^0x/, "");
+  if (!/^[0-9a-f]{40}$/.test(hex)) {
+    throw new Error("imutableUnivocity is not a 20-byte hex address");
+  }
+  return hex;
+}

package/src/lib/fsio.ts

@@ -0,0 +1,91 @@
+/**
+ * Runtime-neutral file I/O for the CLI.
+ *
+ * The CLI ships to npm as a Node program (`npx @forestrie/forestrie-cli`)
+ * as well as a Bun-compiled static binary, so nothing under `src/` may
+ * reach for `Bun.*`. These helpers are the `node:fs` equivalents of the
+ * `Bun.file` / `Bun.write` / `Bun.stdin` calls the commands used to make,
+ * with the one behaviour that was load-bearing preserved: `Bun.write`
+ * creates missing parent directories, `fs.writeFile` does not.
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+/** True for a `node:fs` "no such file or directory" rejection. */
+function isNotFound(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    (error as { code?: unknown }).code === "ENOENT"
+  );
+}
+
+/**
+ * Write `data` to `filePath`, creating parent directories first
+ * (`Bun.write` parity — several commands write into `--out` paths whose
+ * directory the caller has not made).
+ */
+export async function writeOutputFile(
+  filePath: string,
+  data: string | Uint8Array,
+): Promise<void> {
+  const dir = path.dirname(path.resolve(filePath));
+  await mkdir(dir, { recursive: true });
+  await writeFile(filePath, data);
+}
+
+/**
+ * Read `filePath` as UTF-8, raising `notFoundMessage` (not a raw ENOENT)
+ * when it does not exist — the message flags surface to the user.
+ */
+export async function readTextFile(
+  filePath: string,
+  notFoundMessage: string,
+): Promise<string> {
+  try {
+    return await readFile(filePath, "utf8");
+  } catch (error) {
+    if (isNotFound(error)) {
+      throw new Error(notFoundMessage);
+    }
+    throw error;
+  }
+}
+
+/** As `readTextFile`, but returns the raw bytes. */
+export async function readBytesFile(
+  filePath: string,
+  notFoundMessage: string,
+): Promise<Uint8Array> {
+  try {
+    const buffer = await readFile(filePath);
+    return new Uint8Array(
+      buffer.buffer,
+      buffer.byteOffset,
+      buffer.byteLength,
+    );
+  } catch (error) {
+    if (isNotFound(error)) {
+      throw new Error(notFoundMessage);
+    }
+    throw error;
+  }
+}
+
+/** Drain stdin to bytes (`Bun.stdin.arrayBuffer()` equivalent). */
+export async function readStdinBytes(): Promise<Uint8Array> {
+  const chunks: Uint8Array[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(
+      typeof chunk === "string" ? Buffer.from(chunk) : new Uint8Array(chunk),
+    );
+  }
+  const total = chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0);
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return out;
+}

package/src/lib/grant-flags-local.ts

@@ -0,0 +1,19 @@
+/**
+ * Local bridge until `@forestrie/grant-builder` publishes `dataLogExtendFlags()`.
+ *
+ * The published grant-builder ships `dataLogCreateExtendFlags()` (byte 3 =
+ * `GF_CREATE|GF_EXTEND` = 0x03) but not the extend-only shape a statement
+ * *writer* grant needs. Constructing the 8-byte wire bitmap here is a plain
+ * Uint8Array literal, NOT copied package logic — see ADR-0052 / plan-2607-21.
+ * Drop this module once grant-builder exports `dataLogExtendFlags()`.
+ */
+
+/**
+ * Extend-only data-log writer grant flags: byte 3 = `GF_EXTEND` (0x02, no
+ * `GF_CREATE`), byte 7 = `GF_DATA_LOG` (0x02). Mirrors grant-builder's byte
+ * layout (grant-flags.ts): byte 3 carries the capability bits, byte 7 the
+ * log-class bits.
+ */
+export function dataLogExtendFlags(): Uint8Array {
+  return Uint8Array.from([0, 0, 0, 0x02, 0, 0, 0, 0x02]);
+}