@forestrie/forestrie-cli 0.8.0

package/src/main/complete-grant.ts

@@ -0,0 +1,265 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import type { Out } from "@forestrie/cli-kit/reporting";
+import type { CompleteGrantOptions } from "../options/complete-grant.js";
+import {
+  CompleteGrantFailure,
+  deriveCompletedGrant,
+  type CompletedGrant,
+  type CompleteGrantReason,
+  type CompleteGrantStage,
+} from "../lib/complete-grant-derive.js";
+
+/**
+ * FOR-344: self-create the `Authorization: Forestrie-Grant` header content
+ * from a checkpoint (+ local massif) — grants are derivable from log data,
+ * not operator-issued. The offline twin of `register-grant`'s completion:
+ * locate the grant's leaf in the massif, rebuild its inclusion receipt against
+ * the checkpoint's pre-signed peak, and attach receipt + idtimestamp with no
+ * re-signing.
+ */
+
+/** Where an operational error broke the run. */
+export type CompleteGrantErrorStage = "input" | CompleteGrantStage;
+
+/** `--json` operational-error shape — stable stage + reason tokens. */
+export type CompleteGrantErrorReport = {
+  error:
+    | "complete_grant_input_failed"
+    | "complete_grant_decode_failed"
+    | "complete_grant_locate_failed"
+    | "complete_grant_parse_failed"
+    | "complete_grant_derive_failed";
+  command: "complete-grant";
+  stage: CompleteGrantErrorStage;
+  reason?: CompleteGrantReason;
+  message: string;
+};
+
+/** Structured `--json` success report — the shape is a contract. */
+export type CompleteGrantReport = {
+  command: "complete-grant";
+  status: "completed";
+  entryId: string;
+  mmrIndex: string;
+  idtimestamp: string;
+  idtimestampSource: CompletedGrant["idtimestampSource"];
+  proof: {
+    length: number;
+    peakIndex: number;
+    peakCount: number;
+  };
+  sealedSize: string;
+  certCopied: boolean;
+  receiptBytes: number;
+  /** Present when `--out-b64` was given. */
+  outB64?: string;
+  /** Completed grant base64 — only when not written to `--out-b64`. */
+  grantB64?: string;
+};
+
+const ERROR_CODES: Record<
+  CompleteGrantErrorStage,
+  CompleteGrantErrorReport["error"]
+> = {
+  input: "complete_grant_input_failed",
+  decode: "complete_grant_decode_failed",
+  locate: "complete_grant_locate_failed",
+  parse: "complete_grant_parse_failed",
+  derive: "complete_grant_derive_failed",
+};
+
+const IDTIMESTAMP_HEX_RE = /^[0-9a-f]{16}$/i;
+
+/** An operational error that carries the stage but no lib reason. */
+class InputError extends Error {}
+
+function readBytes(path: string, flag: string): Uint8Array {
+  try {
+    return new Uint8Array(readFileSync(path));
+  } catch (err) {
+    throw new InputError(
+      `cannot read ${flag} '${path}': ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}
+
+function hexToBe8(hex: string): Uint8Array {
+  const out = new Uint8Array(8);
+  for (let i = 0; i < 8; i++) {
+    out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return out;
+}
+
+/**
+ * Resolve `--idtimestamp <hex|path>` to 8 big-endian bytes: a bare 16-char hex
+ * value, or a file holding either the 8 raw bytes or a hex string.
+ */
+function parseIdtimestampOption(value: string): Uint8Array {
+  const trimmed = value.trim();
+  if (IDTIMESTAMP_HEX_RE.test(trimmed)) return hexToBe8(trimmed);
+  let raw: Uint8Array;
+  try {
+    raw = new Uint8Array(readFileSync(value));
+  } catch (err) {
+    throw new InputError(
+      `--idtimestamp is neither 16 hex chars nor a readable file '${value}': ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+  }
+  if (raw.length === 8) return raw;
+  const text = new TextDecoder().decode(raw).trim();
+  if (IDTIMESTAMP_HEX_RE.test(text)) return hexToBe8(text);
+  throw new InputError(
+    `--idtimestamp file '${value}' must be 8 raw bytes or 16 hex chars`,
+  );
+}
+
+/** Structured envelope under `--json`; one clean line on stderr otherwise. */
+function reportRunError(
+  out: Out,
+  options: CompleteGrantOptions,
+  stage: CompleteGrantErrorStage,
+  err: unknown,
+): void {
+  const message = err instanceof Error ? err.message : String(err);
+  const reason = err instanceof CompleteGrantFailure ? err.reason : undefined;
+  if (options.json) {
+    const report: CompleteGrantErrorReport = {
+      error: ERROR_CODES[stage],
+      command: "complete-grant",
+      stage,
+      ...(reason !== undefined ? { reason } : {}),
+      message,
+    };
+    out.out(JSON.stringify(report, null, 2));
+  } else {
+    out.warn("forestrie complete-grant: %s: %s", stage, message);
+  }
+  process.exitCode = 1;
+}
+
+export async function runCompleteGrant(
+  out: Out,
+  options: CompleteGrantOptions,
+): Promise<void> {
+  // 1. Inputs. The massif is required — it is what carries the leaf we recover
+  //    the mmrIndex and idtimestamp from.
+  let grantBase64: string;
+  let massifBytes: Uint8Array;
+  let checkpointBytes: Uint8Array;
+  let idtimestampOverride: Uint8Array | undefined;
+  try {
+    if (options.massif === undefined) {
+      throw new InputError(
+        "--massif is required: the grant's leaf (mmrIndex + idtimestamp) is " +
+          "recovered from the local massif blob",
+      );
+    }
+    grantBase64 = readFileSync(options.grant, "utf8").trim();
+    massifBytes = readBytes(options.massif, "--massif");
+    checkpointBytes = readBytes(options.checkpoint, "--checkpoint");
+    idtimestampOverride =
+      options.idtimestamp !== undefined
+        ? parseIdtimestampOption(options.idtimestamp)
+        : undefined;
+  } catch (err) {
+    if (err instanceof InputError) {
+      reportRunError(out, options, "input", err);
+      return;
+    }
+    reportRunError(
+      out,
+      options,
+      "input",
+      new InputError(
+        `cannot read --grant '${options.grant}': ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      ),
+    );
+    return;
+  }
+
+  // 2. Derive the completed grant.
+  let completed: CompletedGrant;
+  try {
+    completed = await deriveCompletedGrant({
+      grantBase64,
+      massifBytes,
+      checkpointBytes,
+      idtimestampOverride,
+    });
+  } catch (err) {
+    const stage = err instanceof CompleteGrantFailure ? err.stage : "derive";
+    reportRunError(out, options, stage, err);
+    return;
+  }
+
+  // 3. Emit.
+  try {
+    if (options.outB64 !== undefined) {
+      writeFileSync(options.outB64, completed.completedBase64);
+    }
+  } catch (err) {
+    reportRunError(out, options, "input", new InputError(
+      `cannot write --out-b64 '${options.outB64}': ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    ));
+    return;
+  }
+
+  const idtimestampHex = completed.entryIdHex.slice(0, 16);
+  if (options.json) {
+    const report: CompleteGrantReport = {
+      command: "complete-grant",
+      status: "completed",
+      entryId: completed.entryIdHex,
+      mmrIndex: completed.mmrIndex.toString(10),
+      idtimestamp: idtimestampHex,
+      idtimestampSource: completed.idtimestampSource,
+      proof: {
+        length: completed.proofLength,
+        peakIndex: completed.peakIndex,
+        peakCount: completed.peakCount,
+      },
+      sealedSize: completed.sealedSize.toString(10),
+      certCopied: completed.certCopied,
+      receiptBytes: completed.receiptBytes,
+      ...(options.outB64 !== undefined
+        ? { outB64: options.outB64 }
+        : { grantB64: completed.completedBase64 }),
+    };
+    out.out(JSON.stringify(report, null, 2));
+    return;
+  }
+
+  // Human mode: without --out-b64 the completed grant base64 is the pipeable
+  // product on stdout; the summary narrates on stderr (mirrors register-grant).
+  const emit = options.outB64 === undefined ? out.print : out.out;
+  emit("complete-grant: leaf       — mmrIndex %s (recovered from massif)", completed.mmrIndex.toString(10));
+  emit(
+    "complete-grant: entry id   — %s (idtimestamp from %s)",
+    completed.entryIdHex,
+    completed.idtimestampSource,
+  );
+  emit(
+    "complete-grant: proof      — %d node(s) to peak %d/%d",
+    completed.proofLength,
+    completed.peakIndex + 1,
+    completed.peakCount,
+  );
+  emit(
+    "complete-grant: checkpoint — sealed size %s, delegation cert copied: %s",
+    completed.sealedSize.toString(10),
+    completed.certCopied ? "yes" : "no",
+  );
+  emit("complete-grant: receipt    — %d bytes attached (header 396)", completed.receiptBytes);
+  if (options.outB64 !== undefined) {
+    emit("complete-grant: wrote completed grant (base64) to %s", options.outB64);
+  } else {
+    out.out("%s", completed.completedBase64);
+  }
+}

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

@@ -0,0 +1,83 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import type { Out } from "@forestrie/cli-kit/reporting";
+import type { CreateConsistencyProofOptions } from "../options/create-consistency-proof.js";
+import {
+  buildConsistencyProofArtifact,
+  encodeConsistencyProofArtifact,
+  multiMassifNodeGetter,
+} from "../lib/consistency-proof.js";
+
+/** `--json` success shape on stdout — stable for demo scripting. */
+export type CreateConsistencyProofReport = {
+  command: "create-consistency-proof";
+  fromSize: string;
+  toSize: string;
+  basePeakCount: number;
+  pathCount: number;
+  out: string;
+};
+
+export type CreateConsistencyProofErrorReport = {
+  error: "create_consistency_proof_failed";
+  command: "create-consistency-proof";
+  message: string;
+};
+
+/**
+ * Build the portable top-up artifact from massif tiles (FOR-368 Phase 3):
+ * base accumulator at `--from-size` plus one inclusion path per base peak
+ * proven at `--to-size`, self-verified before writing. Consumers verify
+ * tile-free with `verify --known-accumulator ... --consistency-proof`.
+ */
+export async function runCreateConsistencyProof(
+  out: Out,
+  options: CreateConsistencyProofOptions,
+): Promise<void> {
+  try {
+    const blobs = options.massifs.map(
+      (f) => new Uint8Array(readFileSync(f)),
+    );
+    const artifact = await buildConsistencyProofArtifact({
+      get: multiMassifNodeGetter(blobs),
+      fromSize: options.fromSize,
+      toSize: options.toSize,
+    });
+    writeFileSync(options.out, encodeConsistencyProofArtifact(artifact));
+
+    if (options.json) {
+      const report: CreateConsistencyProofReport = {
+        command: "create-consistency-proof",
+        fromSize: artifact.fromSize.toString(),
+        toSize: artifact.toSize.toString(),
+        basePeakCount: artifact.accumulatorFrom.length,
+        pathCount: artifact.paths.length,
+        out: options.out,
+      };
+      out.out(JSON.stringify(report, null, 2));
+    } else {
+      out.print(
+        "create-consistency-proof: proved %s -> %s (%d base peaks; self-verified)",
+        artifact.fromSize.toString(),
+        artifact.toSize.toString(),
+        artifact.accumulatorFrom.length,
+      );
+      out.out(
+        `wrote consistency proof: ${options.out} (verify with --known-accumulator at size ${artifact.toSize} plus --consistency-proof)`,
+      );
+    }
+    process.exitCode = 0;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (options.json) {
+      const report: CreateConsistencyProofErrorReport = {
+        error: "create_consistency_proof_failed",
+        command: "create-consistency-proof",
+        message,
+      };
+      out.out(JSON.stringify(report, null, 2));
+    } else {
+      out.warn("forestrie create-consistency-proof: %s", message);
+    }
+    process.exitCode = 1;
+  }
+}

package/src/main/create-log.ts

@@ -0,0 +1,347 @@
+import type { Out } from "@forestrie/cli-kit/reporting";
+import { readTextFile, writeOutputFile } from "../lib/fsio.js";
+import type { CreateLogOptions } from "../options/create-log.js";
+import {
+  RegisterGrantBuildError,
+  buildCreateLogGrant,
+  type BuiltCreateLogGrant,
+} from "../lib/create-log-build.js";
+import { completeGrantBase64 } from "../lib/register-grant-complete.js";
+import {
+  PrepareLogError,
+  prepareChildLog,
+} from "../lib/create-log-prepare.js";
+import {
+  RegisterFlowError,
+  runRegisterGrantFlow,
+  type RegisterGrantFlowDeps,
+  type RegisterGrantFlowResult,
+} from "../lib/register-grant-flow.js";
+
+/**
+ * FOR-390 / ADR-0052: create a log and set its owner (K(L)). Build the signed
+ * create grant (`@forestrie/grant-builder` ES256 profile) with
+ * `GF_CREATE|GF_EXTEND` flags, POST it to `/register/{bootstrap}/grants` with
+ * the parent grant as CBOR body evidence, follow the 303 to the receipt, then
+ * emit the COMPLETED grant. The flow is identical to register-grant's; only the
+ * grant shape and the reporter labels differ (newLog / owner).
+ */
+
+/** `--json` success shape. */
+export type CreateLogReport = {
+  command: "create-log";
+  status: "receipt";
+  /** Parent/auth log the create grant was sequenced into. */
+  ownerLog: string;
+  /** The log that was created. */
+  newLog: string;
+  /** The new log owner (ES256 x||y, hex) committed as grantData. */
+  ownerHex: string;
+  entryId: string;
+  statusUrl: string;
+  receiptUrl: string;
+  receiptBytes: number;
+  /** Present when `--out-b64` was given. */
+  outB64?: string;
+  /** Completed grant base64 — only when not written to `--out-b64`. */
+  grantB64?: string;
+};
+
+/** `--json` failure shape (problem = CBOR problem-details passthrough). */
+export type CreateLogErrorReport = {
+  error:
+    | "key_read_failed"
+    | "grant_build_failed"
+    | "registration_failed"
+    | "status_failed"
+    | "receipt_failed"
+    | "network_failed"
+    | "timeout";
+  command: "create-log";
+  message: string;
+  httpStatus?: number;
+  detail?: string;
+  problem?: Record<string, unknown>;
+  statusUrl?: string;
+  receiptUrl?: string;
+};
+
+/** Test seam: effects injected by the create-log tests (real by default). */
+export type CreateLogRunDeps = RegisterGrantFlowDeps;
+
+const FLOW_ERROR_CODES = {
+  register: "registration_failed",
+  status: "status_failed",
+  receipt: "receipt_failed",
+  network: "network_failed",
+  timeout: "timeout",
+} as const;
+
+async function readPemFile(path: string, flag: string): Promise<string> {
+  return readTextFile(path, `${flag} key file not found: ${path}`);
+}
+
+function reportError(
+  out: Out,
+  options: CreateLogOptions,
+  report: CreateLogErrorReport,
+): void {
+  if (options.json) {
+    out.out(JSON.stringify(report, null, 2));
+  } else {
+    out.warn("forestrie create-log: %s", report.message);
+    if (report.detail !== undefined && !report.message.includes(report.detail)) {
+      out.warn("  detail: %s", report.detail);
+    }
+    if (report.problem !== undefined) {
+      out.log("problem details: %s", JSON.stringify(report.problem));
+    }
+    if (report.statusUrl !== undefined) {
+      out.warn("  statusUrl: %s", report.statusUrl);
+    }
+    if (report.receiptUrl !== undefined) {
+      out.warn("  receiptUrl: %s", report.receiptUrl);
+    }
+  }
+  process.exitCode = 1;
+}
+
+function flowErrorReport(err: RegisterFlowError): CreateLogErrorReport {
+  const report: CreateLogErrorReport = {
+    error: FLOW_ERROR_CODES[err.stage],
+    command: "create-log",
+    message: err.message,
+  };
+  if (err.httpStatus !== undefined) report.httpStatus = err.httpStatus;
+  if (err.detail !== undefined) report.detail = err.detail;
+  if (err.problem !== undefined) report.problem = err.problem;
+  if (err.statusUrl !== undefined) report.statusUrl = err.statusUrl;
+  if (err.receiptUrl !== undefined) report.receiptUrl = err.receiptUrl;
+  return report;
+}
+
+async function reportCompletedGrant(
+  out: Out,
+  options: CreateLogOptions,
+  built: BuiltCreateLogGrant,
+  result: RegisterGrantFlowResult,
+  completedB64: string,
+): Promise<void> {
+  const ownerHex = Buffer.from(built.grantData).toString("hex");
+  if (options.outB64 !== undefined) {
+    await writeOutputFile(options.outB64, completedB64);
+  }
+  if (options.json) {
+    const report: CreateLogReport = {
+      command: "create-log",
+      status: "receipt",
+      ownerLog: options.ownerLog,
+      newLog: options.newLog,
+      ownerHex,
+      entryId: result.entryIdHex,
+      statusUrl: result.statusUrl,
+      receiptUrl: result.receiptUrl,
+      receiptBytes: result.receipt.length,
+    };
+    if (options.outB64 !== undefined) {
+      report.outB64 = options.outB64;
+    } else {
+      report.grantB64 = completedB64;
+    }
+    out.out(JSON.stringify(report, null, 2));
+    return;
+  }
+  // Human mode: without --out-b64 the completed grant base64 is the pipeable
+  // product on stdout; the summary narrates on stderr. With --out-b64 the
+  // summary is the stdout product (mirrors register / register-grant).
+  const emit = options.outB64 === undefined ? out.print : out.out;
+  emit("ownerLog: %s (grant leaf)", options.ownerLog);
+  emit("newLog: %s (created)", options.newLog);
+  emit("owner: %s", ownerHex);
+  emit("entryId: %s", result.entryIdHex);
+  emit("statusUrl: %s", result.statusUrl);
+  emit("receiptUrl: %s", result.receiptUrl);
+  if (options.outB64 !== undefined) {
+    emit("wrote completed grant (base64) to %s", options.outB64);
+  } else {
+    out.out("%s", completedB64);
+  }
+}
+
+export async function runCreateLog(
+  out: Out,
+  options: CreateLogOptions,
+  deps: CreateLogRunDeps = {},
+): Promise<void> {
+  // 1. Key material.
+  let signWithPem: string;
+  let signerPem: string | undefined;
+  try {
+    signWithPem = await readPemFile(options.signWith, "--sign-with");
+    signerPem =
+      options.signerPem !== undefined
+        ? await readPemFile(options.signerPem, "--signer-pem")
+        : undefined;
+  } catch (err) {
+    reportError(out, options, {
+      error: "key_read_failed",
+      command: "create-log",
+      message: err instanceof Error ? err.message : String(err),
+    });
+    return;
+  }
+
+  // 2. Build + sign the create grant transparent statement.
+  let built: BuiltCreateLogGrant;
+  try {
+    built = buildCreateLogGrant({
+      newLog: options.newLog,
+      ownerLog: options.ownerLog,
+      signWithPem,
+      signerPem,
+      selfReferential: options.selfReferential,
+      authLog: options.authLog,
+      childPaymentRequired: options.childPaymentRequired,
+    });
+  } catch (err) {
+    if (err instanceof RegisterGrantBuildError) {
+      reportError(out, options, {
+        error: "grant_build_failed",
+        command: "create-log",
+        message: err.message,
+      });
+      return;
+    }
+    throw err;
+  }
+
+  // 2b. --prepare: pre-register the child public root with the coordinator under
+  // parent authority (ADR-0053), WITHOUT sequencing. Emits the create grant so a
+  // later plain `create-log` sequences it. Enables `delegate` before the log
+  // exists.
+  if (options.prepare) {
+    if (options.selfReferential) {
+      reportError(out, options, {
+        error: "grant_build_failed",
+        command: "create-log",
+        message:
+          "--prepare is for child logs; the root/bootstrap log is onboarded via genesis, not prepare",
+      });
+      return;
+    }
+    try {
+      const prepared = await prepareChildLog(
+        {
+          baseUrl: options.baseUrl,
+          childLogId: options.newLog,
+          grantBase64: built.grantBase64,
+        },
+        { fetchImpl: deps.fetchImpl },
+      );
+      if (options.outB64 !== undefined) {
+        await writeOutputFile(options.outB64, built.grantBase64);
+      }
+      if (options.json) {
+        const report = {
+          command: "create-log" as const,
+          status: "prepared" as const,
+          ownerLog: options.ownerLog,
+          newLog: options.newLog,
+          publicRoot: prepared.publicRoot,
+          ...(prepared.webhook !== undefined
+            ? { webhook: prepared.webhook }
+            : {}),
+          ...(options.outB64 !== undefined ? { outB64: options.outB64 } : {}),
+          grantB64: options.outB64 === undefined ? built.grantBase64 : undefined,
+        };
+        out.out(JSON.stringify(report, null, 2));
+        return;
+      }
+      const emit = options.outB64 === undefined ? out.print : out.out;
+      emit("prepared child log %s (owner %s)", options.newLog, options.ownerLog);
+      emit(
+        "coordinator: public-root %s%s",
+        prepared.publicRoot,
+        prepared.webhook !== undefined ? `, webhook ${prepared.webhook}` : "",
+      );
+      emit("owner: %s", Buffer.from(built.grantData).toString("hex"));
+      if (options.outB64 !== undefined) {
+        emit("wrote create grant (base64) to %s", options.outB64);
+      } else {
+        out.out("%s", built.grantBase64);
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      reportError(out, options, {
+        error: "registration_failed",
+        command: "create-log",
+        message,
+        ...(err instanceof PrepareLogError && err.httpStatus !== undefined
+          ? { httpStatus: err.httpStatus }
+          : {}),
+      });
+    }
+    return;
+  }
+
+  const flowDeps: RegisterGrantFlowDeps = {
+    ...deps,
+    onProgress:
+      deps.onProgress ??
+      ((progress) => {
+        switch (progress.phase) {
+          case "registered":
+            out.print("create grant registered; status: %s", progress.statusUrl);
+            break;
+          case "status-pending":
+            out.log(
+              "sequencing pending (attempt %d): %s",
+              progress.attempt,
+              progress.statusUrl,
+            );
+            break;
+          case "receipt-located":
+            out.print(
+              "sequenced as entry %s; receipt: %s",
+              progress.entryIdHex,
+              progress.receiptUrl,
+            );
+            break;
+          case "receipt-pending":
+            out.log(
+              "receipt objects still writing (attempt %d): %s",
+              progress.attempt,
+              progress.receiptUrl,
+            );
+            break;
+        }
+      }),
+  };
+
+  // 3. Register the create grant, follow to the receipt, complete the grant.
+  try {
+    const result = await runRegisterGrantFlow(
+      {
+        baseUrl: options.baseUrl,
+        bootstrapLogId: options.bootstrapLog,
+        grantBase64: built.grantBase64,
+        parentGrantBase64: options.parentGrantB64,
+        timeoutMs: options.timeoutMs,
+        pollIntervalMs: options.pollIntervalMs,
+      },
+      flowDeps,
+    );
+    const completedB64 = completeGrantBase64(
+      built.grantBase64,
+      result.receipt,
+      result.entryIdHex,
+    );
+    await reportCompletedGrant(out, options, built, result, completedB64);
+  } catch (err) {
+    if (err instanceof RegisterFlowError) {
+      reportError(out, options, flowErrorReport(err));
+      return;
+    }
+    throw err;
+  }
+}