@forestrie/forestrie-cli 0.8.0

package/src/lib/onboard-attestation.ts

@@ -0,0 +1,120 @@
+/**
+ * Bootstrap-key registrant attestation producer (devdocs plan-2607-43 slice
+ * 06, ADR-0059 D8) — the client half of canopy's
+ * `onboarding/onboard-attestation.ts` verifier; the two must agree
+ * byte-for-byte on Sig_structure.
+ *
+ * COSE_Sign1, protected `{1: alg, 3: content type}`, payload = CWT claims:
+ * `iss` = the CAIP-10 univocityInstanceId, `aud` = the operator origin,
+ * `iat`/`exp` = a bounded freshness window, and a private claim (-70000)
+ * carrying the exact chain binding. Signed by the deployment's bootstrap key
+ * — the only key that can ever produce the instance's first checkpoint, so
+ * holder-of-key and whose-instance-this-is are the same party.
+ */
+
+import { sign as signSecp256k1 } from "viem/accounts";
+import { keccak256, hexToBytes as viemHexToBytes } from "viem";
+import {
+  encodeCborDeterministic,
+  encodeSigStructure,
+} from "@forestrie/encoding";
+import type { Es256SigningKey } from "./sign-statement-key.js";
+
+export const ONBOARD_ATTESTATION_CONTENT_TYPE =
+  "application/forestrie-onboard-attestation+cwt";
+
+export const COSE_ALG_ES256 = -7;
+export const COSE_ALG_KS256 = -65799;
+
+/** Private CWT claim: map {1: chainId tstr, 2: univocityAddr 40-lowerhex}. */
+export const CLAIM_CHAIN_BINDING = -70000;
+
+/** Default freshness window (canopy's policy ceiling is 24 h). */
+export const DEFAULT_ATTESTATION_WINDOW_SEC = 3600;
+
+export interface OnboardAttestationInput {
+  chainId: string;
+  /** 40-hex lowercase address body, no 0x. */
+  univocityAddr: string;
+  /** Operator deployment origin, e.g. `https://api-a.forest-2.forestrie.dev`. */
+  aud: string;
+  nowSec: number;
+  windowSec?: number;
+}
+
+function claimsBytes(input: OnboardAttestationInput): Uint8Array {
+  const window = input.windowSec ?? DEFAULT_ATTESTATION_WINDOW_SEC;
+  const claims = new Map<number, unknown>([
+    [1, `eip155:${input.chainId}:0x${input.univocityAddr}`],
+    [3, input.aud],
+    [4, input.nowSec + window],
+    [6, input.nowSec],
+    [
+      CLAIM_CHAIN_BINDING,
+      new Map<number, unknown>([
+        [1, input.chainId],
+        [2, input.univocityAddr],
+      ]),
+    ],
+  ]);
+  return encodeCborDeterministic(claims);
+}
+
+function protectedBytes(alg: number): Uint8Array {
+  return encodeCborDeterministic(
+    new Map<number, unknown>([
+      [1, alg],
+      [3, ONBOARD_ATTESTATION_CONTENT_TYPE],
+    ]),
+  );
+}
+
+function assemble(
+  prot: Uint8Array,
+  payload: Uint8Array,
+  signature: Uint8Array,
+): Uint8Array {
+  return encodeCborDeterministic([prot, new Map(), payload, signature]);
+}
+
+/** ES256 attestation signed with the deploy-generated bootstrap PEM key. */
+export async function buildOnboardAttestationEs256(
+  key: Es256SigningKey,
+  input: OnboardAttestationInput,
+): Promise<Uint8Array> {
+  const prot = protectedBytes(COSE_ALG_ES256);
+  const payload = claimsBytes(input);
+  const sigStructure = encodeSigStructure(prot, new Uint8Array(0), payload);
+  const signature = new Uint8Array(
+    await crypto.subtle.sign(
+      { name: "ECDSA", hash: "SHA-256" },
+      key.privateKey,
+      sigStructure as unknown as ArrayBuffer,
+    ),
+  );
+  return assemble(prot, payload, signature);
+}
+
+/**
+ * KS256 attestation: the delegation-cose profile — keccak256(Sig_structure),
+ * 65-byte `r‖s‖v` EOA signature by the bootstrap key.
+ */
+export async function buildOnboardAttestationKs256(
+  privateKeyHex: string,
+  input: OnboardAttestationInput,
+): Promise<Uint8Array> {
+  const prot = protectedBytes(COSE_ALG_KS256);
+  const payload = claimsBytes(input);
+  const sigStructure = encodeSigStructure(prot, new Uint8Array(0), payload);
+  const hash = keccak256(sigStructure);
+  const key = privateKeyHex.startsWith("0x")
+    ? (privateKeyHex as `0x${string}`)
+    : (`0x${privateKeyHex}` as `0x${string}`);
+  const sig = await signSecp256k1({ hash, privateKey: key, to: "bytes" });
+  if (sig.length !== 65) {
+    throw new Error(`KS256 signature must be 65 bytes, got ${sig.length}`);
+  }
+  return assemble(prot, payload, sig);
+}
+
+export { viemHexToBytes as hexToBytes };

package/src/lib/onboard-genesis-body.ts

@@ -0,0 +1,94 @@
+/**
+ * Direct-sign ES256 forest genesis body (FOR-406, plan-2607-27 W2).
+ *
+ * The operator onboarding payload for a `forestrie deploy`ed forest: the
+ * five-label v2 genesis map canopy's forest-genesis expects for the
+ * direct-sign path, encoded with the sanctioned deterministic RFC 8949
+ * §4.2 codec. This is the single shipped implementation that retires the
+ * demo's onboard-genesis.mjs and system-testing's es256-genesis helper.
+ */
+import { createPublicKey } from "node:crypto";
+import { encodeCborDeterministic } from "@forestrie/encoding";
+
+/** CBOR labels aligned with canopy forest-genesis-labels (v2 direct-sign). */
+const LABEL_GENESIS_VERSION = -68009;
+const LABEL_UNIVOCITY_ADDR = -68011;
+const LABEL_CHAIN_ID = -68013;
+const LABEL_GENESIS_ALG = -68014;
+const LABEL_BOOTSTRAP_KEY = -68015;
+const SCHEMA_V2 = 2;
+const COSE_ALG_ES256 = -7;
+
+function hexToBytes20(hex: string): Uint8Array {
+  const stripped = hex.startsWith("0x") ? hex.slice(2) : hex;
+  if (!/^[0-9a-fA-F]{40}$/.test(stripped)) {
+    throw new Error(`expected a 20-byte hex contract address, got ${hex}`);
+  }
+  const out = new Uint8Array(20);
+  for (let i = 0; i < 20; i += 1) {
+    out[i] = Number.parseInt(stripped.slice(i * 2, i * 2 + 2), 16);
+  }
+  return out;
+}
+
+/** Raw 64-byte x||y public key from a P-256 PEM (private or public). */
+export function es256PublicKeyXy(pem: string): Uint8Array {
+  const jwk = createPublicKey(pem).export({ format: "jwk" });
+  if (jwk.crv !== "P-256" || !jwk.x || !jwk.y) {
+    throw new Error("bootstrap PEM must be a P-256 (ES256) key");
+  }
+  const x = Buffer.from(jwk.x, "base64url");
+  const y = Buffer.from(jwk.y, "base64url");
+  if (x.length !== 32 || y.length !== 32) {
+    throw new Error(
+      `expected 32-byte P-256 coordinates, got x=${x.length} y=${y.length}`,
+    );
+  }
+  const xy = new Uint8Array(64);
+  xy.set(x, 0);
+  xy.set(y, 32);
+  return xy;
+}
+
+/** Build the v2 direct-sign genesis CBOR body. */
+export function buildEs256GenesisBody(opts: {
+  chainId: string;
+  univocityAddress: string;
+  bootstrapKeyXy: Uint8Array;
+}): Uint8Array {
+  if (opts.bootstrapKeyXy.length !== 64) {
+    throw new Error(
+      `bootstrap key must be 64 bytes (x||y), got ${opts.bootstrapKeyXy.length}`,
+    );
+  }
+  if (!opts.chainId.trim()) {
+    throw new Error("chainId must be a non-empty string");
+  }
+  return encodeCborDeterministic(
+    new Map<number, unknown>([
+      [LABEL_GENESIS_VERSION, SCHEMA_V2],
+      [LABEL_UNIVOCITY_ADDR, hexToBytes20(opts.univocityAddress)],
+      [LABEL_CHAIN_ID, opts.chainId],
+      [LABEL_GENESIS_ALG, COSE_ALG_ES256],
+      [LABEL_BOOTSTRAP_KEY, opts.bootstrapKeyXy],
+    ]),
+  );
+}
+
+/** Genesis POST URL with the sealing-callback webhook query param. */
+export function genesisPostUrl(
+  baseUrl: string,
+  logId: string,
+  webhookUrl: string,
+): string {
+  const base = baseUrl.replace(/\/$/, "");
+  return `${base}/api/forest/${logId}/genesis?webhookUrl=${encodeURIComponent(webhookUrl)}`;
+}
+
+/** Coordinator signing-route webhook for a log (ADR-0050 sealing wiring). */
+export function coordinatorSigningRouteUrl(
+  coordinatorUrl: string,
+  logId: string,
+): string {
+  return `${coordinatorUrl.replace(/\/$/, "")}/api/logs/${logId}/signing-route`;
+}

package/src/lib/openssl-error-queue.ts

@@ -0,0 +1,56 @@
+/**
+ * OpenSSL/BoringSSL thread-local error-queue hygiene (FOR-343).
+ *
+ * On bun (BoringSSL), a FAILED `crypto.subtle.importKey` over malformed DER
+ * leaves one unconsumed error on the thread-local OpenSSL error queue. The
+ * NEXT `node:crypto` PEM parse (`createPrivateKey` / `createPublicKey`) reads
+ * that stale error and misreports a perfectly valid key as
+ * `error:0c00007b:ASN.1 encoding routines:OPENSSL_internal:HEADER_TOO_LONG`.
+ * A single subsequent parse consumes the stale entry, so the corruption
+ * "poisons" exactly one following operation.
+ *
+ * This bites cross-module in the single bun test runtime: `forestrie deploy`'s
+ * negative-path test (a deliberately invalid bootstrap PEM routed through
+ * `@forestrie/deploy-core`'s WebCrypto importKey) poisons the queue, and a
+ * later `sign-statement` / `register-grant` PEM parse in another test file
+ * then fails spuriously. See the FOR-343 repro.
+ *
+ * These helpers keep the failure contained: {@link drainOpenSslErrorQueue}
+ * consumes the stale entry at the source (right after a known crypto failure),
+ * and {@link parsePemResilient} retries once so a valid key is never rejected
+ * because of a queue poisoned elsewhere.
+ */
+import { createPublicKey } from "node:crypto";
+
+/**
+ * Consume any single stale entry left on the OpenSSL error queue by a prior
+ * failed crypto operation. Parses a deliberately invalid PEM and swallows the
+ * (expected) throw: that parse reads and clears the stale entry. Best-effort
+ * and never throws.
+ */
+export function drainOpenSslErrorQueue(): void {
+  try {
+    createPublicKey({
+      key: "-----BEGIN PUBLIC KEY-----\nAA\n-----END PUBLIC KEY-----\n",
+      format: "pem",
+    });
+  } catch {
+    // Expected: the invalid PEM consumes the stale queue entry (and its own).
+  }
+}
+
+/**
+ * Run a PEM `parse` that may spuriously throw because the OpenSSL error queue
+ * was poisoned by an unrelated prior crypto failure. On the first failure the
+ * stale entry is consumed, so a single retry either succeeds (the input was
+ * always valid) or throws the genuine error (the input is truly invalid).
+ */
+export function parsePemResilient<T>(parse: () => T): T {
+  try {
+    return parse();
+  } catch {
+    // Retry once: the failed attempt above drained any poisoning entry, so a
+    // valid key now parses; a genuinely-invalid key throws the real error here.
+    return parse();
+  }
+}

package/src/lib/register-flow.ts

@@ -0,0 +1,292 @@
+/**
+ * FOR-342 registration flow: POST the signed statement, then drive the
+ * SCRAPI 303 receipt-redirect contract to completion.
+ *
+ * `@forestrie/scrapi-client` deliberately ships poll-once primitives with
+ * NO sleep loops — this module owns the pacing (`--timeout` /
+ * `--poll-interval`), honouring a longer `Retry-After` when the worker
+ * sends one. Fetch/sleep/clock are injectable for tests.
+ */
+import {
+  ScrapiRegistrationError,
+  queryRegistrationOnce,
+  registerSignedStatement,
+  resolveReceiptOnce,
+  toAbsoluteScrapiUrl,
+  type ProblemDetails,
+} from "@forestrie/scrapi-client";
+
+/** Where the flow failed — drives the `--json` error code. */
+export type RegisterFlowStage =
+  | "register" // POST /register/{logId}/entries rejected
+  | "status" // query-registration-status broke the 303 contract
+  | "receipt" // resolve-receipt answered non-200/404
+  | "network" // fetch itself failed (ECONNREFUSED, DNS, reset) — no response
+  | "timeout"; // `--timeout` budget exhausted (pending, or a hung request)
+
+export class RegisterFlowError extends Error {
+  readonly stage: RegisterFlowStage;
+  readonly httpStatus: number | undefined;
+  /** Problem `detail` (or body preview) from the failing response. */
+  readonly detail: string | undefined;
+  /** RFC 9457 problem details decoded from a CBOR error body. */
+  readonly problem: ProblemDetails | undefined;
+  readonly statusUrl: string | undefined;
+  readonly receiptUrl: string | undefined;
+
+  constructor(
+    message: string,
+    info: {
+      stage: RegisterFlowStage;
+      httpStatus?: number;
+      detail?: string;
+      problem?: ProblemDetails;
+      statusUrl?: string;
+      receiptUrl?: string;
+    },
+  ) {
+    super(message);
+    this.name = "RegisterFlowError";
+    this.stage = info.stage;
+    this.httpStatus = info.httpStatus;
+    this.detail = info.detail;
+    this.problem = info.problem;
+    this.statusUrl = info.statusUrl;
+    this.receiptUrl = info.receiptUrl;
+  }
+}
+
+/** Progress callbacks so the CLI can narrate long polls on stderr. */
+export type RegisterProgress =
+  | { phase: "registered"; statusUrl: string }
+  | { phase: "status-pending"; statusUrl: string; attempt: number }
+  | { phase: "receipt-located"; receiptUrl: string; entryIdHex: string }
+  | { phase: "receipt-pending"; receiptUrl: string; attempt: number };
+
+/** Injectable effects — production defaults are real fetch/sleep/clock. */
+export type RegisterFlowDeps = {
+  fetchImpl?: typeof fetch;
+  sleep?: (ms: number) => Promise<void>;
+  now?: () => number;
+  onProgress?: (progress: RegisterProgress) => void;
+};
+
+export type RegisterFlowParams = {
+  /** SCRAPI origin, no trailing slash. */
+  baseUrl: string;
+  /** Forest bootstrap log id — first `/register/` path segment. */
+  logId: string;
+  /** Completed grant, `Authorization: Forestrie-Grant` base64. */
+  grantB64: string;
+  /** COSE Sign1 signed statement wire bytes. */
+  statement: Uint8Array;
+  /** Overall budget covering both poll phases. */
+  timeoutMs: number;
+  /** Pacing between polls; a longer `Retry-After` wins. */
+  pollIntervalMs: number;
+};
+
+export type RegisterFlowResult = {
+  /** Final query-registration-status URL (from the register 303). */
+  statusUrl: string;
+  /** Permanent resolve-receipt URL. */
+  receiptUrl: string;
+  /** Permanent entry id (32 hex chars) from the receipt Location. */
+  entryIdHex: string;
+  /** Receipt wire bytes (CBOR). */
+  receipt: Uint8Array;
+  contentType: string | undefined;
+};
+
+const defaultSleep = (ms: number): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, ms));
+
+/** One line for a transport failure: `code: message (cause)` where known. */
+function describeFetchError(err: unknown): string {
+  if (!(err instanceof Error)) return String(err);
+  const code = (err as { code?: unknown }).code;
+  const cause =
+    err.cause instanceof Error && err.cause.message !== err.message
+      ? ` (${err.cause.message})`
+      : "";
+  return typeof code === "string" && code !== "" && !err.message.includes(code)
+    ? `${code}: ${err.message}${cause}`
+    : `${err.message}${cause}`;
+}
+
+function requestUrl(input: Parameters<typeof fetch>[0]): string {
+  if (typeof input === "string") return input;
+  if (input instanceof URL) return input.href;
+  return input.url;
+}
+
+/**
+ * F4 (plan-2607-14 W1.4): bound every request with an AbortSignal tied to
+ * the remaining `--timeout` budget — a hung server cannot stall the flow
+ * past the deadline (the deadline was previously only checked BETWEEN
+ * polls) — and map fetch-level failures (ECONNREFUSED, DNS, resets) into
+ * the `RegisterFlowError` taxonomy instead of letting bare TypeErrors
+ * escape as unstructured crashes.
+ *
+ * The timer uses real wall-clock (`setTimeout`) while `remaining` comes
+ * from the injectable `now` — with a fake clock the fake fetch resolves
+ * immediately and the timer is cleared before it can fire.
+ */
+function boundedFetch(
+  baseFetch: typeof fetch,
+  now: () => number,
+  deadline: number,
+  timeoutMs: number,
+): typeof fetch {
+  return (async (
+    input: Parameters<typeof fetch>[0],
+    init?: RequestInit,
+  ): Promise<Response> => {
+    const remaining = deadline - now();
+    if (remaining <= 0) {
+      throw new RegisterFlowError(
+        `timed out after ${timeoutMs}ms waiting for the receipt`,
+        { stage: "timeout" },
+      );
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), remaining);
+    try {
+      return await baseFetch(input, { ...init, signal: controller.signal });
+    } catch (err) {
+      if (err instanceof RegisterFlowError) throw err;
+      const url = requestUrl(input);
+      if (controller.signal.aborted) {
+        throw new RegisterFlowError(
+          `timed out after ${timeoutMs}ms: no response from ${url} within the --timeout budget`,
+          { stage: "timeout", detail: url },
+        );
+      }
+      throw new RegisterFlowError(
+        `request to ${url} failed: ${describeFetchError(err)}`,
+        { stage: "network", detail: describeFetchError(err) },
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+  }) as typeof fetch;
+}
+
+/**
+ * Register `statement` and wait for its receipt: POST → 303 status URL →
+ * poll query-registration-status until the receipt redirect → poll
+ * resolve-receipt (404 = objects still writing) until 200.
+ */
+export async function runRegisterFlow(
+  params: RegisterFlowParams,
+  deps: RegisterFlowDeps = {},
+): Promise<RegisterFlowResult> {
+  const sleep = deps.sleep ?? defaultSleep;
+  const now = deps.now ?? Date.now;
+  const onProgress = deps.onProgress ?? (() => {});
+  const deadline = now() + params.timeoutMs;
+  const fetchImpl = boundedFetch(
+    deps.fetchImpl ?? fetch,
+    now,
+    deadline,
+    params.timeoutMs,
+  );
+
+  const paceOrTimeout = async (
+    waitMs: number,
+    info: { statusUrl: string; receiptUrl?: string },
+  ): Promise<void> => {
+    if (now() + waitMs > deadline) {
+      throw new RegisterFlowError(
+        `timed out after ${params.timeoutMs}ms waiting for the receipt`,
+        { stage: "timeout", ...info },
+      );
+    }
+    await sleep(waitMs);
+  };
+
+  // 1. POST /register/{logId}/entries — only 303 + Location succeeds.
+  let statusUrl: string;
+  try {
+    ({ statusUrl } = await registerSignedStatement({
+      baseUrl: params.baseUrl,
+      bootstrapLogId: params.logId,
+      grantBase64: params.grantB64,
+      statement: params.statement,
+      fetchImpl,
+    }));
+  } catch (err) {
+    if (err instanceof ScrapiRegistrationError) {
+      throw new RegisterFlowError(err.message, {
+        stage: "register",
+        httpStatus: err.httpStatus,
+        detail: err.detail,
+        ...(err.problem !== undefined ? { problem: err.problem } : {}),
+      });
+    }
+    throw err;
+  }
+  onProgress({ phase: "registered", statusUrl });
+
+  // 2. Poll query-registration-status until the receipt redirect.
+  let receiptUrl: string;
+  let entryIdHex: string;
+  for (let attempt = 1; ; attempt++) {
+    const status = await queryRegistrationOnce({
+      statusUrl,
+      baseUrl: params.baseUrl,
+      fetchImpl,
+    });
+    if (status.status === "receipt") {
+      ({ receiptUrl, entryIdHex } = status);
+      break;
+    }
+    if (status.status === "error") {
+      throw new RegisterFlowError(
+        `registration status: ${status.detail}`,
+        {
+          stage: "status",
+          httpStatus: status.httpStatus,
+          detail: status.detail,
+          ...(status.problem !== undefined ? { problem: status.problem } : {}),
+          statusUrl,
+        },
+      );
+    }
+    // pending — the worker may move the status Location and pace us.
+    statusUrl = toAbsoluteScrapiUrl(params.baseUrl, status.location);
+    onProgress({ phase: "status-pending", statusUrl, attempt });
+    await paceOrTimeout(
+      Math.max(params.pollIntervalMs, status.retryAfterMs ?? 0),
+      { statusUrl },
+    );
+  }
+  onProgress({ phase: "receipt-located", receiptUrl, entryIdHex });
+
+  // 3. Poll resolve-receipt: 404 = checkpoint/massif still writing.
+  for (let attempt = 1; ; attempt++) {
+    const resolution = await resolveReceiptOnce({ receiptUrl, fetchImpl });
+    if (resolution.status === "receipt") {
+      return {
+        statusUrl,
+        receiptUrl,
+        entryIdHex,
+        receipt: resolution.body,
+        contentType: resolution.headers["content-type"],
+      };
+    }
+    if (resolution.status === "error") {
+      throw new RegisterFlowError(
+        `resolve receipt: HTTP ${resolution.httpStatus}`,
+        {
+          stage: "receipt",
+          httpStatus: resolution.httpStatus,
+          statusUrl,
+          receiptUrl,
+        },
+      );
+    }
+    onProgress({ phase: "receipt-pending", receiptUrl, attempt });
+    await paceOrTimeout(params.pollIntervalMs, { statusUrl, receiptUrl });
+  }
+}