@forestrie/forestrie-cli 0.8.0

package/src/lib/decode-receipt-render.ts

@@ -0,0 +1,284 @@
+/**
+ * Human rendering for `forestrie decode-receipt` (FOR-346).
+ *
+ * The demo money-shot: an annotated tree that makes the receipt legible
+ * to an audience — it's just COSE (Sign1 + MMR inclusion). Works purely
+ * from the display model so `--json` and the tree always agree.
+ */
+
+import type {
+  DecodedHeaderEntry,
+  DecodedReceipt,
+  Json,
+} from "./decode-receipt-decode.js";
+import {
+  CWT_CLAIMS_LABEL,
+  DELEGATION_CERT_LABEL,
+  PROOF_KIND_NAMES,
+  SEAL_PEAK_RECEIPTS_LABEL,
+  VDS_LABEL,
+  VERIFIABLE_PROOFS_LABEL,
+} from "./decode-receipt-labels.js";
+
+/** Shorten `h'…'` / hex strings for tree display; JSON keeps full bytes. */
+function shortHex(hex: string, keepBytes = 8): string {
+  const byteLength = hex.length / 2;
+  if (byteLength <= keepBytes * 2) return hex;
+  return `${hex.slice(0, keepBytes * 2)}…${hex.slice(-4)}`;
+}
+
+function describeJson(value: Json): string {
+  if (typeof value === "string") {
+    const bytes = /^h'([0-9a-f]*)'$/.exec(value);
+    if (bytes) {
+      const hex = bytes[1] ?? "";
+      return `${shortHex(hex)} (${hex.length / 2} bytes)`;
+    }
+    return JSON.stringify(value);
+  }
+  if (value === null) return "null";
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  if (Array.isArray(value)) {
+    if (value.length === 0) return "[]";
+    return `array of ${value.length}`;
+  }
+  return `map of ${Object.keys(value).length}`;
+}
+
+function labelPrefix(entry: DecodedHeaderEntry): string {
+  return entry.name !== null
+    ? `${entry.label} (${entry.name})`
+    : `${entry.label} (unknown label)`;
+}
+
+type Line = { depth: number; text: string; last?: boolean };
+
+/** Render one unprotected 396 verifiable-proofs map as sub-lines. */
+function proofLines(
+  value: Json,
+  receipt: DecodedReceipt,
+  depth: number,
+): Line[] {
+  const lines: Line[] = [];
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    lines.push({ depth, text: describeJson(value) });
+    return lines;
+  }
+  for (const [key, entry] of Object.entries(value)) {
+    const kind = PROOF_KIND_NAMES.get(Number(key));
+    const head = kind ? `${key} (${kind})` : `${key} (unknown proof kind)`;
+    if (Number(key) === -1) {
+      // Inclusion proofs — expand from the verified summary.
+      lines.push({ depth, text: `${head}: 1 entry` });
+      lines.push({
+        depth: depth + 1,
+        text: `1 (mmr index): ${receipt.inclusion.mmrIndex}`,
+      });
+      lines.push({
+        depth: depth + 1,
+        text: `2 (path): ${receipt.inclusion.pathLength} × 32-byte hashes`,
+      });
+      for (const [i, hash] of receipt.inclusion.path.entries()) {
+        lines.push({ depth: depth + 2, text: `[${i}] ${shortHex(hash)}` });
+      }
+      continue;
+    }
+    lines.push({ depth, text: `${head}: ${describeJson(entry)}` });
+  }
+  return lines;
+}
+
+function unprotectedLines(
+  entry: DecodedHeaderEntry,
+  receipt: DecodedReceipt,
+  depth: number,
+): Line[] {
+  if (entry.label === VERIFIABLE_PROOFS_LABEL) {
+    return [
+      { depth, text: `${labelPrefix(entry)}:` },
+      ...proofLines(entry.value, receipt, depth + 1),
+    ];
+  }
+  if (
+    entry.label === DELEGATION_CERT_LABEL &&
+    receipt.unprotected.delegation
+  ) {
+    const d = receipt.unprotected.delegation;
+    const nested = d.nestedCoseSign1
+      ? " — parses as a nested COSE_Sign1"
+      : "";
+    return [
+      {
+        depth,
+        text: `${labelPrefix(entry)}: ${d.byteLength} bytes${nested}`,
+      },
+    ];
+  }
+  if (
+    entry.label === SEAL_PEAK_RECEIPTS_LABEL &&
+    receipt.unprotected.peakReceipts
+  ) {
+    return [
+      {
+        depth,
+        text: `${labelPrefix(entry)}: ${receipt.unprotected.peakReceipts.count} receipts`,
+      },
+    ];
+  }
+  return [{ depth, text: `${labelPrefix(entry)}: ${describeJson(entry.value)}` }];
+}
+
+function protectedLines(
+  entry: DecodedHeaderEntry,
+  receipt: DecodedReceipt,
+  depth: number,
+): Line[] {
+  const p = receipt.protected;
+  if (entry.label === 1 && p.alg) {
+    const name = p.alg.name ?? "unknown alg";
+    return [{ depth, text: `1 (alg): ${p.alg.value} — ${name}` }];
+  }
+  if (entry.label === 4 && p.kid) {
+    const text =
+      "hex" in p.kid
+        ? `${shortHex(p.kid.hex)} (${p.kid.byteLength} bytes)`
+        : JSON.stringify(p.kid.text);
+    return [{ depth, text: `4 (kid): ${text}` }];
+  }
+  if (entry.label === VDS_LABEL && p.vds) {
+    const name = p.vds.name ?? "unknown verifiable data structure";
+    return [
+      {
+        depth,
+        text: `${VDS_LABEL} (verifiable data structure): ${p.vds.value} — ${name}`,
+      },
+    ];
+  }
+  if (entry.label === CWT_CLAIMS_LABEL && p.cwtClaims) {
+    const lines: Line[] = [{ depth, text: `15 (CWT claims):` }];
+    for (const claim of p.cwtClaims) {
+      const head = claim.name ? `${claim.key} (${claim.name})` : `${claim.key}`;
+      lines.push({
+        depth: depth + 1,
+        text: `${head}: ${describeJson(claim.value)}`,
+      });
+      if (
+        claim.value !== null &&
+        typeof claim.value === "object" &&
+        !Array.isArray(claim.value)
+      ) {
+        for (const [k, v] of Object.entries(claim.value)) {
+          lines.push({ depth: depth + 2, text: `${k}: ${describeJson(v)}` });
+        }
+      }
+    }
+    return lines;
+  }
+  return [{ depth, text: `${labelPrefix(entry)}: ${describeJson(entry.value)}` }];
+}
+
+/** Draw the annotated COSE tree with box-drawing connectors. */
+function drawTree(lines: Line[]): string[] {
+  const out: string[] = [];
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i]!;
+    if (line.depth === 0) {
+      out.push(line.text);
+      continue;
+    }
+    // A node is "last" among its siblings if no later line has its depth
+    // before a shallower one appears.
+    const isLast = (depth: number, from: number): boolean => {
+      for (let j = from + 1; j < lines.length; j += 1) {
+        const d = lines[j]!.depth;
+        if (d < depth) return true;
+        if (d === depth) return false;
+      }
+      return true;
+    };
+    let prefix = "";
+    for (let depth = 1; depth < line.depth; depth += 1) {
+      // Find the nearest ancestor line at `depth` at or before i.
+      let ancestor = -1;
+      for (let j = i; j >= 0; j -= 1) {
+        if (lines[j]!.depth === depth) {
+          ancestor = j;
+          break;
+        }
+        if (lines[j]!.depth < depth) break;
+      }
+      prefix += ancestor >= 0 && isLast(depth, ancestor) ? "   " : "│  ";
+    }
+    prefix += isLast(line.depth, i) ? "└─ " : "├─ ";
+    out.push(prefix + line.text);
+  }
+  return out;
+}
+
+/** Render the receipt as the annotated human tree. */
+export function renderReceipt(receipt: DecodedReceipt): string {
+  const tagText =
+    receipt.tag !== null
+      ? `tagged ${receipt.tag} (COSE_Sign1)`
+      : "untagged (tag 18 omitted)";
+  const lines: Line[] = [
+    {
+      depth: 0,
+      text: `COSE_Sign1 — ${tagText} — ${receipt.byteLength} bytes`,
+    },
+  ];
+
+  lines.push({
+    depth: 1,
+    text: `protected: ${receipt.protected.byteLength} bytes (CBOR map, covered by the signature)`,
+  });
+  if (receipt.protected.entries.length === 0) {
+    lines.push({ depth: 2, text: "(empty)" });
+  }
+  for (const entry of receipt.protected.entries) {
+    lines.push(...protectedLines(entry, receipt, 2));
+  }
+
+  lines.push({ depth: 1, text: "unprotected: (not covered by the signature)" });
+  if (receipt.unprotected.entries.length === 0) {
+    lines.push({ depth: 2, text: "(empty)" });
+  }
+  for (const entry of receipt.unprotected.entries) {
+    lines.push(...unprotectedLines(entry, receipt, 2));
+  }
+
+  if (receipt.payload.detached) {
+    lines.push({
+      depth: 1,
+      text: "payload: detached (nil) — the verifier recomputes the MMR peak from the inclusion path",
+    });
+  } else {
+    lines.push({
+      depth: 1,
+      text: `payload: ${receipt.payload.byteLength} bytes — MMR peak hash ${shortHex(receipt.payload.hex)}`,
+    });
+  }
+
+  lines.push({
+    depth: 1,
+    text: `signature: ${receipt.signature.byteLength} bytes — ${shortHex(receipt.signature.hex)}`,
+  });
+
+  const tree = drawTree(lines);
+
+  const inclusion = receipt.inclusion;
+  const peak =
+    inclusion.peakHex !== null
+      ? `${shortHex(inclusion.peakHex)} (from payload)`
+      : inclusion.peakSource;
+  return [
+    ...tree,
+    "",
+    "MMR inclusion",
+    `  mmr index:    ${inclusion.mmrIndex}`,
+    `  path length:  ${inclusion.pathLength}`,
+    `  peak:         ${peak}`,
+  ].join("\n");
+}

package/src/lib/delegate-flow.ts

@@ -0,0 +1,289 @@
+/**
+ * FOR-390 / ADR-0052 delegation flow: authorize a custodian-vouched sealer to
+ * publish checkpoints for a log the caller owns (K(L)), using only PUBLIC
+ * coordinator endpoints (no operator token, no RPC).
+ *
+ * Port of canopy's `signAdvanceDelegation` + `buildByokDelegationMaterial`
+ * composed on published `@forestrie/delegation-cose` + `@forestrie/encoding`:
+ *
+ *   1. Import the ES256 root PEM (K(L)) as a WebCrypto CryptoKeyPair.
+ *   2. GET the coordinator's pending-delegation entries; find the STANDING
+ *      delegate-key entry (has `suggestedTtlSeconds`, no `mmrStart`).
+ *   3. Verify the registrar voucher against the caller-known registrar key
+ *      (mandatory — fail closed).
+ *   4. Build the delegation certificate + on-chain delegation proof over the
+ *      horizon `mmr 0..end`.
+ *   5. POST the certificate to the coordinator.
+ *
+ * Node-only (node:crypto PEM import). WebCrypto (`crypto.subtle`) does the
+ * ES256 signing inside delegation-cose.
+ */
+import { createPrivateKey, createPublicKey } from "node:crypto";
+import {
+  buildDelegationCertificateEs256,
+  decodeDelegatedCoseKeyFromBytes,
+  parseDelegatedCoseKeyFromPayload,
+  parseDelegationCertificate,
+  signOnchainDelegationEs256,
+  type DelegationInput,
+} from "@forestrie/delegation-cose";
+import { uuidToBytes } from "@forestrie/encoding";
+import {
+  parseRegistrarKeyXY,
+  verifyDelegateKeyVoucher,
+} from "./delegate-voucher.js";
+
+/** Fixed inclusive MMR start for a horizon delegation lease. */
+const MMR_START = 0;
+
+function b64ToBytes(b64: string): Uint8Array {
+  return new Uint8Array(Buffer.from(b64, "base64"));
+}
+
+function bytesToB64(bytes: Uint8Array): string {
+  return Buffer.from(bytes).toString("base64");
+}
+
+/**
+ * A coordinator pending-delegation entry. The STANDING delegate-key entry
+ * (registered by C1/C3) carries `suggestedTtlSeconds` and no `mmrStart`; lease
+ * entries carry `mmrStart`.
+ */
+export type StandingDelegationEntry = {
+  /** base64 CBOR EC2 P-256 COSE_Key for the delegated checkpoint signer. */
+  delegatedPublicKey: string;
+  /** Present on the standing entry only. */
+  suggestedTtlSeconds?: number;
+  /** Present on lease entries only. */
+  mmrStart?: number;
+  /** base64 COSE Sign1 registrar voucher. */
+  voucher?: string;
+  /** Sealer identity attested by the voucher. */
+  sealerId?: string;
+  /** Registrar key epoch attested by the voucher. */
+  epoch?: number | string;
+};
+
+/** Failure raised by the delegation flow (submit / verify / precondition). */
+export class DelegateFlowError extends Error {
+  readonly httpStatus?: number;
+  /** Structured error code for `--json` reporting (default: delegation_failed). */
+  readonly code?: "key_read_failed" | "delegation_failed";
+  constructor(
+    message: string,
+    httpStatus?: number,
+    code?: "key_read_failed" | "delegation_failed",
+  ) {
+    super(message);
+    this.name = "DelegateFlowError";
+    if (httpStatus !== undefined) this.httpStatus = httpStatus;
+    if (code !== undefined) this.code = code;
+  }
+}
+
+export type DelegateFlowParams = {
+  /** Delegation coordinator origin, no trailing slash. */
+  coordinatorUrl: string;
+  /** Target log id (UUID). */
+  logId: string;
+  /** ES256 log-root PEM (K(L)) that authorizes the delegation. */
+  rootPem: string;
+  /** Pinned registrar key, base64 `x||y` (64 bytes). */
+  knownSealerKey: string;
+  /** Exclusive MMR end of the horizon lease (mmrStart is fixed 0). */
+  horizonMmrEnd: number;
+  /** Lease TTL seconds; defaults to the standing entry's suggestedTtlSeconds. */
+  ttlSeconds?: number | undefined;
+};
+
+export type DelegateFlowDeps = {
+  fetchImpl?: typeof fetch;
+};
+
+export type DelegateFlowResult = {
+  sealerId: string;
+  epoch: number | string;
+  mmrStart: number;
+  mmrEnd: number;
+  /** base64 delegated public key COSE_Key passed through to the coordinator. */
+  delegatedPublicKey: string;
+  expiresAt: number;
+  certificate: Uint8Array;
+};
+
+/**
+ * Import an ES256 PKCS#8/SEC1 PEM as a WebCrypto CryptoKeyPair (private for
+ * signing, public for verification). Mirrors canopy's `importEs256PemKeyPair`.
+ */
+async function importEs256PemKeyPair(pem: string): Promise<CryptoKeyPair> {
+  const priv = createPrivateKey({ key: pem, format: "pem" });
+  const pkcs8 = priv.export({ format: "der", type: "pkcs8" });
+  const privateKey = await crypto.subtle.importKey(
+    "pkcs8",
+    pkcs8,
+    { name: "ECDSA", namedCurve: "P-256" },
+    false,
+    ["sign"],
+  );
+  // Derive the public key from the private PEM (round-trip through PEM keeps
+  // the @types/node overloads happy — createPublicKey(KeyObject) is untyped
+  // in this toolchain).
+  const pubPem = priv.export({ format: "pem", type: "pkcs8" }) as string;
+  const spki = createPublicKey({ key: pubPem, format: "pem" }).export({
+    format: "der",
+    type: "spki",
+  });
+  const publicKey = await crypto.subtle.importKey(
+    "spki",
+    spki,
+    { name: "ECDSA", namedCurve: "P-256" },
+    true,
+    ["verify"],
+  );
+  return { privateKey, publicKey };
+}
+
+/**
+ * Run the public delegation flow end-to-end, returning the submitted
+ * certificate and the bound lease scope.
+ */
+export async function runDelegateFlow(
+  params: DelegateFlowParams,
+  deps: DelegateFlowDeps = {},
+): Promise<DelegateFlowResult> {
+  const fetchImpl = deps.fetchImpl ?? fetch;
+
+  // 1. Root key pair (K(L)). A malformed or wrong-curve PEM must surface as a
+  // structured error (not an unhandled throw that leaks the key path / stack).
+  let rootKeyPair: CryptoKeyPair;
+  try {
+    rootKeyPair = await importEs256PemKeyPair(params.rootPem);
+  } catch {
+    throw new DelegateFlowError(
+      "--sign-with is not a usable ES256 (P-256) root PEM (K(L))",
+      undefined,
+      "key_read_failed",
+    );
+  }
+
+  // 2. Fetch pending delegation entries and find the standing entry.
+  const pendingUrl = `${params.coordinatorUrl}/api/logs/${params.logId}/pending-delegation`;
+  const pendingRes = await fetchImpl(pendingUrl);
+  if (!pendingRes.ok) {
+    const preview = (await pendingRes.text()).slice(0, 200);
+    throw new DelegateFlowError(
+      `pending-delegation fetch failed: HTTP ${pendingRes.status} ${preview}`,
+      pendingRes.status,
+    );
+  }
+  const pending = (await pendingRes.json()) as {
+    entries?: StandingDelegationEntry[];
+  };
+  const entries = pending.entries ?? [];
+  const standing = entries.find(
+    (e) => e.suggestedTtlSeconds !== undefined && e.mmrStart === undefined,
+  );
+  if (standing === undefined) {
+    throw new DelegateFlowError(
+      "no standing delegate-key entry for log — register a public root and a sealer delegate key first (C1/C3)",
+    );
+  }
+
+  // 3. Verify the registrar voucher (mandatory — fail closed).
+  if (
+    standing.voucher === undefined ||
+    standing.sealerId === undefined ||
+    standing.epoch === undefined
+  ) {
+    throw new DelegateFlowError(
+      "standing entry is missing its registrar voucher — refusing to bind",
+    );
+  }
+  const pinned = parseRegistrarKeyXY(b64ToBytes(params.knownSealerKey));
+  if (pinned === null) {
+    throw new DelegateFlowError(
+      "known-sealer-key must be base64 x||y (64 bytes)",
+    );
+  }
+  const voucherResult = await verifyDelegateKeyVoucher(
+    b64ToBytes(standing.voucher),
+    pinned,
+    {
+      sealerId: standing.sealerId,
+      epoch: standing.epoch,
+      publicKey: b64ToBytes(standing.delegatedPublicKey),
+    },
+  );
+  if (!voucherResult.ok) {
+    throw new DelegateFlowError(
+      `registrar voucher failed verification (${voucherResult.reason}) — refusing to bind`,
+    );
+  }
+
+  // 4. Build the delegation certificate + on-chain proof over mmr 0..end.
+  const mmrStart = MMR_START;
+  const mmrEnd = params.horizonMmrEnd;
+  const logIdHex32 = Buffer.from(uuidToBytes(params.logId)).toString("hex");
+  const delegatedPublicKeyBytes = b64ToBytes(standing.delegatedPublicKey);
+
+  const ttlSeconds = params.ttlSeconds ?? standing.suggestedTtlSeconds;
+  const certInput: DelegationInput = {
+    logIdHex32,
+    mmrStart,
+    mmrEnd,
+    delegatedPublicKeyCbor: delegatedPublicKeyBytes,
+  };
+  if (ttlSeconds !== undefined) certInput.ttlSeconds = ttlSeconds;
+  const certificate = await buildDelegationCertificateEs256(
+    certInput,
+    rootKeyPair,
+  );
+  const info = parseDelegationCertificate(certificate);
+  const delegated = parseDelegatedCoseKeyFromPayload(
+    decodeDelegatedCoseKeyFromBytes(delegatedPublicKeyBytes),
+  );
+  const onchainProof = await signOnchainDelegationEs256(
+    {
+      logIdHex: logIdHex32,
+      mmrStart,
+      mmrEnd,
+      delegatedKeyX: delegated.x,
+      delegatedKeyY: delegated.y,
+    },
+    rootKeyPair,
+  );
+
+  // 5. Submit the certificate to the coordinator.
+  const submitUrl = `${params.coordinatorUrl}/api/delegations/certificate`;
+  const submitRes = await fetchImpl(submitUrl, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      logId: params.logId,
+      mmrStart,
+      mmrEnd,
+      delegatedPublicKey: standing.delegatedPublicKey,
+      certificate: bytesToB64(certificate),
+      issuedAt: info.issuedAt,
+      expiresAt: info.expiresAt,
+      onchainSignature: bytesToB64(onchainProof.signature),
+    }),
+  });
+  if (!submitRes.ok) {
+    const preview = (await submitRes.text()).slice(0, 200);
+    throw new DelegateFlowError(
+      `certificate submit failed: HTTP ${submitRes.status} ${preview}`,
+      submitRes.status,
+    );
+  }
+
+  return {
+    sealerId: standing.sealerId,
+    epoch: standing.epoch,
+    mmrStart,
+    mmrEnd,
+    delegatedPublicKey: standing.delegatedPublicKey,
+    expiresAt: info.expiresAt,
+    certificate,
+  };
+}

package/src/lib/delegate-voucher.ts

@@ -0,0 +1,122 @@
+/**
+ * FOR-390 / ADR-0052 registrar delegate-key voucher verification, composed
+ * from published `@forestrie/encoding` primitives.
+ *
+ * A voucher is a COSE Sign1 signed by the known registrar key over a CBOR
+ * claims map `{1: sealerId, 2: epoch, 3: publicKey}`. It binds a sealer's
+ * delegated checkpoint-signing key to a registrar-attested identity; the CLI
+ * refuses to bind a delegation certificate to a delegate key whose voucher
+ * does not verify against the caller-known registrar key.
+ *
+ * This mirrors canopy `@forestrie/encoding`'s `verify-delegate-key-voucher.ts`.
+ * The published encoding v0.3.0 does NOT yet export
+ * `verifyDelegateKeyVoucher` / `parseRegistrarKeyXY`, so they are composed here
+ * from `decodeCoseSign1`, `verifyCoseSign1WithParsedKey`, and
+ * `decodeCborDeterministic`. Adopt the published helper once encoding ships it.
+ */
+import {
+  decodeCborDeterministic,
+  decodeCoseSign1,
+  verifyCoseSign1WithParsedKey,
+  type ParsedEcPublicKey,
+} from "@forestrie/encoding";
+
+const REGISTRAR_KEY_XY_BYTES = 64;
+const P256_COORD_BYTES = 32;
+
+/** Claims map labels in the registrar voucher payload. */
+const CLAIM_SEALER_ID = 1;
+const CLAIM_EPOCH = 2;
+const CLAIM_PUBLIC_KEY = 3;
+
+/**
+ * Parse a raw registrar key (uncompressed `x||y`, 64 bytes) into a
+ * {@link ParsedEcPublicKey}. Returns null when the input is not 64 bytes.
+ */
+export function parseRegistrarKeyXY(raw: Uint8Array): ParsedEcPublicKey | null {
+  if (raw.length !== REGISTRAR_KEY_XY_BYTES) return null;
+  return {
+    x: raw.slice(0, P256_COORD_BYTES),
+    y: raw.slice(P256_COORD_BYTES),
+    curve: "P-256",
+  };
+}
+
+/** Claims the voucher must attest to for the binding to proceed. */
+export type VoucherExpectation = {
+  /** Sealer identity (claim 1). */
+  sealerId: string;
+  /** Registrar key epoch (claim 2); a JSON string epoch is parsed to bigint. */
+  epoch: bigint | number | string;
+  /** Delegated public key CBOR bytes (claim 3). */
+  publicKey: Uint8Array;
+};
+
+/** Voucher verification outcome (fail-closed with a machine reason). */
+export type VoucherResult = { ok: true } | { ok: false; reason: string };
+
+/** Constant-time byte comparison (no early exit on first mismatch). */
+function constantTimeEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= a[i]! ^ b[i]!;
+  }
+  return diff === 0;
+}
+
+function toBigIntOrNull(value: unknown): bigint | null {
+  if (typeof value === "bigint") return value;
+  if (typeof value === "number" && Number.isInteger(value)) return BigInt(value);
+  if (typeof value === "string" && /^-?\d+$/.test(value)) return BigInt(value);
+  return null;
+}
+
+/**
+ * Verify a registrar delegate-key voucher:
+ *   1. COSE Sign1 signature verifies against the known registrar key.
+ *   2. The payload decodes to a CBOR claims map.
+ *   3. Claims 1/2/3 (sealerId / epoch / publicKey) match {@link expect}, with a
+ *      constant-time compare on the public key bytes.
+ *
+ * @returns `{ok:true}` when everything matches, otherwise `{ok:false, reason}`.
+ */
+export async function verifyDelegateKeyVoucher(
+  voucherBytes: Uint8Array,
+  pinnedKey: ParsedEcPublicKey,
+  expect: VoucherExpectation,
+): Promise<VoucherResult> {
+  // 1. Signature against the known registrar key.
+  const sigOk = await verifyCoseSign1WithParsedKey(voucherBytes, pinnedKey);
+  if (!sigOk) return { ok: false, reason: "signature" };
+
+  // 2. Decode envelope + claims map.
+  const decoded = decodeCoseSign1(voucherBytes);
+  if (decoded === null) return { ok: false, reason: "decode" };
+  let claims: unknown;
+  try {
+    claims = decodeCborDeterministic(decoded.payloadBstr);
+  } catch {
+    return { ok: false, reason: "decode" };
+  }
+  if (!(claims instanceof Map)) return { ok: false, reason: "decode" };
+
+  // 3. Claim-by-claim comparison.
+  const sealerId = claims.get(CLAIM_SEALER_ID);
+  if (typeof sealerId !== "string" || sealerId !== expect.sealerId) {
+    return { ok: false, reason: "sealerId" };
+  }
+  const epoch = toBigIntOrNull(claims.get(CLAIM_EPOCH));
+  const expectedEpoch = toBigIntOrNull(expect.epoch);
+  if (epoch === null || expectedEpoch === null || epoch !== expectedEpoch) {
+    return { ok: false, reason: "epoch" };
+  }
+  const publicKey = claims.get(CLAIM_PUBLIC_KEY);
+  if (
+    !(publicKey instanceof Uint8Array) ||
+    !constantTimeEqual(publicKey, expect.publicKey)
+  ) {
+    return { ok: false, reason: "publicKey" };
+  }
+  return { ok: true };
+}