@forestrie/forestrie-cli 0.8.0

package/src/lib/verify-report.ts

@@ -0,0 +1,265 @@
+import type {
+  ReceiptVerifyResult,
+  ReceiptVerifyStage,
+} from "@forestrie/receipt-verify";
+import type { AnchorCheck } from "./verify-anchored.js";
+
+/**
+ * Result → report shaping for `forestrie verify` (FOR-347). Pure — the
+ * `--json` shape emitted from here is a contract for demo scripting.
+ */
+
+/** Verification pipeline in narration order (ADR-0045 layers A–C). */
+export const VERIFY_STAGES: readonly ReceiptVerifyStage[] = [
+  "parse",
+  "signature",
+  "inclusion",
+  "binding",
+];
+
+/** One line per stage: what the audience sees at every demo step. */
+export const STAGE_NARRATION: Record<ReceiptVerifyStage, string> = {
+  parse: "receipt COSE decodes; genesis trust root loads (ES256)",
+  signature: "checkpoint signature verifies under the genesis trust key",
+  inclusion: "proof path recomputes the checkpoint peak",
+  binding: "leaf commits the payload (SHA-256) at the receipt idtimestamp",
+};
+
+export type StageStatus = "ok" | "failed" | "skipped";
+
+export type StageRow = {
+  stage: ReceiptVerifyStage;
+  status: StageStatus;
+  reason?: string;
+};
+
+/**
+ * Anchor-only chain verification (FOR-297 approach C): the checkpoint was
+ * sealed under a delegation the offline verifier cannot resolve (a child
+ * log's per-log delegation does not chain to the root genesis). The
+ * signature stage still reports **ok** — not because the COSE check re-ran
+ * locally, but because a match against the on-chain accumulator *implies*
+ * it: univocity only accepts a checkpoint whose signature verifies under
+ * the log's live delegation, whose publish grant's inclusion is re-proven
+ * against the parent's on-chain state on EVERY publish, and whose
+ * accumulator is consistency-gated against the previously published state.
+ * So if the locally-recomputed peak (from `leaf(payload, idtimestamp)` +
+ * the receipt's proof path) appears in the accumulator, the publishing
+ * signature was valid and a fresh grant chain to the bootstrap existed at
+ * publish time — the anchor match combines inclusion, binding, signature
+ * validity AND a split-view check (status-2607-09 D2).
+ *
+ * Enforcement cited from `_Univocity.sol publishCheckpoint` @ univocity
+ * ea410d5a90e4c2337fc1dec288d660551daf36ab:
+ * - signature under the live delegation: `_verifyCheckpointSignature`,
+ *   src/contracts/_Univocity.sol#L199-L208 (reverts on failure)
+ * - grant inclusion re-verified each publish (rules 1–3):
+ *   `_applyInclusionGrant`, src/contracts/_Univocity.sol#L211-L219
+ * - grant bounds (rule 4): src/contracts/_Univocity.sol#L181-L188
+ * - consistency gating: `verifyConsistencyProofChain`,
+ *   src/contracts/_Univocity.sol#L189-L193
+ */
+export const SIGNATURE_ANCHORED_REASON =
+  "verified against accumulator from chain — signature enforced by univocity at publish";
+
+export function anchorOnlyStageRows(): StageRow[] {
+  return [
+    { stage: "parse", status: "ok" },
+    {
+      stage: "signature",
+      status: "ok",
+      reason: SIGNATURE_ANCHORED_REASON,
+    },
+    { stage: "inclusion", status: "ok" },
+    { stage: "binding", status: "ok" },
+  ];
+}
+
+/**
+ * Expand the library's `{ok, stage, reason}` into one row per stage:
+ * on success all four pass; on failure the reported stage failed, earlier
+ * stages passed, later stages were not reached.
+ *
+ * A stage this CLI does not know (a future `@forestrie/receipt-verify`
+ * addition) still renders explicitly as the failed row — degrading it to
+ * four silent "skipped" rows would hide the failure (F3, plan-2607-14
+ * W1.3). We cannot order an unknown stage among the known ones, so the
+ * known stages read "skipped" (not evaluated by this CLI's knowledge) and
+ * the unknown stage carries the failure.
+ */
+/**
+ * Caller-known trust anchor (FOR-297 D1): the claim is verified under a key
+ * the CALLER supplied out of band, not one derived from genesis — the output
+ * must name that anchor so the two claims are never confusable. The known key
+ * asserts the key↔log binding (its provenance is the only defence), gives no
+ * grant-lifecycle visibility and no split-view protection.
+ */
+export const KNOWN_KEY_PARSE_REASON =
+  "receipt COSE decodes; caller-known log key loads (ES256)";
+export const KNOWN_KEY_SIGNATURE_REASON =
+  "verifies under caller-known log key (not genesis-derived)";
+
+/** Stage rows for a verify run anchored on `--known-log-key` (FOR-297 D1). */
+export function knownKeyStageRows(result: ReceiptVerifyResult): StageRow[] {
+  return stageRows(result).map((row) => {
+    if (row.status !== "ok") return row;
+    if (row.stage === "parse") return { ...row, reason: KNOWN_KEY_PARSE_REASON };
+    if (row.stage === "signature")
+      return { ...row, reason: KNOWN_KEY_SIGNATURE_REASON };
+    return row;
+  });
+}
+
+export function stageRows(result: ReceiptVerifyResult): StageRow[] {
+  if (result.ok) {
+    return VERIFY_STAGES.map((stage) => ({ stage, status: "ok" }));
+  }
+  const failedAt = VERIFY_STAGES.indexOf(result.stage);
+  if (failedAt === -1) {
+    return [
+      ...VERIFY_STAGES.map((stage) => ({
+        stage,
+        status: "skipped" as const,
+      })),
+      {
+        stage: result.stage,
+        status: "failed" as const,
+        reason: result.reason ?? "unknown",
+      },
+    ];
+  }
+  return VERIFY_STAGES.map((stage, i) => {
+    if (i < failedAt) return { stage, status: "ok" as const };
+    if (i === failedAt) {
+      return {
+        stage,
+        status: "failed" as const,
+        reason: result.reason ?? "unknown",
+      };
+    }
+    return { stage, status: "skipped" as const };
+  });
+}
+
+/** `--json` anchor block (chain / known-accumulator modes). Sizes are
+ * decimal strings. */
+export type AnchorReport = {
+  univocity: string;
+  logId: string;
+  anchored: boolean;
+  anchoredSize: string;
+  peakCount: number;
+  matchedPeak: number | null;
+  reason?: string;
+  /** known-accumulator anchors only: the audited chain read (FOR-297 D5). */
+  blockNumber?: string;
+  blockHash?: string;
+  /** True when the match required proof-path extension via massif nodes. */
+  extended?: boolean;
+  /** Historical event-scan anchor (FOR-368): the peak matched a prior
+   * CheckpointPublished accumulator; consistency-gated forward. */
+  historical?: boolean;
+  anchoredAtBlock?: string;
+  txHash?: string;
+  /** Checkpoint-chain anchors only (FOR-368 Phase 3): links folded and the
+   * sealed size of the link that held the peak. */
+  linkCount?: number;
+  matchedLinkSize?: string;
+  /** Consistency-proof top-up (FOR-368 Phase 3): base size the untrusted
+   * artifact extended the receipt from into the trusted snapshot. */
+  topUpBaseSize?: string;
+};
+
+export type VerifyMode =
+  | "offline"
+  | "chain-anchored"
+  | "accumulator-anchored"
+  | "checkpoint-chain-anchored";
+
+/** `--json` report on stdout — stable shape for demo scripting. */
+export type VerifyReport = {
+  command: "verify";
+  mode: VerifyMode;
+  ok: boolean;
+  stage: ReceiptVerifyStage;
+  reason?: string;
+  stages: StageRow[];
+  anchor?: AnchorReport;
+};
+
+/** Extra anchor facts present only for known-accumulator checks. */
+type SnapshotAnchorFacts = {
+  blockNumber?: bigint;
+  blockHashHex?: string;
+  extended?: boolean;
+};
+
+export function buildVerifyReport(opts: {
+  ok: boolean;
+  result: ReceiptVerifyResult;
+  mode: VerifyMode;
+  anchor?: (AnchorCheck & SnapshotAnchorFacts) | undefined;
+  univocity?: string | undefined;
+  logId?: string | undefined;
+  /** Anchor-only mode: rows that reflect the skipped signature stage. */
+  stagesOverride?: StageRow[] | undefined;
+}): VerifyReport {
+  const report: VerifyReport = {
+    command: "verify",
+    mode: opts.mode,
+    ok: opts.ok,
+    stage: opts.result.stage,
+    stages: opts.stagesOverride ?? stageRows(opts.result),
+  };
+  if (opts.result.reason !== undefined) {
+    report.reason = opts.result.reason;
+  }
+  if (opts.anchor !== undefined) {
+    const anchor: AnchorReport = {
+      univocity: opts.univocity ?? "",
+      logId: opts.logId ?? "",
+      anchored: opts.anchor.anchored,
+      anchoredSize: opts.anchor.size.toString(),
+      peakCount: opts.anchor.accumulator.length,
+      matchedPeak: opts.anchor.matchedPeak,
+    };
+    if (opts.anchor.reason !== undefined) {
+      anchor.reason = opts.anchor.reason;
+    }
+    if (opts.anchor.blockNumber !== undefined) {
+      anchor.blockNumber = opts.anchor.blockNumber.toString();
+      anchor.blockHash = `0x${opts.anchor.blockHashHex ?? ""}`;
+      anchor.extended = opts.anchor.extended === true;
+    }
+    const historical = opts.anchor as {
+      historical?: boolean;
+      anchoredAtBlock?: bigint;
+      txHash?: string;
+    };
+    if (historical.historical === true) {
+      anchor.historical = true;
+      if (historical.anchoredAtBlock !== undefined) {
+        anchor.anchoredAtBlock = historical.anchoredAtBlock.toString();
+      }
+      if (historical.txHash !== undefined) {
+        anchor.txHash = historical.txHash;
+      }
+    }
+    const chained = opts.anchor as {
+      linkCount?: number;
+      matchedLinkSize?: bigint | null;
+    };
+    if (chained.linkCount !== undefined) {
+      anchor.linkCount = chained.linkCount;
+      if (chained.matchedLinkSize !== undefined && chained.matchedLinkSize !== null) {
+        anchor.matchedLinkSize = chained.matchedLinkSize.toString();
+      }
+    }
+    const topUp = opts.anchor as { topUpBaseSize?: bigint };
+    if (topUp.topUpBaseSize !== undefined) {
+      anchor.topUpBaseSize = topUp.topUpBaseSize.toString();
+    }
+    report.anchor = anchor;
+  }
+  return report;
+}

package/src/lib/x402-payment.ts

@@ -0,0 +1,115 @@
+/**
+ * x402 `exact` payer: sign an EIP-3009 `transferWithAuthorization` against a
+ * decoded `X-PAYMENT-REQUIRED` challenge (base64 header value in, base64
+ * `X-PAYMENT` header value out). Matches the payload shape canopy's
+ * `parsePaymentHeader` expects and the facilitator settles.
+ *
+ * REAL money moves when a signed payment settles (testnet USDC on dev). The
+ * payer key never leaves this process and is never logged.
+ */
+
+import { privateKeyToAccount } from "viem/accounts";
+
+interface X402Option {
+  scheme: string;
+  network: string;
+  payTo: string;
+  asset: string;
+  amount: string;
+  maxTimeoutSeconds?: number;
+  extra?: { name?: string; version?: string };
+}
+
+function b64ToUtf8(b64: string): string {
+  return Buffer.from(b64, "base64").toString("utf8");
+}
+
+function randomNonceHex(): `0x${string}` {
+  const bytes = crypto.getRandomValues(new Uint8Array(32));
+  return `0x${Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("")}` as `0x${string}`;
+}
+
+export async function signX402Payment(
+  paymentRequiredB64: string,
+  payerKeyHex: string,
+  nowSec = Math.floor(Date.now() / 1000),
+): Promise<string> {
+  const decoded = JSON.parse(b64ToUtf8(paymentRequiredB64)) as {
+    accepts?: X402Option[];
+  };
+  const chosen = (decoded.accepts ?? []).find((o) => o.scheme === "exact");
+  if (!chosen) {
+    throw new Error("X-PAYMENT-REQUIRED has no 'exact' scheme option");
+  }
+  if (!chosen.extra?.name || !chosen.extra?.version) {
+    throw new Error("challenge lacks EIP-712 domain name/version in extra");
+  }
+
+  const key = payerKeyHex.startsWith("0x")
+    ? (payerKeyHex as `0x${string}`)
+    : (`0x${payerKeyHex}` as `0x${string}`);
+  const account = privateKeyToAccount(key);
+  const nonce = randomNonceHex();
+  const validAfter = BigInt(nowSec - 600);
+  const validBefore = BigInt(nowSec + (chosen.maxTimeoutSeconds ?? 300));
+
+  const signature = await account.signTypedData({
+    domain: {
+      name: chosen.extra.name,
+      version: chosen.extra.version,
+      chainId: Number(chosen.network.split(":")[1]),
+      verifyingContract: chosen.asset as `0x${string}`,
+    },
+    types: {
+      TransferWithAuthorization: [
+        { name: "from", type: "address" },
+        { name: "to", type: "address" },
+        { name: "value", type: "uint256" },
+        { name: "validAfter", type: "uint256" },
+        { name: "validBefore", type: "uint256" },
+        { name: "nonce", type: "bytes32" },
+      ],
+    },
+    primaryType: "TransferWithAuthorization",
+    message: {
+      from: account.address,
+      to: chosen.payTo as `0x${string}`,
+      value: BigInt(chosen.amount),
+      validAfter,
+      validBefore,
+      nonce,
+    },
+  });
+
+  const payload = {
+    x402Version: 2,
+    payload: {
+      authorization: {
+        from: account.address,
+        to: chosen.payTo,
+        value: chosen.amount,
+        validAfter: validAfter.toString(),
+        validBefore: validBefore.toString(),
+        nonce,
+      },
+      signature,
+    },
+    resource: {
+      url: "",
+      description: "forestrie onboard request",
+      mimeType: "application/cbor",
+    },
+    accepted: {
+      scheme: "exact",
+      network: chosen.network,
+      asset: chosen.asset,
+      amount: chosen.amount,
+      payTo: chosen.payTo,
+      maxTimeoutSeconds: chosen.maxTimeoutSeconds ?? 300,
+      extra: chosen.extra,
+    },
+  };
+  return Buffer.from(JSON.stringify(payload)).toString("base64");
+}

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

@@ -0,0 +1,216 @@
+import type { Out } from "@forestrie/cli-kit/reporting";
+import { writeOutputFile } from "../lib/fsio.js";
+import {
+  decodeCborDeterministic,
+  encodeCborDeterministic,
+} from "@forestrie/encoding";
+import type { AdminOnboardTokenOptions } from "../options/admin-onboard-token.js";
+import {
+  readDeploymentRecord,
+  univocityAddrHex,
+} from "../lib/deployment-record.js";
+
+/**
+ * FOR-406 (plan-2607-27 W1): mint a forest onboard token from
+ * `POST /api/payments/onboard-tokens` under the operator credential.
+ *
+ * The minted token is the ONLY product on stdout (or `--out`) so the
+ * command composes: `ONBOARD_TOKEN=$(forestrie admin onboard-token …)`.
+ * The operator credential is never logged or echoed, including in errors.
+ * Public onboarding is x402 (ARC-0015) — a future sibling token source
+ * feeding the same `onboard-genesis --onboard-token` input.
+ */
+
+/** Mint request body keys (canopy payments onboard-tokens contract). */
+const MINT_LABEL_KEY = 1;
+const MINT_CHAIN_ID_KEY = 3;
+const MINT_UNIVOCITY_ADDR_KEY = 4;
+
+/** `--json` success shape (the token itself; cref for operator records). */
+export type AdminOnboardTokenReport = {
+  command: "admin onboard-token";
+  status: "minted";
+  label: string;
+  token: string;
+  cref?: string;
+  /** Present when `--out` was given (token then omitted from stdout). */
+  out?: string;
+};
+
+export type AdminOnboardTokenErrorReport = {
+  error: "input_failed" | "mint_failed" | "network_failed" | "response_malformed";
+  command: "admin onboard-token";
+  message: string;
+  httpStatus?: number;
+};
+
+/** Test seam. */
+export type AdminOnboardTokenDeps = {
+  fetchImpl?: typeof fetch;
+};
+
+function mintUrl(baseUrl: string): string {
+  return `${baseUrl.replace(/\/$/, "")}/api/payments/onboard-tokens`;
+}
+
+/** Extract a required text field from the decoded CBOR response. */
+function responseText(
+  decoded: unknown,
+  field: string,
+): string | undefined {
+  const value =
+    decoded instanceof Map
+      ? decoded.get(field)
+      : decoded && typeof decoded === "object"
+        ? (decoded as Record<string, unknown>)[field]
+        : undefined;
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function reportError(
+  out: Out,
+  options: AdminOnboardTokenOptions,
+  report: AdminOnboardTokenErrorReport,
+): void {
+  if (options.json) {
+    out.out(JSON.stringify(report, null, 2));
+  } else {
+    out.warn("forestrie admin onboard-token: %s", report.message);
+    if (report.httpStatus !== undefined) {
+      out.warn("  httpStatus: %d", report.httpStatus);
+    }
+  }
+  process.exitCode = 1;
+}
+
+export async function runAdminOnboardToken(
+  out: Out,
+  options: AdminOnboardTokenOptions,
+  deps: AdminOnboardTokenDeps = {},
+): Promise<void> {
+  const fetchImpl = deps.fetchImpl ?? fetch;
+
+  // Bindings are mandatory on every token (ADR-0059 D7): the mint reserves
+  // the named univocity instance, and canopy 400s an unbound mint.
+  let chainId: string;
+  let univocityAddr: string;
+  try {
+    if (options.deployment !== undefined) {
+      const record = readDeploymentRecord(options.deployment);
+      if (record.chainId === undefined) {
+        throw new Error(
+          `${options.deployment}: deployment carries no chainId; pass --chain-id`,
+        );
+      }
+      chainId = record.chainId;
+      univocityAddr = univocityAddrHex(record);
+    } else if (options.chainId !== undefined && options.univocityAddr !== undefined) {
+      chainId = options.chainId.trim();
+      univocityAddr = univocityAddrHex({
+        imutableUnivocity: options.univocityAddr,
+      });
+    } else {
+      throw new Error(
+        "chain binding required: pass --deployment, or --chain-id with --univocity",
+      );
+    }
+  } catch (err) {
+    reportError(out, options, {
+      error: "input_failed",
+      command: "admin onboard-token",
+      message: err instanceof Error ? err.message : String(err),
+    });
+    return;
+  }
+
+  const body = encodeCborDeterministic(
+    new Map<number, string>([
+      [MINT_LABEL_KEY, options.label],
+      [MINT_CHAIN_ID_KEY, chainId],
+      [MINT_UNIVOCITY_ADDR_KEY, univocityAddr],
+    ]),
+  );
+
+  let res: Response;
+  try {
+    res = await fetchImpl(mintUrl(options.baseUrl), {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${options.opsToken}`,
+        "Content-Type": "application/cbor",
+        Accept: "application/cbor",
+      },
+      body: body.buffer.slice(
+        body.byteOffset,
+        body.byteOffset + body.byteLength,
+      ) as ArrayBuffer,
+    });
+  } catch (err) {
+    reportError(out, options, {
+      error: "network_failed",
+      command: "admin onboard-token",
+      // The ops token never appears in fetch errors; message is URL-level.
+      message: err instanceof Error ? err.message : String(err),
+    });
+    return;
+  }
+
+  if (!res.ok) {
+    reportError(out, options, {
+      error: "mint_failed",
+      command: "admin onboard-token",
+      message: `mint rejected: HTTP ${res.status}`,
+      httpStatus: res.status,
+    });
+    return;
+  }
+
+  let token: string | undefined;
+  let cref: string | undefined;
+  try {
+    const decoded = decodeCborDeterministic(
+      new Uint8Array(await res.arrayBuffer()),
+    );
+    token = responseText(decoded, "token");
+    cref = responseText(decoded, "cref");
+  } catch (err) {
+    reportError(out, options, {
+      error: "response_malformed",
+      command: "admin onboard-token",
+      message: `mint response is not valid CBOR: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    });
+    return;
+  }
+  if (token === undefined) {
+    reportError(out, options, {
+      error: "response_malformed",
+      command: "admin onboard-token",
+      message: "mint response carried no token field",
+    });
+    return;
+  }
+
+  if (options.out !== undefined) {
+    await writeOutputFile(options.out, token);
+  }
+  if (options.json) {
+    const report: AdminOnboardTokenReport = {
+      command: "admin onboard-token",
+      status: "minted",
+      label: options.label,
+      token,
+    };
+    if (cref !== undefined) report.cref = cref;
+    if (options.out !== undefined) report.out = options.out;
+    out.out(JSON.stringify(report, null, 2));
+    return;
+  }
+  if (options.out !== undefined) {
+    out.print("wrote onboard token (label %s) to %s", options.label, options.out);
+    return;
+  }
+  // The token is the pipeable product: nothing else on stdout.
+  out.out("%s", token);
+}