@forestrie/forestrie-cli 0.8.0

package/src/main/register-grant.ts

@@ -0,0 +1,270 @@
+import type { Out } from "@forestrie/cli-kit/reporting";
+import { readTextFile, writeOutputFile } from "../lib/fsio.js";
+import type { RegisterGrantOptions } from "../options/register-grant.js";
+import {
+  RegisterGrantBuildError,
+  buildGrantStatement,
+  type BuiltGrantStatement,
+} from "../lib/register-grant-build.js";
+import { completeGrantBase64 } from "../lib/register-grant-complete.js";
+import {
+  RegisterFlowError,
+  runRegisterGrantFlow,
+  type RegisterGrantFlowDeps,
+  type RegisterGrantFlowResult,
+} from "../lib/register-grant-flow.js";
+
+/**
+ * FOR-343: register a grant statement authorizing use of a child/data log.
+ * One grant binds exactly ONE signer; several signers on one data log =
+ * several grants naming that log, all sequenced into the OWNER (auth)
+ * log. Build the signed grant (`@forestrie/grant-builder` ES256 profile),
+ * POST it to `/register/{bootstrap}/grants` with the parent grant as CBOR
+ * body evidence (`@forestrie/scrapi-client`), follow the 303 to the
+ * receipt, then emit the COMPLETED grant (receipt + idtimestamp attached)
+ * — the bearer credential `forestrie register` consumes.
+ */
+
+/** `--json` success shape. */
+export type RegisterGrantReport = {
+  command: "register-grant";
+  status: "receipt";
+  /** Owner (auth) log the grant leaf was sequenced into. */
+  ownerLog: string;
+  /** Target child/data log the grant authorizes. */
+  dataLog: string;
+  /** The ONE authorized signer (ES256 x||y, hex) committed as grantData. */
+  grantDataHex: 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 RegisterGrantErrorReport = {
+  error:
+    | "key_read_failed"
+    | "grant_build_failed"
+    | "registration_failed"
+    | "status_failed"
+    | "receipt_failed"
+    | "network_failed"
+    | "timeout";
+  command: "register-grant";
+  message: string;
+  httpStatus?: number;
+  detail?: string;
+  problem?: Record<string, unknown>;
+  statusUrl?: string;
+  receiptUrl?: string;
+};
+
+/** Test seam: effects injected by the register-grant tests (real by default). */
+export type RegisterGrantRunDeps = 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: RegisterGrantOptions,
+  report: RegisterGrantErrorReport,
+): void {
+  if (options.json) {
+    out.out(JSON.stringify(report, null, 2));
+  } else {
+    out.warn("forestrie register-grant: %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): RegisterGrantErrorReport {
+  const report: RegisterGrantErrorReport = {
+    error: FLOW_ERROR_CODES[err.stage],
+    command: "register-grant",
+    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: RegisterGrantOptions,
+  built: BuiltGrantStatement,
+  result: RegisterGrantFlowResult,
+  completedB64: string,
+): Promise<void> {
+  const grantDataHex = Buffer.from(built.grantData).toString("hex");
+  if (options.outB64 !== undefined) {
+    await writeOutputFile(options.outB64, completedB64);
+  }
+  if (options.json) {
+    const report: RegisterGrantReport = {
+      command: "register-grant",
+      status: "receipt",
+      ownerLog: options.ownerLog,
+      dataLog: options.dataLog,
+      grantDataHex,
+      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).
+  const emit = options.outB64 === undefined ? out.print : out.out;
+  emit("ownerLog: %s (grant leaf)", options.ownerLog);
+  emit("dataLog: %s (authorized)", options.dataLog);
+  emit("signer: %s", grantDataHex);
+  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 runRegisterGrant(
+  out: Out,
+  options: RegisterGrantOptions,
+  deps: RegisterGrantRunDeps = {},
+): Promise<void> {
+  // 1. Key material.
+  let signWithPem: string;
+  let signerPem: string;
+  try {
+    signWithPem = await readPemFile(options.signWith, "--sign-with");
+    signerPem = await readPemFile(options.signerPem, "--signer-pem");
+  } catch (err) {
+    reportError(out, options, {
+      error: "key_read_failed",
+      command: "register-grant",
+      message: err instanceof Error ? err.message : String(err),
+    });
+    return;
+  }
+
+  // 2. Build + sign the grant transparent statement (one grant, ONE signer).
+  let built: BuiltGrantStatement;
+  try {
+    built = buildGrantStatement({
+      targetLog: options.dataLog,
+      ownerLog: options.ownerLog,
+      signWithPem,
+      signerPem,
+    });
+  } catch (err) {
+    if (err instanceof RegisterGrantBuildError) {
+      reportError(out, options, {
+        error: "grant_build_failed",
+        command: "register-grant",
+        message: err.message,
+      });
+      return;
+    }
+    throw err;
+  }
+
+  const flowDeps: RegisterGrantFlowDeps = {
+    ...deps,
+    onProgress:
+      deps.onProgress ??
+      ((progress) => {
+        switch (progress.phase) {
+          case "registered":
+            out.print("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 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;
+  }
+}

package/src/main/register.ts

@@ -0,0 +1,243 @@
+import type { Out } from "@forestrie/cli-kit/reporting";
+import {
+  readBytesFile,
+  readStdinBytes,
+  writeOutputFile,
+} from "../lib/fsio.js";
+import type { RegisterOptions } from "../options/register.js";
+import {
+  RegisterFlowError,
+  runRegisterFlow,
+  type RegisterFlowDeps,
+  type RegisterFlowResult,
+} from "../lib/register-flow.js";
+
+/**
+ * FOR-342: register a signed statement via SCRAPI
+ * (`@forestrie/scrapi-client`) — POST with the `Authorization:
+ * Forestrie-Grant` header (opaque bearer at this step), follow the 303,
+ * poll, download the receipt. Any SCRAPI client, plain COSE Sign1.
+ */
+
+/** `--json` success shape. */
+export type RegisterReport = {
+  command: "register";
+  status: "receipt";
+  entryId: string;
+  statusUrl: string;
+  receiptUrl: string;
+  receiptBytes: number;
+  /** Present when `--out` was given. */
+  out?: string;
+  /** Receipt bytes, base64 — only when not written to `--out`. */
+  receiptB64?: string;
+};
+
+/** `--json` failure shape (problem = CBOR problem-details passthrough). */
+export type RegisterErrorReport = {
+  error:
+    | "statement_read_failed"
+    | "registration_failed"
+    | "status_failed"
+    | "receipt_failed"
+    | "network_failed"
+    | "timeout";
+  command: "register";
+  message: string;
+  httpStatus?: number;
+  detail?: string;
+  problem?: Record<string, unknown>;
+  statusUrl?: string;
+  receiptUrl?: string;
+};
+
+/** Test seam: effects injected by the register tests (real by default). */
+export type RegisterRunDeps = RegisterFlowDeps & {
+  /** Statement source when `--statement` is `-`/absent (default: stdin). */
+  readStdin?: () => Promise<Uint8Array>;
+};
+
+const FLOW_ERROR_CODES = {
+  register: "registration_failed",
+  status: "status_failed",
+  receipt: "receipt_failed",
+  network: "network_failed",
+  timeout: "timeout",
+} as const;
+
+async function readStatementBytes(
+  statement: string | undefined,
+  readStdin: () => Promise<Uint8Array>,
+): Promise<Uint8Array> {
+  if (statement === undefined || statement === "-") {
+    return readStdin();
+  }
+  return readBytesFile(statement, `statement file not found: ${statement}`);
+}
+
+function reportError(
+  out: Out,
+  options: RegisterOptions,
+  report: RegisterErrorReport,
+): void {
+  if (options.json) {
+    out.out(JSON.stringify(report, null, 2));
+  } else {
+    out.warn("forestrie register: %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): RegisterErrorReport {
+  const report: RegisterErrorReport = {
+    error: FLOW_ERROR_CODES[err.stage],
+    command: "register",
+    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 reportReceipt(
+  out: Out,
+  options: RegisterOptions,
+  result: RegisterFlowResult,
+): Promise<void> {
+  if (options.out !== undefined) {
+    await writeOutputFile(options.out, result.receipt);
+  }
+  if (options.json) {
+    const report: RegisterReport = {
+      command: "register",
+      status: "receipt",
+      entryId: result.entryIdHex,
+      statusUrl: result.statusUrl,
+      receiptUrl: result.receiptUrl,
+      receiptBytes: result.receipt.length,
+    };
+    if (options.out !== undefined) {
+      report.out = options.out;
+    } else {
+      report.receiptB64 = Buffer.from(result.receipt).toString("base64");
+    }
+    out.out(JSON.stringify(report, null, 2));
+    return;
+  }
+  // Human mode: receipt to --out keeps stdout clean; without --out the
+  // summary is the pipeable product.
+  const emit = options.out !== undefined ? out.print : out.out;
+  emit("entryId: %s", result.entryIdHex);
+  emit("statusUrl: %s", result.statusUrl);
+  emit("receiptUrl: %s", result.receiptUrl);
+  if (options.out !== undefined) {
+    emit(
+      "wrote receipt (%d bytes) to %s",
+      result.receipt.length,
+      options.out,
+    );
+  } else {
+    emit(
+      "receipt: %d bytes (pass --out <path> to save the CBOR)",
+      result.receipt.length,
+    );
+  }
+}
+
+export async function runRegister(
+  out: Out,
+  options: RegisterOptions,
+  deps: RegisterRunDeps = {},
+): Promise<void> {
+  const readStdin = deps.readStdin ?? readStdinBytes;
+
+  let statement: Uint8Array;
+  try {
+    statement = await readStatementBytes(options.statement, readStdin);
+  } catch (err) {
+    reportError(out, options, {
+      error: "statement_read_failed",
+      command: "register",
+      message: err instanceof Error ? err.message : String(err),
+    });
+    return;
+  }
+  if (statement.length === 0) {
+    reportError(out, options, {
+      error: "statement_read_failed",
+      command: "register",
+      message: "signed statement is empty",
+    });
+    return;
+  }
+
+  const flowDeps: RegisterFlowDeps = {
+    ...deps,
+    onProgress:
+      deps.onProgress ??
+      ((progress) => {
+        switch (progress.phase) {
+          case "registered":
+            out.print("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;
+        }
+      }),
+  };
+
+  try {
+    const result = await runRegisterFlow(
+      {
+        baseUrl: options.baseUrl,
+        logId: options.logId,
+        grantB64: options.grantB64,
+        statement,
+        timeoutMs: options.timeoutMs,
+        pollIntervalMs: options.pollIntervalMs,
+      },
+      flowDeps,
+    );
+    await reportReceipt(out, options, result);
+  } catch (err) {
+    if (err instanceof RegisterFlowError) {
+      reportError(out, options, flowErrorReport(err));
+      return;
+    }
+    throw err;
+  }
+}

package/src/main/sign-statement.ts

@@ -0,0 +1,168 @@
+import { writeFileSync } from "node:fs";
+import type { Out } from "@forestrie/cli-kit/reporting";
+import type { SignStatementOptions } from "../options/sign-statement.js";
+import {
+  buildSignedStatement,
+  readPayloadBytes,
+  type SignedStatement,
+} from "../lib/sign-statement-build.js";
+import {
+  errorMessage,
+  loadEs256SigningKey,
+} from "../lib/sign-statement-key.js";
+
+/** Structured `--json` success report — the shape is a contract. */
+export type SignStatementReport = {
+  command: "sign-statement";
+  /** COSE algorithm used for the signature. */
+  alg: "ES256";
+  /** Signer binding, hex: first 32 bytes of `x||y`. */
+  kid: string;
+  /** Payload size in bytes. */
+  payloadBytes: number;
+  /** COSE content type header value (label 3, protected). */
+  contentType: string;
+  /** Issuer (CWT claim 1, protected label 15). */
+  iss: string;
+  /** Subject (CWT claim 2, protected label 15). */
+  sub: string;
+  /** Issued-at (CWT claim 6), when `--iat` was given. */
+  iat?: number;
+  /** Signed statement (COSE Sign1 CBOR) size in bytes. */
+  statementBytes: number;
+  /** Output path, when `--out` was given. */
+  out?: string;
+  /** Base64 COSE Sign1 bytes, when no `--out` (JSON owns stdout). */
+  statementB64?: string;
+};
+
+/** Structured `--json` error report. */
+export type SignStatementError = {
+  error: "sign_statement_failed";
+  command: "sign-statement";
+  message: string;
+};
+
+/**
+ * FOR-341: build a plain COSE Sign1 signed statement
+ * (`@forestrie/encoding`). `kid` = first 32 bytes of x||y under ES256;
+ * alg (label 1), content type (label 3), and kid (label 4) all in the
+ * **protected** header — the signature covers them; nothing interpretable
+ * rides unprotected (review F1). Statement bytes go to `--out`, or raw to
+ * stdout — except under `--json` without `--out`, where they are returned
+ * base64 inside the report (stdout carries JSON).
+ */
+export async function runSignStatement(
+  out: Out,
+  options: SignStatementOptions,
+): Promise<void> {
+  let payload: Uint8Array;
+  let signed: SignedStatement;
+  let kidHex: string;
+  try {
+    rejectEmptyClaim("--iss", options.iss, "the default hex-kid issuer");
+    rejectEmptyClaim("--sub", options.sub, "the default payload-hash subject");
+    payload = readPayloadBytes(options.payload);
+    const key = await loadEs256SigningKey(options.key);
+    signed = await buildSignedStatement(payload, key, {
+      contentType: options.contentType,
+      iss: options.iss,
+      sub: options.sub,
+      iat: resolveIatOption(options.iat),
+    });
+    kidHex = Buffer.from(key.kid).toString("hex");
+    if (options.out !== undefined) {
+      writeFileSync(options.out, signed.statement);
+    }
+  } catch (err) {
+    reportFailure(out, options, errorMessage(err));
+    return;
+  }
+  const statement = signed.statement;
+
+  if (options.json) {
+    const report: SignStatementReport = {
+      command: "sign-statement",
+      alg: "ES256",
+      kid: kidHex,
+      payloadBytes: payload.length,
+      contentType: options.contentType,
+      iss: signed.iss,
+      sub: signed.sub,
+      ...(signed.iat !== undefined && { iat: signed.iat }),
+      statementBytes: statement.length,
+      ...(options.out !== undefined
+        ? { out: options.out }
+        : { statementB64: Buffer.from(statement).toString("base64") }),
+    };
+    out.out(JSON.stringify(report, null, 2));
+    return;
+  }
+
+  if (options.out === undefined) {
+    // Raw CBOR to stdout (pipeable); the summary stays on stderr.
+    writeFileSync(1, statement);
+  }
+  out.print("signed statement: plain COSE Sign1 (ES256)");
+  out.print("  kid:       %s", kidHex);
+  out.print("  iss:       %s", signed.iss);
+  out.print("  sub:       %s", signed.sub);
+  if (signed.iat !== undefined) out.print("  iat:       %d", signed.iat);
+  out.print("  payload:   %d bytes (%s)", payload.length, options.contentType);
+  out.print(
+    "  statement: %d bytes -> %s",
+    statement.length,
+    options.out ?? "stdout",
+  );
+}
+
+/** Largest iat the canonical encoder accepts (4-byte CBOR uint). */
+const IAT_MAX_SECONDS = 0xffffffff;
+
+/** `--iat now` → current unix seconds; digits → bounded integer. */
+function resolveIatOption(raw: string | undefined): number | undefined {
+  if (raw === undefined) return undefined;
+  if (raw === "now") return Math.floor(Date.now() / 1000);
+  if (!/^\d+$/.test(raw)) {
+    throw new Error(`--iat must be 'now' or unix seconds, got '${raw}'`);
+  }
+  const seconds = Number.parseInt(raw, 10);
+  if (seconds > IAT_MAX_SECONDS) {
+    throw new Error(
+      `--iat ${raw} exceeds ${IAT_MAX_SECONDS} (unix seconds; a 13-digit value is usually milliseconds — divide by 1000)`,
+    );
+  }
+  return seconds;
+}
+
+/** An explicit empty claim is an error, never a silent default. */
+function rejectEmptyClaim(
+  flag: string,
+  value: string | undefined,
+  fallbackDescription: string,
+): void {
+  if (value === "") {
+    throw new Error(
+      `${flag} must not be empty (omit it for ${fallbackDescription})`,
+    );
+  }
+}
+
+/** Human mode: one line on stderr. `--json`: the report on stdout. */
+function reportFailure(
+  out: Out,
+  options: SignStatementOptions,
+  message: string,
+): void {
+  if (options.json) {
+    const report: SignStatementError = {
+      error: "sign_statement_failed",
+      command: "sign-statement",
+      message,
+    };
+    out.out(JSON.stringify(report, null, 2));
+  } else {
+    out.warn("forestrie sign-statement: %s", message);
+  }
+  process.exitCode = 1;
+}