@forestrie/forestrie-cli 0.8.0

package/src/lib/consistency-proof.ts

@@ -0,0 +1,271 @@
+import { bytesEqual } from "./bytes.js";
+import {
+  decodeCborDeterministic,
+  encodeCborDeterministic,
+} from "@forestrie/encoding";
+import {
+  createSyncHasher,
+  indexConsistencyProof,
+  openMassifNodeStore,
+  peakMMRIndexes,
+  verifyConsistency,
+  type NodeGetter,
+} from "@forestrie/merklelog";
+
+/**
+ * Portable consistency-proof artifact (FOR-368 Phase 3, plan-2607-29):
+ * the "top-up" a holder of an old receipt obtains from ANY party with the
+ * public massif tiles — after which the holder verifies tile-free against
+ * a trusted newer state (`--known-accumulator`).
+ *
+ * Trust model: the artifact is UNSIGNED and untrusted. Soundness comes
+ * from recomputation — the receipt's peak must appear in the artifact's
+ * base accumulator, and folding the artifact's paths from that base
+ * (draft-bryce `consistent_roots`) must land every proven root inside the
+ * TRUSTED target accumulator. A fabricated artifact can only fail; a
+ * passing one proves the old state is a committed prefix of the trusted
+ * state (SCRAPI §2.4's Resolve Receipt provision, made third-party).
+ *
+ * Encoding is strict RFC 8949 §4.2 deterministic CBOR (hard policy).
+ */
+
+/** CBOR map labels for the artifact (strict RFC 8949 §4.2). */
+const LABEL_VERSION = 1;
+const LABEL_FROM_SIZE = 2;
+const LABEL_TO_SIZE = 3;
+const LABEL_ACCUMULATOR_FROM = 4;
+const LABEL_PATHS = 5;
+
+const ARTIFACT_VERSION = 1;
+
+export type ConsistencyProofArtifact = {
+  version: number;
+  /** MMR size the proof extends FROM (the old receipt's era). */
+  fromSize: bigint;
+  /** MMR size the proof lands on — must equal the trusted state's size. */
+  toSize: bigint;
+  /** Full accumulator at `fromSize` (untrusted; proven by the fold). */
+  accumulatorFrom: Uint8Array[];
+  /** One inclusion path per `fromSize` peak, proven at `toSize`. */
+  paths: Uint8Array[][];
+};
+
+export function encodeConsistencyProofArtifact(
+  artifact: ConsistencyProofArtifact,
+): Uint8Array {
+  return encodeCborDeterministic(
+    new Map<number, unknown>([
+      [LABEL_VERSION, artifact.version],
+      [LABEL_FROM_SIZE, artifact.fromSize],
+      [LABEL_TO_SIZE, artifact.toSize],
+      [LABEL_ACCUMULATOR_FROM, artifact.accumulatorFrom],
+      [LABEL_PATHS, artifact.paths],
+    ]),
+  );
+}
+
+function asBigint(v: unknown, what: string): bigint {
+  if (typeof v === "bigint") return v;
+  if (typeof v === "number" && Number.isSafeInteger(v) && v >= 0)
+    return BigInt(v);
+  throw new Error(`consistency proof: ${what} must be an unsigned integer`);
+}
+
+/** Strict decode + structural validation of a top-up artifact. */
+export function decodeConsistencyProofArtifact(
+  bytes: Uint8Array,
+): ConsistencyProofArtifact {
+  let decoded: unknown;
+  try {
+    decoded = decodeCborDeterministic(bytes);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`consistency proof is not canonical CBOR: ${message}`);
+  }
+  if (!(decoded instanceof Map)) {
+    throw new Error("consistency proof must be a CBOR map");
+  }
+  const version = Number(asBigint(decoded.get(LABEL_VERSION), "version"));
+  if (version !== ARTIFACT_VERSION) {
+    throw new Error(`consistency proof version ${version} not supported`);
+  }
+  const fromSize = asBigint(decoded.get(LABEL_FROM_SIZE), "fromSize");
+  const toSize = asBigint(decoded.get(LABEL_TO_SIZE), "toSize");
+  if (fromSize === 0n || toSize <= fromSize) {
+    throw new Error(
+      `consistency proof sizes invalid: from ${fromSize} to ${toSize}`,
+    );
+  }
+  const accRaw = decoded.get(LABEL_ACCUMULATOR_FROM);
+  const pathsRaw = decoded.get(LABEL_PATHS);
+  if (
+    !Array.isArray(accRaw) ||
+    accRaw.some((p) => !(p instanceof Uint8Array) || p.length !== 32)
+  ) {
+    throw new Error(
+      "consistency proof: accumulatorFrom must be 32-byte peaks",
+    );
+  }
+  if (
+    !Array.isArray(pathsRaw) ||
+    pathsRaw.some(
+      (p) => !Array.isArray(p) || p.some((n) => !(n instanceof Uint8Array)),
+    )
+  ) {
+    throw new Error(
+      "consistency proof: paths must be arrays of byte strings",
+    );
+  }
+  const wanted = peakMMRIndexes(fromSize - 1n).length;
+  if (accRaw.length !== wanted || pathsRaw.length !== wanted) {
+    throw new Error(
+      `consistency proof: size ${fromSize} has ${wanted} peaks; got ${accRaw.length} accumulator values and ${pathsRaw.length} paths`,
+    );
+  }
+  return {
+    version,
+    fromSize,
+    toSize,
+    accumulatorFrom: accRaw as Uint8Array[],
+    paths: pathsRaw as Uint8Array[][],
+  };
+}
+
+/**
+ * Node access across one or more massif blobs (a proof spanning massifs
+ * needs nodes from each). First blob covering the index wins; ancestor
+ * peak-stack reads resolve through whichever blob carries them.
+ */
+export function multiMassifNodeGetter(blobs: Uint8Array[]): NodeGetter {
+  const stores = blobs.map((b) => openMassifNodeStore(b));
+  return (i: bigint) => {
+    let lastErr: unknown;
+    for (const store of stores) {
+      try {
+        return store.get(i);
+      } catch (err) {
+        lastErr = err;
+      }
+    }
+    throw new Error(
+      `node ${i} is not covered by the supplied massifs: ${
+        lastErr instanceof Error ? lastErr.message : String(lastErr)
+      }`,
+    );
+  };
+}
+
+/**
+ * Build (and self-verify) a top-up artifact from massif node data. The
+ * builder needs tiles; consumers of the artifact never do.
+ */
+export async function buildConsistencyProofArtifact(opts: {
+  get: NodeGetter;
+  fromSize: bigint;
+  toSize: bigint;
+}): Promise<ConsistencyProofArtifact> {
+  if (opts.fromSize === 0n || opts.toSize <= opts.fromSize) {
+    throw new Error(
+      `--from-size must be > 0 and < --to-size (got ${opts.fromSize} -> ${opts.toSize})`,
+    );
+  }
+  const accumulatorFrom = peakMMRIndexes(opts.fromSize - 1n).map(opts.get);
+  const proof = indexConsistencyProof(
+    opts.get,
+    opts.fromSize - 1n,
+    opts.toSize - 1n,
+  );
+  // Self-check before emitting: the artifact must verify against the
+  // accumulator the same nodes derive at toSize — a coverage gap in the
+  // supplied massifs fails HERE, not at the holder.
+  const accumulatorTo = peakMMRIndexes(opts.toSize - 1n).map(opts.get);
+  const hasher = await createSyncHasher();
+  const check = await verifyConsistency(
+    hasher,
+    proof,
+    accumulatorFrom,
+    accumulatorTo,
+  );
+  if (!check.ok) {
+    throw new Error(
+      "self-verification failed: supplied massifs do not consistently cover the requested range",
+    );
+  }
+  return {
+    version: ARTIFACT_VERSION,
+    fromSize: opts.fromSize,
+    toSize: opts.toSize,
+    accumulatorFrom,
+    paths: proof.paths,
+  };
+}
+
+export type ConsistencyProofAnchorCheck = {
+  anchored: boolean;
+  /** Index of the receipt peak within the artifact's base accumulator. */
+  matchedPeak: number | null;
+  reason?: string;
+};
+
+/**
+ * Tile-free extension of an old receipt to a trusted newer accumulator:
+ * peak ∈ artifact base, then fold the artifact into the trusted target.
+ */
+export async function checkReceiptAnchoredViaConsistencyProof(opts: {
+  artifact: ConsistencyProofArtifact;
+  recomputedPeak: Uint8Array;
+  leafMmrIndex: bigint;
+  /** Trusted target state (e.g. a known-accumulator snapshot). */
+  trustedSize: bigint;
+  trustedAccumulator: Uint8Array[];
+}): Promise<ConsistencyProofAnchorCheck> {
+  const { artifact } = opts;
+  if (artifact.toSize !== opts.trustedSize) {
+    return {
+      anchored: false,
+      matchedPeak: null,
+      reason: "consistency_proof_target_mismatch",
+    };
+  }
+  if (opts.leafMmrIndex >= artifact.fromSize) {
+    return {
+      anchored: false,
+      matchedPeak: null,
+      reason: "receipt_newer_than_consistency_proof_base",
+    };
+  }
+  let matchedPeak: number | null = null;
+  for (let i = 0; i < artifact.accumulatorFrom.length; i++) {
+    if (bytesEqual(opts.recomputedPeak, artifact.accumulatorFrom[i]!)) {
+      matchedPeak = i;
+      break;
+    }
+  }
+  if (matchedPeak === null) {
+    return {
+      anchored: false,
+      matchedPeak: null,
+      reason: "peak_not_in_consistency_proof_base",
+    };
+  }
+  const hasher = await createSyncHasher();
+  const check = await verifyConsistency(
+    hasher,
+    {
+      mmrSizeA: artifact.fromSize,
+      mmrSizeB: artifact.toSize,
+      paths: artifact.paths,
+    },
+    artifact.accumulatorFrom,
+    opts.trustedAccumulator,
+  );
+  if (!check.ok) {
+    return {
+      anchored: false,
+      matchedPeak: null,
+      reason: "consistency_proof_invalid",
+    };
+  }
+  return { anchored: true, matchedPeak };
+}
+

package/src/lib/create-log-build.ts

@@ -0,0 +1,168 @@
+/**
+ * FOR-390 / ADR-0052 create-log grant assembly: build the grant that CREATES
+ * a log and sets its owner (K(L)). Lifted out of the old register-grant-build
+ * (plan-2607-21) — register-grant is now writer-only.
+ *
+ * Three shapes, all `GF_CREATE|GF_EXTEND` in byte 3 (grants.md §5):
+ *
+ * - `--self-referential` — root bootstrap leaf (`logId == ownerLogId`); the
+ *   grant is its own authority, so grantData IS the envelope signer and
+ *   `--signer-pem` is forbidden. Auth-log shaped (`authLogBootstrapShapedFlags`).
+ * - `--auth-log` — create a child auth log; grantData = `--signer-pem` (the new
+ *   log's owner). Auth-log shaped (`authLogBootstrapShapedFlags`).
+ * - default — create a data log; grantData = `--signer-pem`. Data-log shaped
+ *   (`dataLogCreateExtendFlags`).
+ *
+ * Auth-shaped grants may additionally carry
+ * `GF_DERIVED | GF_CHILD_PAYMENT_REQUIRED` (`--child-payment-required`,
+ * adr-0062/plan-2608-09): child grants registered under the new log's
+ * authority are then x402 payment-gated when a lane enables admission.
+ *
+ * grantData is the new log owner's ES256 `x||y`. Reuses the register-grant
+ * ES256 PEM parser and error class. Node-only (node:crypto PEM handling); no
+ * HTTP, no env.
+ */
+import {
+  authLogBootstrapShapedFlags,
+  bytesToForestrieGrantBase64,
+  dataLogCreateExtendFlags,
+  signGrantPayloadWithEs256Pem,
+  withChildPaymentRequired,
+} from "@forestrie/grant-builder";
+import {
+  encodeGrantPayloadV0Canonical,
+  uuidToBytes,
+  type Grant,
+} from "@forestrie/encoding";
+import {
+  RegisterGrantBuildError,
+  es256PublicKeyXyFromPem,
+} from "./register-grant-build.js";
+
+export { RegisterGrantBuildError };
+
+export type BuildCreateLogGrantParams = {
+  /** The log being created (`grant.logId`, UUID). */
+  newLog: string;
+  /** Parent/auth log the create grant is sequenced into (`grant.ownerLogId`, UUID). */
+  ownerLog: string;
+  /** PKCS#8/SEC1 ES256 PEM that signs the grant envelope (the granting authority, K(L)). */
+  signWithPem: string;
+  /**
+   * PEM of the new log's owner (`grantData` = ES256 x||y). Required unless
+   * `--self-referential` (which binds the `--sign-with` key itself).
+   */
+  signerPem?: string | undefined;
+  /** Root bootstrap: first leaf of the root log, `logId == ownerLogId`. */
+  selfReferential: boolean;
+  /** Create a child auth log (auth-log flag class) rather than a data log. */
+  authLog: boolean;
+  /**
+   * Set `GF_DERIVED | GF_CHILD_PAYMENT_REQUIRED` (univocity bits 34/35) on the
+   * creation grant, declaring that child grants registered under this log's
+   * authority require an x402 payment (adr-0062, plan-2608-09). Auth-shaped
+   * grants only — a data log is never the parent authority of a child grant.
+   */
+  childPaymentRequired?: boolean | undefined;
+};
+
+export type BuiltCreateLogGrant = {
+  /** Signed grant transparent statement, Forestrie-Grant header base64. */
+  grantBase64: string;
+  /** Canonical grant v0 payload CBOR (keys 1-6) that was signed. */
+  grantPayloadBytes: Uint8Array;
+  /** The new log owner this grant commits (ES256 x||y, 64 bytes). */
+  grantData: Uint8Array;
+  /** 8-byte GF_* flags bitmap that went on the wire. */
+  flags: Uint8Array;
+};
+
+/**
+ * Build and sign the create-log grant transparent statement: canonical grant
+ * v0 CBOR (`encodeGrantPayloadV0Canonical`) with `GF_CREATE|GF_EXTEND` flags,
+ * signed via the Custodian ES256 PEM profile (`signGrantPayloadWithEs256Pem`),
+ * returned as `Authorization: Forestrie-Grant` base64.
+ */
+export function buildCreateLogGrant(
+  params: BuildCreateLogGrantParams,
+): BuiltCreateLogGrant {
+  let logId: Uint8Array;
+  let ownerLogId: Uint8Array;
+  try {
+    logId = uuidToBytes(params.newLog);
+  } catch {
+    throw new RegisterGrantBuildError(`--new-log is not a UUID: ${params.newLog}`);
+  }
+  try {
+    ownerLogId = uuidToBytes(params.ownerLog);
+  } catch {
+    throw new RegisterGrantBuildError(
+      `--owner-log is not a UUID: ${params.ownerLog}`,
+    );
+  }
+
+  if (params.selfReferential) {
+    // Root bootstrap shape: the grant is its own authority (first leaf of the
+    // root log), so the new log IS the owner and grantData IS the envelope
+    // signer (arbor's root-grant check compares them).
+    if (params.newLog.toLowerCase() !== params.ownerLog.toLowerCase()) {
+      throw new RegisterGrantBuildError(
+        "--self-referential requires --new-log and --owner-log to be the same log (logId == ownerLogId)",
+      );
+    }
+    if (params.signerPem !== undefined) {
+      throw new RegisterGrantBuildError(
+        "--self-referential grants bind the --sign-with key itself; omit --signer-pem",
+      );
+    }
+  } else if (params.signerPem === undefined) {
+    throw new RegisterGrantBuildError(
+      "--signer-pem is required (the new log's owner) unless --self-referential",
+    );
+  }
+
+  // The new log owner's public key is the committed grantData; the
+  // self-referential bootstrap binds the granting key itself.
+  const grantData = es256PublicKeyXyFromPem(
+    params.signerPem ?? params.signWithPem,
+  );
+
+  let flags =
+    params.authLog || params.selfReferential
+      ? authLogBootstrapShapedFlags()
+      : dataLogCreateExtendFlags();
+  if (params.childPaymentRequired === true) {
+    if (!params.authLog && !params.selfReferential) {
+      throw new RegisterGrantBuildError(
+        "--child-payment-required applies to auth logs (--auth-log or --self-referential); a data log is never the parent authority of a child grant",
+      );
+    }
+    flags = withChildPaymentRequired(flags);
+  }
+
+  const grant: Grant = {
+    logId,
+    ownerLogId,
+    grant: flags,
+    maxHeight: 0,
+    minGrowth: 0,
+    grantData,
+  };
+  const grantPayloadBytes = encodeGrantPayloadV0Canonical(grant);
+  let sign1: Uint8Array;
+  try {
+    sign1 = signGrantPayloadWithEs256Pem(grantPayloadBytes, params.signWithPem);
+  } catch (err) {
+    throw new RegisterGrantBuildError(
+      `--sign-with key rejected: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+  }
+  return {
+    grantBase64: bytesToForestrieGrantBase64(sign1),
+    grantPayloadBytes,
+    grantData,
+    flags,
+  };
+}

package/src/lib/create-log-prepare.ts

@@ -0,0 +1,75 @@
+/**
+ * FOR-390 / ADR-0053: pre-register a child log's public root with the delegation
+ * coordinator under PARENT authority, WITHOUT sequencing the create leaf.
+ *
+ * The parent-signed create grant travels as the `Authorization: Forestrie-Grant`
+ * credential; canopy-api verifies it against the parent log's registered root key
+ * and forwards `{childLogId -> owner key}` to the coordinator. This lets an owner
+ * pre-sign an advance delegation (`forestrie delegate`) for a child logId BEFORE
+ * the log exists — no operator onboard token, authority flows down the log
+ * hierarchy (ADR-0053). Node/Bun HTTP only.
+ */
+
+/** Prepare (child public-root pre-registration) failure. */
+export class PrepareLogError extends Error {
+  readonly httpStatus?: number;
+  constructor(message: string, httpStatus?: number) {
+    super(message);
+    this.name = "PrepareLogError";
+    if (httpStatus !== undefined) this.httpStatus = httpStatus;
+  }
+}
+
+/** Coordinator forward outcome (best-effort parse of the prepare response). */
+export type PrepareResult = {
+  /** "ok" when the child public root was registered with the coordinator. */
+  publicRoot: string;
+  /** "ok" | "skipped" | "error" when a signing-route webhook was set. */
+  webhook?: string | undefined;
+  detail?: string | undefined;
+};
+
+export type PrepareDeps = { fetchImpl?: typeof fetch | undefined };
+
+/**
+ * POST the parent-signed create grant to
+ * `POST /api/forest/{childLogId}/prepare` (Authorization: Forestrie-Grant), which
+ * registers the child's public root with the coordinator under parent authority.
+ * Returns the coordinator forward status; throws {@link PrepareLogError} on non-2xx.
+ */
+export async function prepareChildLog(
+  params: { baseUrl: string; childLogId: string; grantBase64: string },
+  deps: PrepareDeps = {},
+): Promise<PrepareResult> {
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  const url = `${params.baseUrl.replace(/\/$/, "")}/api/forest/${params.childLogId}/prepare`;
+  const res = await fetchImpl(url, {
+    method: "POST",
+    headers: { Authorization: `Forestrie-Grant ${params.grantBase64}` },
+  });
+  if (!res.ok) {
+    const preview = (await res.text().catch(() => "")).slice(0, 300);
+    throw new PrepareLogError(
+      `prepare failed: HTTP ${res.status} ${preview}`,
+      res.status,
+    );
+  }
+  // Lenient: the endpoint returns the coordinator forward status (JSON or CBOR).
+  // A 2xx alone means the public root was registered; extract fields when the
+  // body is JSON-parseable, else report a generic success.
+  let publicRoot = "ok";
+  let webhook: string | undefined;
+  let detail: string | undefined;
+  try {
+    const body = (await res.json()) as Record<string, unknown> & {
+      coordinator?: Record<string, unknown>;
+    };
+    const src = (body.coordinator ?? body) as Record<string, unknown>;
+    if (typeof src.publicRoot === "string") publicRoot = src.publicRoot;
+    if (typeof src.webhook === "string") webhook = src.webhook;
+    if (typeof src.detail === "string") detail = src.detail;
+  } catch {
+    // non-JSON (e.g. CBOR) — 2xx is success.
+  }
+  return { publicRoot, webhook, detail };
+}