@forestrie/forestrie-cli 0.8.0

package/src/lib/register-grant-build.ts

@@ -0,0 +1,173 @@
+/**
+ * FOR-343 writer-grant statement assembly: deterministic Forestrie-Grant v0
+ * construction on top of `@forestrie/grant-builder` / `@forestrie/encoding`.
+ *
+ * This module is now WRITER-ONLY (ADR-0052 / plan-2607-21): it authorizes one
+ * statement signer on an existing data log, emitting an EXTEND-ONLY grant
+ * (byte 3 = `GF_EXTEND`, byte 7 = `GF_DATA_LOG`). Log creation and the
+ * bootstrap self-referential / auth-log shapes moved to `create-log`
+ * (`create-log-build.ts`).
+ *
+ * A grant binds exactly ONE signer (`grantData` = the signer's ES256 `x||y`);
+ * several signers on one data log means several grants, each naming that log.
+ * The grant leaf is sequenced into the OWNER (auth) log (`ownerLogId`); the
+ * target/data log holds only statements. Flag shape follows grants.md §5:
+ * writer grant → `GF_EXTEND` + `GF_DATA_LOG` (`dataLogExtendFlags`, the local
+ * bridge in `grant-flags-local.ts`).
+ *
+ * ES256 is the paved path (mirrors grant-builder's node-only
+ * `es256-pem-grant` profile: COSE Sign1 with a 32-byte digest payload and
+ * the full grant v0 CBOR in unprotected -65538).
+ *
+ * Node-only module (node:crypto PEM handling); no HTTP, no env.
+ */
+import { createPublicKey } from "node:crypto";
+import { parsePemResilient } from "./openssl-error-queue.js";
+import {
+  bytesToForestrieGrantBase64,
+  signGrantPayloadWithEs256Pem,
+} from "@forestrie/grant-builder";
+import {
+  encodeGrantPayloadV0Canonical,
+  uuidToBytes,
+  type Grant,
+} from "@forestrie/encoding";
+import { dataLogExtendFlags } from "./grant-flags-local.js";
+
+/** Grant construction failure (bad key material / inconsistent shape). */
+export class RegisterGrantBuildError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "RegisterGrantBuildError";
+  }
+}
+
+const ES256_XY_BYTES = 64;
+
+function base64UrlToBytes(b64url: string): Uint8Array {
+  return new Uint8Array(Buffer.from(b64url, "base64url"));
+}
+
+/**
+ * ES256 P-256 public key as uncompressed `x||y` (64 bytes) from a PEM.
+ * Accepts a public (SPKI) PEM or a private (SEC1/PKCS#8) PEM — the demo
+ * flow points `--signer-pem` at the same key file `sign-statement --key`
+ * uses, and the authorized signer's PUBLIC key is all the grant commits
+ * to (grant-builder only ships the private-PEM variant).
+ */
+export function es256PublicKeyXyFromPem(pem: string): Uint8Array {
+  let jwk: { crv?: string; x?: unknown; y?: unknown };
+  try {
+    // `parsePemResilient` retries once so a valid key is never rejected
+    // because the OpenSSL error queue was poisoned elsewhere (FOR-343).
+    jwk = parsePemResilient(() =>
+      createPublicKey({ key: pem, format: "pem" }),
+    ).export({
+      format: "jwk",
+    });
+  } catch (err) {
+    throw new RegisterGrantBuildError(
+      `not an EC PEM (public or private): ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+  }
+  if (jwk.crv !== "P-256" || typeof jwk.x !== "string" || typeof jwk.y !== "string") {
+    throw new RegisterGrantBuildError(
+      "signer key must be a P-256 (ES256) EC key",
+    );
+  }
+  const x = base64UrlToBytes(jwk.x);
+  const y = base64UrlToBytes(jwk.y);
+  if (x.length !== 32 || y.length !== 32) {
+    throw new RegisterGrantBuildError(
+      "ES256 public key coordinates must be 32 bytes each",
+    );
+  }
+  const out = new Uint8Array(ES256_XY_BYTES);
+  out.set(x, 0);
+  out.set(y, 32);
+  return out;
+}
+
+export type BuildGrantStatementParams = {
+  /** Target data log the grant authorizes (`grant.logId`, UUID). */
+  targetLog: string;
+  /** Owner (auth) log the grant leaf is sequenced into (`grant.ownerLogId`, UUID). */
+  ownerLog: string;
+  /** PKCS#8/SEC1 ES256 PEM that signs the grant envelope (the granting authority). */
+  signWithPem: string;
+  /** PEM of the ONE signer being authorized (`grantData` = ES256 x||y). */
+  signerPem: string;
+};
+
+export type BuiltGrantStatement = {
+  /** Signed grant transparent statement, Forestrie-Grant header base64. */
+  grantBase64: string;
+  /** Canonical grant v0 payload CBOR (keys 1-6) that was signed. */
+  grantPayloadBytes: Uint8Array;
+  /** The ONE authorized signer this grant binds (ES256 x||y, 64 bytes). */
+  grantData: Uint8Array;
+  /** 8-byte GF_* flags bitmap that went on the wire. */
+  flags: Uint8Array;
+};
+
+/**
+ * Build and sign the writer grant transparent statement:
+ * canonical grant v0 CBOR (`encodeGrantPayloadV0Canonical`) with EXTEND-ONLY
+ * data-log flags, signed via the Custodian ES256 PEM profile
+ * (`signGrantPayloadWithEs256Pem`), returned as `Authorization:
+ * Forestrie-Grant` base64.
+ */
+export function buildGrantStatement(
+  params: BuildGrantStatementParams,
+): BuiltGrantStatement {
+  let logId: Uint8Array;
+  let ownerLogId: Uint8Array;
+  try {
+    logId = uuidToBytes(params.targetLog);
+  } catch {
+    throw new RegisterGrantBuildError(
+      `--data-log is not a UUID: ${params.targetLog}`,
+    );
+  }
+  try {
+    ownerLogId = uuidToBytes(params.ownerLog);
+  } catch {
+    throw new RegisterGrantBuildError(
+      `--owner-log is not a UUID: ${params.ownerLog}`,
+    );
+  }
+
+  // One grant, ONE signer: the authorized signer's public key is the
+  // committed grantData. Writer grants always name an explicit signer.
+  const grantData = es256PublicKeyXyFromPem(params.signerPem);
+
+  const flags = dataLogExtendFlags();
+
+  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/register-grant-complete.ts

@@ -0,0 +1,47 @@
+/**
+ * FOR-343 completed-grant assembly: once the grant leaf is sequenced and
+ * the receipt resolved, the *completed* grant is the original signed grant
+ * statement with the receipt (header 396) and the entry's idtimestamp
+ * (header -65537) merged into the UNPROTECTED headers — no re-signing
+ * (mirrors e2e-kit `buildCompletedGrantBase64`). The completed grant is
+ * the `Authorization: Forestrie-Grant` bearer used by `forestrie register`.
+ */
+import {
+  HEADER_IDTIMESTAMP,
+  HEADER_RECEIPT,
+  base64ToBytes,
+  bytesToForestrieGrantBase64,
+} from "@forestrie/grant-builder";
+import { mergeUnprotectedIntoCoseSign1 } from "@forestrie/encoding";
+
+const ENTRY_ID_HEX_RE = /^[0-9a-f]{32}$/i;
+
+/**
+ * First half of the permanent 32-hex-char entry id (idtimestamp_be8 ||
+ * mmrIndex_be8): the 8 idtimestamp bytes for unprotected header -65537.
+ */
+export function entryIdHexToIdtimestampBe8(entryIdHex: string): Uint8Array {
+  if (!ENTRY_ID_HEX_RE.test(entryIdHex)) {
+    throw new Error(`entryId must be 32 hex chars: ${entryIdHex}`);
+  }
+  return Uint8Array.from(Buffer.from(entryIdHex.slice(0, 16), "hex"));
+}
+
+/**
+ * Attach receipt + idtimestamp to the signed grant statement, returning
+ * the completed grant as Forestrie-Grant header base64.
+ */
+export function completeGrantBase64(
+  grantBase64: string,
+  receiptBytes: Uint8Array,
+  entryIdHex: string,
+): string {
+  const completed = mergeUnprotectedIntoCoseSign1(
+    base64ToBytes(grantBase64),
+    new Map<number, unknown>([
+      [HEADER_RECEIPT, receiptBytes],
+      [HEADER_IDTIMESTAMP, entryIdHexToIdtimestampBe8(entryIdHex)],
+    ]),
+  );
+  return bytesToForestrieGrantBase64(completed);
+}

package/src/lib/register-grant-flow.ts

@@ -0,0 +1,258 @@
+/**
+ * FOR-343 grant registration flow: POST the signed grant statement to
+ * `POST /register/{bootstrapLogId}/grants` (`@forestrie/scrapi-client`
+ * `registerGrant` — the parent grant evidence travels in the CBOR body as
+ * `{ parentGrant: <bytes> }`, grants.md §11), then drive the same SCRAPI
+ * 303 receipt-redirect contract as `register-flow.ts` to completion.
+ *
+ * The pacing/timeout/error taxonomy deliberately MIRRORS
+ * `register-flow.ts` (F4, plan-2607-14 W1.4): scrapi-client ships
+ * poll-once primitives with NO sleep loops, this module owns the pacing,
+ * every request is bounded by an AbortSignal tied to the remaining
+ * `--timeout` budget, and fetch-level failures map into the shared
+ * {@link RegisterFlowError} stages instead of escaping as bare TypeErrors.
+ * `boundedFetch` is not exported from register-flow, so it is mirrored
+ * here (kept private there by design).
+ */
+import {
+  ScrapiRegistrationError,
+  queryRegistrationOnce,
+  registerGrant,
+  resolveReceiptOnce,
+  toAbsoluteScrapiUrl,
+} from "@forestrie/scrapi-client";
+import { RegisterFlowError } from "./register-flow.js";
+
+export { RegisterFlowError };
+
+/** Progress callbacks so the CLI can narrate long polls on stderr. */
+export type RegisterGrantProgress =
+  | { 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 RegisterGrantFlowDeps = {
+  fetchImpl?: typeof fetch;
+  sleep?: (ms: number) => Promise<void>;
+  now?: () => number;
+  onProgress?: (progress: RegisterGrantProgress) => void;
+};
+
+export type RegisterGrantFlowParams = {
+  /** SCRAPI origin, no trailing slash. */
+  baseUrl: string;
+  /** Forest bootstrap/root log id — first `/register/` path segment. */
+  bootstrapLogId: string;
+  /** Signed grant transparent statement, Forestrie-Grant header base64. */
+  grantBase64: string;
+  /**
+   * Completed parent grant (base64) authorizing this registration; sent
+   * in the CBOR request body (grants.md §11). Absent for the
+   * self-referential bootstrap leaf.
+   */
+  parentGrantBase64?: string | undefined;
+  /** Overall budget covering both poll phases. */
+  timeoutMs: number;
+  /** Pacing between polls; a longer `Retry-After` wins. */
+  pollIntervalMs: number;
+};
+
+export type RegisterGrantFlowResult = {
+  /** 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;
+}
+
+/**
+ * Mirror of register-flow's F4 bounded fetch: every request carries an
+ * AbortSignal tied to the remaining `--timeout` budget, and fetch-level
+ * failures (ECONNREFUSED, DNS, resets) map into the RegisterFlowError
+ * taxonomy. Real wall-clock timer; `remaining` from the injectable `now`.
+ */
+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 grant 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 the grant 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 runRegisterGrantFlow(
+  params: RegisterGrantFlowParams,
+  deps: RegisterGrantFlowDeps = {},
+): Promise<RegisterGrantFlowResult> {
+  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 grant receipt`,
+        { stage: "timeout", ...info },
+      );
+    }
+    await sleep(waitMs);
+  };
+
+  // 1. POST /register/{bootstrapLogId}/grants — only 303 + Location succeeds.
+  let statusUrl: string;
+  try {
+    ({ statusUrl } = await registerGrant({
+      baseUrl: params.baseUrl,
+      bootstrapLogId: params.bootstrapLogId,
+      grantBase64: params.grantBase64,
+      ...(params.parentGrantBase64 !== undefined
+        ? { parentGrantBase64: params.parentGrantBase64 }
+        : {}),
+      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 });
+  }
+}

package/src/lib/resolve-receipt-freshen.ts

@@ -0,0 +1,221 @@
+/**
+ * Tile-free freshen for `resolve-receipt` (FOR-418 Phase 3c, plan-2607-32 D1/D3).
+ *
+ * "Freshen" is `resolve-receipt --receipt <stale> + a tile-free source`: re-anchor
+ * a stale receipt to the CURRENT sealed state without massif tiles. The stale
+ * receipt supplies the leaf's MMR index and its old inclusion path (leaf → old
+ * peak); a checkpoint chain supplies the climb from that old peak to the current
+ * accumulator; the latest checkpoint supplies the emission signature. The result
+ * is a native receipt that verifies with the offline verifier.
+ *
+ * A freshened receipt is a NEW attestation of the CURRENT accumulator, so the
+ * only signature it can carry is one over a checkpoint at the current size — the
+ * latest checkpoint's signer, necessarily (anything else would be forgery). This
+ * is not a signer "downgrade": the log authorises a SET of sealers and the
+ * contract enforces membership at publish; ranking them is out-of-band verify-
+ * time policy, not a freshen concern. See the receipt trust model:
+ * https://github.com/forestrie/protocol/blob/main/spec/receipt-trust-model.md
+ *
+ * The leaf VALUE is not in the stale receipt (its payload is detached — verify
+ * recomputes it), so freshen recomputes it exactly as `verify` does:
+ * `univocityLeafHash(idtimestamp, inner)` (see the `inner` note below).
+ * `freshenReceipt` needs it for its fail-closed self-check (recomputed peak ==
+ * folded accumulator peak), so a bad chain/leaf throws here rather than minting
+ * a bad receipt.
+ *
+ * Two tile-free climb sources, both folding to `freshenReceipt`:
+ * - **`.sth` chain** (`freshenFromSthChain`): retained checkpoints; the chain's
+ *   own tail is the emission checkpoint (self-contained, no separate artifact).
+ * - **chain calldata** (`freshenFromCalldataChain`): the `publishCheckpoint`
+ *   transactions carry the consistency-proof chain (authority already checked
+ *   on-chain at publish). Calldata carries no pre-signed peak receipts / cert, so
+ *   emission still needs a latest `.sth` supplied separately.
+ */
+import {
+  freshenReceipt,
+  parseReceipt,
+} from "@forestrie/receipt-verify";
+import {
+  calldataCheckpointChain,
+  sthCheckpointChain,
+  type CheckpointLink,
+} from "./checkpoint-provider.js";
+import { univocityLeafHash } from "./verify-anchored.js";
+import { bytesEqual } from "./bytes.js";
+import type { KnownAccumulator } from "./verify-known-accumulator.js";
+
+function accumulatorsEqual(a: Uint8Array[], b: Uint8Array[]): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) if (!bytesEqual(a[i]!, b[i]!)) return false;
+  return true;
+}
+
+/** Structured detail for the `--json` report and human narration. */
+export type FreshenDetails = {
+  /** The stale receipt's leaf, addressed by MMR index. */
+  leafMmrIndex: bigint;
+  /** Sealed size the freshened receipt is anchored at (latest checkpoint). */
+  sealedSize: bigint;
+  /** Number of consistency-proof links folded from the chain. */
+  chainLinks: number;
+  /** Length of the emitted (extended) inclusion path. */
+  proofLength: number;
+  /** The chain sources, ascending (`.sth` filenames or tx hashes), for narration. */
+  sourceRefs: string[];
+  /** The folded latest accumulator matched a `--known-accumulator` snapshot
+   * (present only when one was supplied). */
+  knownAccumulatorMatched?: boolean;
+};
+
+export type FreshenResult = {
+  receiptCbor: Uint8Array;
+  details: FreshenDetails;
+};
+
+// The leaf value the freshened receipt must root to is recomputed exactly as
+// `verify` does: `univocityLeafHash(idtimestamp, inner)`, where `inner` is the
+// leaf ContentHash — `SHA-256(payload)` for a statement, or the grant commitment
+// hash for a grant. The caller supplies `inner`, so freshen is source-agnostic.
+
+/**
+ * Shared emission: take the provider's links + a latest checkpoint, extend the
+ * stale receipt's path, and re-emit. `freshenReceipt` cross-checks the chain
+ * against the latest checkpoint and self-checks the recomputed peak.
+ *
+ * When a `knownAccumulator` is supplied, the folded latest accumulator is bound
+ * to that trusted snapshot BEFORE the receipt is returned: the state we folded
+ * must equal the snapshot at the same size, or we fail closed. This anchors
+ * FRESHNESS (a chain-captured `logState`, `fetch-accumulator`) — it confirms the
+ * leaf roots into the genuine current state, orthogonal to signer provenance and
+ * needing no genesis walk. For the calldata source (whose fold is already cross-
+ * checked against the on-chain `CheckpointPublished` accumulator), it adds an
+ * independent, RPC-agnostic anchor that catches a lying/stale RPC.
+ */
+async function emitFreshened(opts: {
+  oldReceiptBytes: Uint8Array;
+  leafValue: Uint8Array;
+  links: readonly CheckpointLink[];
+  latestCheckpointBytes: Uint8Array;
+  sourceRefs: string[];
+  knownAccumulator?: KnownAccumulator | undefined;
+}): Promise<FreshenResult> {
+  const result = await freshenReceipt({
+    oldReceiptBytes: opts.oldReceiptBytes,
+    leafValue: opts.leafValue,
+    consistencyProofs: opts.links.map((l) => l.proof),
+    latestCheckpointBytes: opts.latestCheckpointBytes,
+  });
+
+  let knownAccumulatorMatched: boolean | undefined;
+  if (opts.knownAccumulator !== undefined) {
+    const snap = opts.knownAccumulator;
+    const aLatest = opts.links[opts.links.length - 1]!.accumulator;
+    if (snap.size !== result.sealedSize) {
+      throw new Error(
+        `--known-accumulator is size ${snap.size} but the freshened state is size ${result.sealedSize} — capture a snapshot at the current sealed size (freshen cannot extend tile-free)`,
+      );
+    }
+    if (!accumulatorsEqual(aLatest, snap.accumulator)) {
+      throw new Error(
+        "freshened accumulator does not match --known-accumulator — the chain/checkpoint disagrees with your trusted snapshot",
+      );
+    }
+    knownAccumulatorMatched = true;
+  }
+
+  const { proof } = parseReceipt(result.receipt);
+  return {
+    receiptCbor: result.receipt,
+    details: {
+      leafMmrIndex: proof.mmrIndex!,
+      sealedSize: result.sealedSize,
+      chainLinks: opts.links.length,
+      proofLength: proof.path.length,
+      sourceRefs: opts.sourceRefs,
+      ...(knownAccumulatorMatched !== undefined ? { knownAccumulatorMatched } : {}),
+    },
+  };
+}
+
+/**
+ * Freshen a stale receipt against a retained `.sth` checkpoint chain.
+ *
+ * `checkpoints` are the raw `.sth` bytes in ascending massif order (a contiguous
+ * chain from the log's base); the last checkpoint is the emission checkpoint.
+ * `sourceRefs` optionally names them. Throws (with the underlying reason) if the
+ * chain is not a contiguous cover to the leaf, if the chain does not match the
+ * latest checkpoint, or if the recomputed peak does not match the fold.
+ */
+export async function freshenFromSthChain(opts: {
+  oldReceiptBytes: Uint8Array;
+  /** Leaf ContentHash: `SHA-256(payload)` (statement) or the grant commitment. */
+  inner: Uint8Array;
+  idtimestampBe8: Uint8Array;
+  checkpoints: readonly Uint8Array[];
+  sourceRefs?: readonly string[];
+  knownAccumulator?: KnownAccumulator | undefined;
+}): Promise<FreshenResult> {
+  if (opts.checkpoints.length === 0) {
+    throw new Error("--checkpoint-chain resolved to no checkpoints");
+  }
+  const leafValue = await univocityLeafHash(opts.idtimestampBe8, opts.inner);
+  const links = await sthCheckpointChain(
+    opts.checkpoints,
+    opts.sourceRefs !== undefined ? { sourceRefs: opts.sourceRefs } : {},
+  );
+  return emitFreshened({
+    oldReceiptBytes: opts.oldReceiptBytes,
+    leafValue,
+    links,
+    latestCheckpointBytes: opts.checkpoints[opts.checkpoints.length - 1]!,
+    sourceRefs: [...(opts.sourceRefs ?? [])],
+    knownAccumulator: opts.knownAccumulator,
+  });
+}
+
+/**
+ * Freshen a stale receipt against the on-chain `publishCheckpoint` calldata.
+ *
+ * Reads the log's checkpoint chain from the `CheckpointPublished` transactions
+ * (trustless climb material — the on-chain publish already discharged sealing +
+ * grant authority), then re-emits under `latestCheckpointBytes` — a latest `.sth`
+ * supplied by the caller, because the calldata carries no pre-signed peak
+ * receipts or delegation cert. The calldata chain's sealed size must equal the
+ * latest checkpoint's (enforced by `freshenReceipt`). Freshness is anchored by
+ * the fold (and, if supplied, `--known-accumulator`); signer provenance is a
+ * verify-time question. See the receipt trust model:
+ * https://github.com/forestrie/protocol/blob/main/spec/receipt-trust-model.md
+ */
+export async function freshenFromCalldataChain(opts: {
+  oldReceiptBytes: Uint8Array;
+  /** Leaf ContentHash: `SHA-256(payload)` (statement) or the grant commitment. */
+  inner: Uint8Array;
+  idtimestampBe8: Uint8Array;
+  univocity: string;
+  logId: string;
+  rpcUrl: string;
+  latestCheckpointBytes: Uint8Array;
+  knownAccumulator?: KnownAccumulator | undefined;
+  fetchImpl?: typeof fetch;
+}): Promise<FreshenResult> {
+  const leafValue = await univocityLeafHash(opts.idtimestampBe8, opts.inner);
+  const links = await calldataCheckpointChain({
+    univocity: opts.univocity,
+    logId: opts.logId,
+    rpcUrl: opts.rpcUrl,
+    ...(opts.fetchImpl !== undefined ? { fetchImpl: opts.fetchImpl } : {}),
+  });
+  if (links.length === 0) {
+    throw new Error(
+      "no CheckpointPublished history found on-chain for this log — nothing to freshen against",
+    );
+  }
+  return emitFreshened({
+    oldReceiptBytes: opts.oldReceiptBytes,
+    leafValue,
+    links,
+    latestCheckpointBytes: opts.latestCheckpointBytes,
+    sourceRefs: links.map((l) => l.sourceRef ?? ""),
+    knownAccumulator: opts.knownAccumulator,
+  });
+}