@forestrie/forestrie-cli 0.8.0

package/src/lib/sign-statement-build.ts

@@ -0,0 +1,117 @@
+/**
+ * Payload intake and COSE Sign1 assembly for `forestrie sign-statement`
+ * (FOR-341).
+ *
+ * The signed statement is a plain COSE Sign1 (forestrie-demo-01.md, answer
+ * 5) with **all interpretable labels in the protected header**:
+ * `{1: alg (ES256, -7), 3: cty, 4: kid}`, signed via `@forestrie/encoding`
+ * `signCoseSign1Statement` (encoding >= 0.2.0). Nothing rides unprotected —
+ * per SCITT, the content type that tells a relying party how to interpret
+ * the signed bytes must be covered by the signature (review F1,
+ * plan-2607-14 W1.2), and the algorithm is pinned the same way.
+ *
+ * The encoder emits canonical tag-free CBOR, so the wire stays a plain
+ * untagged four-tuple (`84 58 xx ...`) that strict "plain COSE Sign1"
+ * consumers (any SCRAPI client) accept — no cbor-x tag 64 re-encode
+ * workaround is needed now that no unprotected header is merged in.
+ */
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import {
+  COSE_ALG_ES256,
+  coseKeyThumbprintUriP256,
+  signCoseSign1Statement,
+} from "@forestrie/encoding";
+import { errorMessage, type Es256SigningKey } from "./sign-statement-key.js";
+
+/** COSE header label for content type (RFC 9052 §3.1) — protected. */
+export const COSE_CONTENT_TYPE = 3;
+
+/**
+ * Read the statement payload from a file, or stdin when `pathOrDash`
+ * is `-`.
+ */
+export function readPayloadBytes(pathOrDash: string): Uint8Array {
+  try {
+    const data =
+      pathOrDash === "-" ? readFileSync(0) : readFileSync(pathOrDash);
+    return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+  } catch (err) {
+    const source =
+      pathOrDash === "-" ? "stdin" : `payload file ${pathOrDash}`;
+    throw new Error(`cannot read ${source}: ${errorMessage(err)}`);
+  }
+}
+
+/** `--iss` keyword deriving the RFC 9679 COSE Key Thumbprint URI. */
+export const ISS_CKT_KEYWORD = "ckt";
+
+/** Statement content type plus CWT claims inputs (FOR-371). */
+export type SignStatementBuildOptions = {
+  /** COSE content type header value (label 3, protected). */
+  contentType: string;
+  /**
+   * Issuer (CWT claim 1): literal StringOrURI, or {@link ISS_CKT_KEYWORD}
+   * to derive the RFC 9679 thumbprint URI from the signing key.
+   * Default: lowercase hex of the kid bytes (devdocs ADR-0055).
+   */
+  iss?: string | undefined;
+  /**
+   * Subject (CWT claim 2): issuer-scoped StringOrURI.
+   * Default: `sha-256:<hex>` of the payload bytes.
+   */
+  sub?: string | undefined;
+  /** Issued-at (CWT claim 6), seconds since epoch. Omitted by default. */
+  iat?: number | undefined;
+};
+
+/** A signed statement plus the claims that were actually bound into it. */
+export type SignedStatement = {
+  /** CBOR COSE Sign1 bytes (untagged array(4)). */
+  statement: Uint8Array;
+  /** Resolved issuer (CWT claim 1). */
+  iss: string;
+  /** Resolved subject (CWT claim 2). */
+  sub: string;
+  /** Issued-at (CWT claim 6), when requested. */
+  iat?: number;
+};
+
+/**
+ * Sign `payload` as a plain COSE Sign1 signed statement.
+ *
+ * Protected header carries `{1: ES256, 3: contentType, 4: kid, 15: CWT
+ * claims}` (SCITT signed statement, FOR-371); the unprotected header is
+ * empty. The signature covers everything interpretable — alg, cty, and the
+ * claims are all inside the protected bstr in the Sig_structure.
+ *
+ * @param payload - Statement payload bytes
+ * @param key - Loaded ES256 signing key (kid = first 32 bytes of `x||y`)
+ * @param options - Content type and claims; iss/sub default per ADR-0055
+ * @returns Statement bytes plus the resolved iss/sub (and iat when set)
+ */
+export async function buildSignedStatement(
+  payload: Uint8Array,
+  key: Es256SigningKey,
+  options: SignStatementBuildOptions,
+): Promise<SignedStatement> {
+  const iss =
+    options.iss === ISS_CKT_KEYWORD
+      ? await coseKeyThumbprintUriP256(key.publicXY)
+      : (options.iss ??
+        Buffer.from(key.kid).toString("hex"));
+  const sub =
+    options.sub ??
+    `sha-256:${createHash("sha256").update(payload).digest("hex")}`;
+  const statement = await signCoseSign1Statement(
+    payload,
+    key.kid,
+    key.privateKey,
+    {
+      alg: COSE_ALG_ES256,
+      cty: options.contentType,
+      cwtClaims: { iss, sub, ...(options.iat !== undefined && { iat: options.iat }) },
+    },
+  );
+  return { statement, iss, sub, ...(options.iat !== undefined && { iat: options.iat }) };
+}

package/src/lib/sign-statement-key.ts

@@ -0,0 +1,145 @@
+/**
+ * ES256 signing-key loading and kid derivation for `forestrie
+ * sign-statement` (FOR-341).
+ *
+ * Key import follows @forestrie/grant-builder `es256-pem-grant`:
+ * node:crypto `createPrivateKey` accepts SEC1 or PKCS#8 EC PEMs (WebCrypto
+ * alone imports only PKCS#8); JWK key files are routed through the same
+ * call so every input is validated identically. The normalized private JWK
+ * is then imported into WebCrypto because `@forestrie/encoding`
+ * `signCoseSign1Statement` signs with `crypto.subtle`.
+ *
+ * kid binding (forestrie-demo-01.md, answer 5): first 32 bytes of the
+ * uncompressed public point `x||y` under ES256.
+ */
+import {
+  createPrivateKey,
+  type KeyObject,
+  type webcrypto,
+} from "node:crypto";
+import { readFileSync } from "node:fs";
+import { parsePemResilient } from "./openssl-error-queue.js";
+
+/** kid length: first 32 bytes of `x||y` (i.e. the x coordinate). */
+export const ES256_KID_BYTES = 32;
+
+/** P-256 coordinate length in bytes. */
+const P256_COORD_BYTES = 32;
+
+/** Loaded ES256 signing key, ready for `signCoseSign1Statement`. */
+export type Es256SigningKey = {
+  /** WebCrypto ECDSA P-256 private key (usage: sign). */
+  privateKey: CryptoKey;
+  /** Signer binding: first {@link ES256_KID_BYTES} bytes of `x||y`. */
+  kid: Uint8Array;
+  /** Uncompressed public point `x||y` (64 bytes). */
+  publicXY: Uint8Array;
+};
+
+/** `Error.message` (or stringified value) for wrapped error causes. */
+export function errorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/**
+ * Load an ES256 (EC P-256) private key from a PEM or JWK file.
+ *
+ * @param keyPath - SEC1/PKCS#8 PEM or JWK JSON private key file
+ * @returns WebCrypto sign key plus the derived kid and public point
+ */
+export async function loadEs256SigningKey(
+  keyPath: string,
+): Promise<Es256SigningKey> {
+  let text: string;
+  try {
+    text = readFileSync(keyPath, "utf8");
+  } catch (err) {
+    throw new Error(`cannot read key file ${keyPath}: ${errorMessage(err)}`);
+  }
+  return es256SigningKeyFromText(text, keyPath);
+}
+
+/** As {@link loadEs256SigningKey}, from key material already in memory. */
+export async function es256SigningKeyFromText(
+  text: string,
+  source: string,
+): Promise<Es256SigningKey> {
+  const keyObject = importPrivateKeyObject(text, source);
+  const jwk = keyObject.export({ format: "jwk" });
+  if (
+    jwk.kty !== "EC" ||
+    jwk.crv !== "P-256" ||
+    typeof jwk.x !== "string" ||
+    typeof jwk.y !== "string" ||
+    typeof jwk.d !== "string"
+  ) {
+    throw new Error(
+      `${source}: sign-statement requires an ES256 (EC P-256) private key`,
+    );
+  }
+
+  const x = base64UrlToBytes(jwk.x);
+  const y = base64UrlToBytes(jwk.y);
+  if (x.length !== P256_COORD_BYTES || y.length !== P256_COORD_BYTES) {
+    throw new Error(
+      `${source}: P-256 public key coordinates must be 32 bytes each`,
+    );
+  }
+  const publicXY = new Uint8Array(P256_COORD_BYTES * 2);
+  publicXY.set(x, 0);
+  publicXY.set(y, P256_COORD_BYTES);
+
+  const privateKey = await crypto.subtle.importKey(
+    "jwk",
+    { kty: "EC", crv: "P-256", x: jwk.x, y: jwk.y, d: jwk.d, ext: true },
+    { name: "ECDSA", namedCurve: "P-256" },
+    false,
+    ["sign"],
+  );
+
+  return {
+    privateKey,
+    kid: publicXY.slice(0, ES256_KID_BYTES),
+    publicXY,
+  };
+}
+
+/** Route PEM or JWK-JSON key text through node:crypto for validation. */
+function importPrivateKeyObject(text: string, source: string): KeyObject {
+  if (text.includes("-----BEGIN")) {
+    try {
+      // `parsePemResilient` retries once so a valid key is never rejected
+      // because the OpenSSL error queue was poisoned elsewhere (FOR-343).
+      return parsePemResilient(() =>
+        createPrivateKey({ key: text, format: "pem" }),
+      );
+    } catch (err) {
+      throw new Error(
+        `${source}: not a readable EC private key PEM: ${errorMessage(err)}`,
+      );
+    }
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new Error(
+      `${source}: key file is neither a PEM nor a JWK JSON document`,
+    );
+  }
+  try {
+    return createPrivateKey({
+      key: parsed as webcrypto.JsonWebKey,
+      format: "jwk",
+    });
+  } catch (err) {
+    throw new Error(
+      `${source}: not a usable private JWK: ${errorMessage(err)}`,
+    );
+  }
+}
+
+/** Decode base64url (JWK coordinate encoding) to bytes. */
+function base64UrlToBytes(b64url: string): Uint8Array {
+  return new Uint8Array(Buffer.from(b64url, "base64url"));
+}

package/src/lib/verify-anchored.ts

@@ -0,0 +1,326 @@
+import { bytesEqual } from "./bytes.js";
+import { ethCall, normalizeHexAddress } from "@forestrie/chain-rpc";
+import { verifyCoseSign1WithParsedKey } from "@forestrie/encoding";
+import {
+  calculateRoot,
+  verifyInclusion,
+  type Hasher,
+} from "@forestrie/merklelog";
+import {
+  decodeTrustRootFromGenesis,
+  parseReceipt,
+  univocityLeafHash,
+} from "@forestrie/receipt-verify";
+
+/** Re-exported for existing local consumers (was CLI-private before FOR-297 D5 hoist). */
+export { univocityLeafHash };
+
+/**
+ * Chain-anchored receipt check (FOR-347 / demo step 5a): read the
+ * Univocity `logState(bytes32)` accumulator over JSON-RPC and assert the
+ * receipt's peak is one of the anchored accumulator peaks. This is the
+ * ONLY networked path in `forestrie verify`; the core verify stays pure
+ * over bytes.
+ *
+ * Anchoring test: for a detached-payload receipt the checkpoint signature
+ * covers the peak (COSE detached content), so the peak the receipt commits
+ * to is exactly the one the signature verifies over. We therefore try the
+ * genesis trust key against each on-chain accumulator peak as the detached
+ * payload — a match proves the signed peak is on-chain, and the offline
+ * verify already proved leaf inclusion under that same signed peak. For an
+ * attached-payload receipt the peak is explicit and byte-compared.
+ */
+
+/** Selector for `logState(bytes32)` (arbor publishproof Univocity ABI). */
+const LOG_STATE_SELECTOR = "0xeecac1b7";
+
+export type OnChainLogState = {
+  /** Anchored accumulator peaks (32 bytes each), contract order. */
+  accumulator: Uint8Array[];
+  /** Anchored MMR size. */
+  size: bigint;
+};
+
+export type AnchorCheck = OnChainLogState & {
+  /** True when the receipt's peak is one of the anchored accumulator peaks. */
+  anchored: boolean;
+  /** Index of the matched accumulator peak, or null. */
+  matchedPeak: number | null;
+  /** Stable failure token when not anchored. */
+  reason?: string;
+};
+
+/**
+ * Classify an unanchored peak so honest receipts never fail tamper-shaped
+ * (FOR-368 Phase 0, plan-2607-29):
+ * - the leaf predates the anchored size but its peak is absent — the log
+ *   grew and BURIED the peak (`peak_not_current`): an honest-receipt
+ *   condition needing growth evidence, not a tamper verdict;
+ * - the leaf is at/after the anchored size — the entry simply is not
+ *   anchored yet (`receipt_newer_than_anchored_state`).
+ * Tampered receipts surface earlier (signature/inclusion) or as a
+ * recomputed peak that matches no anchored state ever; the chain rungs
+ * that PROVE the buried case land in later plan phases.
+ */
+export function classifyUnanchoredPeak(
+  leafMmrIndex: bigint,
+  anchoredSize: bigint,
+): string {
+  if (leafMmrIndex >= anchoredSize) {
+    return "receipt_newer_than_anchored_state";
+  }
+  return "peak_not_current";
+}
+
+/** Leaf MMR index from a parsed receipt proof. */
+export function receiptLeafIndex(receiptCbor: Uint8Array): bigint {
+  const { proof } = parseReceipt(receiptCbor);
+  return proof.leafIndex !== undefined ? proof.leafIndex : proof.mmrIndex!;
+}
+
+/**
+ * Normalize a log id (UUID with dashes, 32-hex UUID form, or 64-hex
+ * contract form) to the 32-byte contract key: Univocity stores logs with
+ * the UUID in the low 16 bytes, zero-padded on the left.
+ */
+export function toContractLogId(logId: string): string {
+  const hex = logId.replace(/-/g, "").replace(/^0x/, "").toLowerCase();
+  if (!/^[0-9a-f]{32}$/.test(hex) && !/^[0-9a-f]{64}$/.test(hex)) {
+    throw new Error(
+      `--log-id must be a UUID or 16/32-byte hex id, got '${logId}'`,
+    );
+  }
+  return "0x" + hex.padStart(64, "0");
+}
+
+function readWord(hex: string, wordIndex: number): bigint {
+  const start = wordIndex * 64;
+  if (hex.length < start + 64) {
+    throw new Error(
+      `logState result too short: need word ${wordIndex}, have ${hex.length} hex chars`,
+    );
+  }
+  return BigInt("0x" + hex.slice(start, start + 64));
+}
+
+function hexToBytes(hex: string): Uint8Array {
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    out[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return out;
+}
+
+/**
+ * Decode the `logState(bytes32)` return — the dynamic tuple
+ * `(bytes32[] accumulator, uint64 size)`: word0 = offset to the tuple,
+ * then relative to the tuple start: word = offset to the accumulator
+ * array, word = `size`, and the array as length + elements.
+ */
+export function decodeLogStateResult(resultHex: string): OnChainLogState {
+  const hex = resultHex.replace(/^0x/, "");
+  if (hex.length === 0) {
+    throw new Error("logState returned empty result (log not found?)");
+  }
+  const tupleOffset = readWord(hex, 0);
+  const base = Number(tupleOffset) / 32; // word index of the tuple start
+  const accumulatorOffset = readWord(hex, base);
+  const size = readWord(hex, base + 1);
+  const arrayBase = base + Number(accumulatorOffset) / 32;
+  const length = Number(readWord(hex, arrayBase));
+  const accumulator: Uint8Array[] = [];
+  for (let i = 0; i < length; i++) {
+    const start = (arrayBase + 1 + i) * 64;
+    if (hex.length < start + 64) {
+      throw new Error(
+        `logState accumulator truncated at peak ${i} of ${length}`,
+      );
+    }
+    accumulator.push(hexToBytes(hex.slice(start, start + 64)));
+  }
+  return { accumulator, size };
+}
+
+/** `eth_call` `logState(logId)` via `@forestrie/chain-rpc`. */
+export async function fetchOnChainLogState(opts: {
+  univocity: string;
+  logId: string;
+  rpcUrl: string;
+}): Promise<OnChainLogState> {
+  const address = normalizeHexAddress(opts.univocity);
+  if (address === null) {
+    throw new Error(`--univocity is not a valid address: '${opts.univocity}'`);
+  }
+  const data = LOG_STATE_SELECTOR + toContractLogId(opts.logId).slice(2);
+  const result = await ethCall(opts.rpcUrl, `0x${address}`, data);
+  if (typeof result !== "string" || result === "0x") {
+    throw new Error(
+      `logState eth_call returned no data for log ${opts.logId} at ${opts.univocity}`,
+    );
+  }
+  return decodeLogStateResult(result);
+}
+
+
+/** Web Crypto SHA-256 hasher (mirrors @forestrie/receipt-verify SubtleHasher). */
+class SubtleHasher implements Hasher {
+  private chunks: Uint8Array[] = [];
+  reset(): void {
+    this.chunks = [];
+  }
+  update(data: Uint8Array): void {
+    this.chunks.push(data);
+  }
+  async digest(): Promise<Uint8Array> {
+    const total = this.chunks.reduce((s, c) => s + c.length, 0);
+    const combined = new Uint8Array(total);
+    let offset = 0;
+    for (const c of this.chunks) {
+      combined.set(c, offset);
+      offset += c.length;
+    }
+    return new Uint8Array(await crypto.subtle.digest("SHA-256", combined));
+  }
+}
+
+export type RecomputedPeak = {
+  /** The accumulator peak the leaf's inclusion proof commits to. */
+  peak: Uint8Array;
+  /**
+   * True when the proof path checks out: always for a detached receipt (the
+   * peak IS the path recomputation), byte-verified for an attached peak.
+   */
+  inclusionOk: boolean;
+};
+
+/**
+ * Recompute the receipt's accumulator peak from the leaf commitment and the
+ * receipt's own inclusion proof — pure bytes, NO signature involved. This is
+ * the signature-free half of chain-anchored verification (FOR-297 approach C):
+ * `leaf = SHA-256(idtimestamp ‖ inner)`, walk the label-396 proof path to the
+ * peak, then the caller matches that peak against the on-chain accumulator.
+ * Binding and inclusion are inherent: a wrong payload or tampered path yields
+ * a peak that cannot appear in the anchored accumulator.
+ */
+export async function recomputeReceiptPeak(opts: {
+  receiptCbor: Uint8Array;
+  idtimestampBe8: Uint8Array;
+  /** Leaf ContentHash: SHA-256(payload) or the grant commitment hash. */
+  inner: Uint8Array;
+}): Promise<RecomputedPeak> {
+  const { explicitPeak, proof } = parseReceipt(opts.receiptCbor);
+  const leafHash = await univocityLeafHash(opts.idtimestampBe8, opts.inner);
+  const hasher = new SubtleHasher();
+  const leafIdx =
+    proof.leafIndex !== undefined ? proof.leafIndex : proof.mmrIndex!;
+  if (explicitPeak !== null) {
+    const inclusionOk = await verifyInclusion(
+      hasher,
+      leafHash,
+      proof,
+      explicitPeak,
+    );
+    return { peak: explicitPeak, inclusionOk };
+  }
+  const peak = await calculateRoot(hasher, leafHash, proof, leafIdx);
+  return { peak, inclusionOk: true };
+}
+
+/**
+ * Assert the receipt's peak is anchored in the on-chain accumulator.
+ * Two peak-location strategies:
+ * - default (offline verify passed): a detached receipt's peak is located by
+ *   trying the genesis trust key against each on-chain peak as the detached
+ *   payload; an attached peak is byte-compared.
+ * - `recomputedPeak` (anchor-only, FOR-297 approach C): the caller recomputed
+ *   the peak from leaf + proof via {@link recomputeReceiptPeak}; byte-compare
+ *   it directly — no signature, no trust key. Trust is the contract anchor.
+ */
+export async function checkReceiptAnchored(opts: {
+  /** Required unless `recomputedPeak` locates the peak without a trust key. */
+  genesisCbor: Uint8Array | undefined;
+  receiptCbor: Uint8Array;
+  univocity: string;
+  logId: string;
+  rpcUrl: string;
+  recomputedPeak?: Uint8Array;
+}): Promise<AnchorCheck> {
+  if (opts.recomputedPeak !== undefined) {
+    const state = await fetchOnChainLogState(opts);
+    let matchedPeak: number | null = null;
+    for (let i = 0; i < state.accumulator.length; i++) {
+      if (bytesEqual(opts.recomputedPeak, state.accumulator[i]!)) {
+        matchedPeak = i;
+        break;
+      }
+    }
+    const anchored = matchedPeak !== null;
+    return {
+      ...state,
+      anchored,
+      matchedPeak,
+      ...(anchored
+        ? {}
+        : {
+            reason: classifyUnanchoredPeak(
+              receiptLeafIndex(opts.receiptCbor),
+              state.size,
+            ),
+          }),
+    };
+  }
+
+  const { explicitPeak } = parseReceipt(opts.receiptCbor);
+  if (opts.genesisCbor === undefined) {
+    throw new Error(
+      "genesis is required to locate the receipt peak on-chain without a recomputed peak",
+    );
+  }
+  const trustRoot = await decodeTrustRootFromGenesis(opts.genesisCbor);
+  if (explicitPeak === null && !(trustRoot instanceof CryptoKey)) {
+    // Detached receipts locate their peak via the ES256 signature; a
+    // KS256 root cannot verify here (same surface as `no_es256_trust_key`).
+    return {
+      accumulator: [],
+      size: 0n,
+      anchored: false,
+      matchedPeak: null,
+      reason: "no_es256_trust_key",
+    };
+  }
+
+  const state = await fetchOnChainLogState(opts);
+
+  let matchedPeak: number | null = null;
+  for (let i = 0; i < state.accumulator.length; i++) {
+    const peak = state.accumulator[i]!;
+    if (explicitPeak !== null) {
+      if (bytesEqual(explicitPeak, peak)) {
+        matchedPeak = i;
+        break;
+      }
+    } else if (
+      await verifyCoseSign1WithParsedKey(opts.receiptCbor, trustRoot as CryptoKey, {
+        detachedPayload: peak,
+      })
+    ) {
+      matchedPeak = i;
+      break;
+    }
+  }
+
+  const anchored = matchedPeak !== null;
+  return {
+    ...state,
+    anchored,
+    matchedPeak,
+    ...(anchored
+      ? {}
+      : {
+          reason: classifyUnanchoredPeak(
+            receiptLeafIndex(opts.receiptCbor),
+            state.size,
+          ),
+        }),
+  };
+}