@forestrie/receipt-verify 0.1.0

package/src/grant-codec.ts

@@ -0,0 +1,106 @@
+import { decode as decodeCbor, encode as encodeCbor } from "cbor-x";
+import type { Grant } from "./grant.js";
+import { grantDataToBytes } from "./grant-data.js";
+import { fromPaddedWire32, toPaddedWire32 } from "./uuid-bytes.js";
+
+const CBOR_KEY_IDTIMESTAMP = 0;
+const CBOR_KEY_LOG_ID = 1;
+const CBOR_KEY_OWNER_LOG_ID = 2;
+const CBOR_KEY_GRANT_FLAGS = 3;
+const CBOR_KEY_MAX_HEIGHT = 4;
+const CBOR_KEY_MIN_GROWTH = 5;
+const CBOR_KEY_GRANT_DATA = 6;
+const WIRE_GRANT_FLAGS_BYTES = 8;
+const IDTIMESTAMP_BYTES = 8;
+
+function leftPad(b: Uint8Array, length: number): Uint8Array {
+  if (b.length >= length) {
+    return b.length === length ? b : b.slice(-length);
+  }
+  const out = new Uint8Array(length);
+  out.set(b, length - b.length);
+  return out;
+}
+
+function mapToGrant(m: Map<number, unknown> | Record<number, unknown>): Grant {
+  const get = (k: number): unknown =>
+    m instanceof Map ? m.get(k) : (m as Record<number, unknown>)[k];
+
+  const requireBstr = (v: unknown, minLen = 0): Uint8Array => {
+    if (!(v instanceof Uint8Array))
+      throw new Error("Grant payload: value must be bstr");
+    if (v.length < minLen) throw new Error("Grant payload: bstr too short");
+    return v;
+  };
+  const requireUint = (v: unknown): number => {
+    if (typeof v === "number" && Number.isInteger(v)) return v;
+    if (typeof v === "bigint") return Number(v);
+    throw new Error("Grant payload: expected uint");
+  };
+
+  return {
+    logId: fromPaddedWire32(requireBstr(get(CBOR_KEY_LOG_ID))),
+    ownerLogId: fromPaddedWire32(requireBstr(get(CBOR_KEY_OWNER_LOG_ID))),
+    grant: leftPad(
+      requireBstr(get(CBOR_KEY_GRANT_FLAGS)),
+      WIRE_GRANT_FLAGS_BYTES,
+    ),
+    maxHeight: requireUint(get(CBOR_KEY_MAX_HEIGHT)),
+    minGrowth: requireUint(get(CBOR_KEY_MIN_GROWTH)),
+    grantData:
+      get(CBOR_KEY_GRANT_DATA) instanceof Uint8Array
+        ? (get(CBOR_KEY_GRANT_DATA) as Uint8Array)
+        : new Uint8Array(0),
+  };
+}
+
+export function decodeGrantPayload(bytes: Uint8Array): Grant {
+  if (!bytes?.length) throw new Error("Grant payload is empty");
+  const raw = decodeCbor(bytes) as unknown;
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new Error("Grant payload must be a CBOR map");
+  }
+  return mapToGrant(raw as Map<number, unknown> | Record<number, unknown>);
+}
+
+export function decodeGrantResponse(bytes: Uint8Array): {
+  grant: Grant;
+  idtimestamp: Uint8Array;
+} {
+  const raw = decodeCbor(bytes) as unknown;
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new Error("Grant response must be a CBOR map");
+  }
+  const m = raw as Map<number, unknown> | Record<number, unknown>;
+  const get = (k: number): unknown =>
+    m instanceof Map ? m.get(k) : (m as Record<number, unknown>)[k];
+  const idtimestampVal = get(CBOR_KEY_IDTIMESTAMP);
+  if (
+    !(idtimestampVal instanceof Uint8Array) ||
+    idtimestampVal.length < IDTIMESTAMP_BYTES
+  ) {
+    throw new Error("Grant response: key 0 must be 8-byte bstr");
+  }
+  const idtimestamp = new Uint8Array(IDTIMESTAMP_BYTES);
+  idtimestamp.set(
+    idtimestampVal.length === IDTIMESTAMP_BYTES
+      ? idtimestampVal
+      : idtimestampVal.slice(-IDTIMESTAMP_BYTES),
+  );
+  return { grant: mapToGrant(m), idtimestamp };
+}
+
+export function encodeGrantPayload(grant: Grant): Uint8Array {
+  const map = new Map<number, unknown>([
+    [CBOR_KEY_LOG_ID, toPaddedWire32(grant.logId)],
+    [CBOR_KEY_OWNER_LOG_ID, toPaddedWire32(grant.ownerLogId)],
+    [CBOR_KEY_GRANT_FLAGS, leftPad(grant.grant, WIRE_GRANT_FLAGS_BYTES)],
+    [CBOR_KEY_MAX_HEIGHT, grant.maxHeight ?? 0],
+    [CBOR_KEY_MIN_GROWTH, grant.minGrowth ?? 0],
+    [
+      CBOR_KEY_GRANT_DATA,
+      grantDataToBytes(grant.grantData ?? new Uint8Array(0)),
+    ],
+  ]);
+  return new Uint8Array(encodeCbor(map));
+}

package/src/grant-commitment.ts

@@ -0,0 +1,64 @@
+import { grantDataToBytes } from "./grant-data.js";
+import type { Grant } from "./grant.js";
+import { toPaddedWire32 } from "./uuid-bytes.js";
+
+const GRANT_FLAGS_32_BYTES = 32;
+const U64_BYTES = 8;
+
+function u64Be(n: number): Uint8Array {
+  const out = new Uint8Array(U64_BYTES);
+  let v = BigInt(n) & 0xffffffffffffffffn;
+  for (let i = 7; i >= 0; i--) {
+    out[i] = Number(v & 0xffn);
+    v >>= 8n;
+  }
+  return out;
+}
+
+function grantFlags32(flags: Uint8Array): Uint8Array {
+  const out = new Uint8Array(GRANT_FLAGS_32_BYTES);
+  if (flags.length >= 8) {
+    out.set(flags.slice(-8), 24);
+  } else if (flags.length > 0) {
+    out.set(flags, 32 - flags.length);
+  }
+  return out;
+}
+
+function grantCommitmentPreimage(grant: Grant): Uint8Array {
+  const logId = toPaddedWire32(grant.logId);
+  const flags32 = grantFlags32(grant.grant);
+  const maxHeight = grant.maxHeight ?? 0;
+  const minGrowth = grant.minGrowth ?? 0;
+  const ownerLogId = toPaddedWire32(grant.ownerLogId);
+  const grantData = grantDataToBytes(grant.grantData ?? new Uint8Array(0));
+
+  const total =
+    logId.length +
+    flags32.length +
+    U64_BYTES * 2 +
+    ownerLogId.length +
+    grantData.length;
+  const out = new Uint8Array(total);
+  let off = 0;
+  out.set(logId, off);
+  off += logId.length;
+  out.set(flags32, off);
+  off += flags32.length;
+  out.set(u64Be(maxHeight), off);
+  off += U64_BYTES;
+  out.set(u64Be(minGrowth), off);
+  off += U64_BYTES;
+  out.set(ownerLogId, off);
+  off += ownerLogId.length;
+  out.set(grantData, off);
+  return out;
+}
+
+export async function grantCommitmentHashFromGrant(
+  grant: Grant,
+): Promise<Uint8Array> {
+  const preimage = grantCommitmentPreimage(grant);
+  const hash = await crypto.subtle.digest("SHA-256", preimage as BufferSource);
+  return new Uint8Array(hash);
+}

package/src/grant-data.ts

@@ -0,0 +1,12 @@
+export interface GrantDataEs256Xy {
+  readonly kind: "es256-xy";
+  readonly xy: Uint8Array;
+}
+
+export type GrantData = Uint8Array | GrantDataEs256Xy;
+
+export function grantDataToBytes(data: Uint8Array | GrantData): Uint8Array {
+  if (data instanceof Uint8Array) return data;
+  if (data.kind === "es256-xy") return data.xy;
+  throw new Error("Unsupported GrantData variant");
+}

package/src/grant.ts

@@ -0,0 +1,12 @@
+import type { GrantData } from "./grant-data.js";
+
+/** On-chain grant content aligned with Univocity `PublishGrant`. */
+export interface Grant {
+  logId: Uint8Array;
+  grant: Uint8Array;
+  request?: bigint;
+  maxHeight?: number;
+  minGrowth?: number;
+  ownerLogId: Uint8Array;
+  grantData: Uint8Array | GrantData;
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+export type {
+  ReceiptVerifyResult,
+  ReceiptVerifyStage,
+} from "./receipt-verify-result.js";
+export type { Grant } from "./grant.js";
+export type { VerifyGrantReceiptOfflineInput } from "./verify-grant-receipt-offline.js";
+export { parseReceipt } from "./parse-receipt.js";
+export { decodeTrustRootFromGenesis } from "./decode-trust-root-from-genesis.js";
+export { verifyGrantReceiptOffline } from "./verify-grant-receipt-offline.js";
+export { decodeForestrieGrantCose } from "./decode-forestrie-grant-cose.js";
+export { decodeGrantPayload, decodeGrantResponse } from "./grant-codec.js";

package/src/leaf-commitment.ts

@@ -0,0 +1,35 @@
+const IDTIMESTAMP_BYTES = 8;
+
+function writeU64BE(out: Uint8Array, offset: number, value: bigint): void {
+  let v = value & 0xffffffffffffffffn;
+  for (let i = 7; i >= 0; i--) {
+    out[offset + i] = Number(v & 0xffn);
+    v >>= 8n;
+  }
+}
+
+export async function univocityLeafHash(
+  idtimestamp: bigint | Uint8Array,
+  grantCommitmentHash: Uint8Array,
+): Promise<Uint8Array> {
+  const idtimestampBytes = new Uint8Array(IDTIMESTAMP_BYTES);
+  if (typeof idtimestamp === "bigint") {
+    writeU64BE(idtimestampBytes, 0, idtimestamp);
+  } else {
+    if (idtimestamp.length < IDTIMESTAMP_BYTES) {
+      throw new Error("idtimestamp must be at least 8 bytes");
+    }
+    idtimestampBytes.set(
+      idtimestamp.length > IDTIMESTAMP_BYTES
+        ? idtimestamp.slice(-IDTIMESTAMP_BYTES)
+        : idtimestamp,
+    );
+  }
+  const preimage = new Uint8Array(
+    idtimestampBytes.length + grantCommitmentHash.length,
+  );
+  preimage.set(idtimestampBytes);
+  preimage.set(grantCommitmentHash, idtimestampBytes.length);
+  const hash = await crypto.subtle.digest("SHA-256", preimage);
+  return new Uint8Array(hash);
+}

package/src/parse-receipt.ts

@@ -0,0 +1,120 @@
+import { decode as decodeCbor } from "cbor-x";
+import type { Proof } from "@forestrie/merklelog";
+
+const VDS_COSE_RECEIPT_PROOFS_TAG = 396;
+
+type CoseSign1 = [
+  protectedHeader: Uint8Array,
+  unprotectedHeader: Map<number, unknown> | Record<string, unknown>,
+  payload: Uint8Array | null,
+  signature: Uint8Array,
+];
+
+function unwrapCoseSign1Tag(value: unknown): unknown {
+  if (value && typeof value === "object" && !(value instanceof Map)) {
+    const tagged = value as { tag?: number; value?: unknown };
+    if (
+      Object.prototype.hasOwnProperty.call(tagged, "value") &&
+      tagged.tag === 18
+    ) {
+      return tagged.value;
+    }
+  }
+  return value;
+}
+
+function requireCoseSign1(value: unknown): CoseSign1 {
+  if (!Array.isArray(value) || value.length !== 4) {
+    throw new Error("Receipt is not a COSE Sign1 array");
+  }
+  const [p, u, payload, sig] = value as unknown[];
+  if (!(p instanceof Uint8Array) || !(sig instanceof Uint8Array)) {
+    throw new Error("Invalid COSE Sign1 structure");
+  }
+  if (!(payload === null || payload instanceof Uint8Array)) {
+    throw new Error("Invalid COSE Sign1 payload");
+  }
+  return [
+    p,
+    u as Map<number, unknown> | Record<string, unknown>,
+    payload,
+    sig,
+  ] as CoseSign1;
+}
+
+function toHeaderMap(
+  value: Map<number, unknown> | Record<string, unknown>,
+): Map<number, unknown> {
+  if (value instanceof Map) return value as Map<number, unknown>;
+  const out = new Map<number, unknown>();
+  if (typeof value === "object" && value !== null) {
+    for (const [k, v] of Object.entries(value)) {
+      const n = Number(k);
+      if (Number.isFinite(n)) out.set(n, v);
+    }
+  }
+  return out;
+}
+
+export function parseReceipt(receiptBytes: Uint8Array): {
+  explicitPeak: Uint8Array | null;
+  proof: Proof;
+  receiptCbor: Uint8Array;
+  coseSign1: CoseSign1;
+} {
+  const decoded = decodeCbor(receiptBytes) as unknown;
+  const unwrapped = unwrapCoseSign1Tag(decoded);
+  requireCoseSign1(unwrapped);
+
+  const coseSign1 = requireCoseSign1(unwrapped);
+  const payload = coseSign1[2];
+  let explicitPeak: Uint8Array | null = null;
+  if (payload instanceof Uint8Array) {
+    if (payload.length !== 32) {
+      throw new Error("Receipt payload must be 32 bytes (peak hash)");
+    }
+    explicitPeak = payload;
+  } else if (payload !== null && payload !== undefined) {
+    throw new Error(
+      "Receipt payload must be nil (detached) or 32-byte peak hash",
+    );
+  }
+
+  const unprotected = toHeaderMap(coseSign1[1]);
+  const proofsRaw = unprotected.get(VDS_COSE_RECEIPT_PROOFS_TAG);
+  if (!proofsRaw || typeof proofsRaw !== "object") {
+    throw new Error("Receipt missing header 396 (inclusion proof)");
+  }
+  const proofsMap = proofsRaw as Map<number, unknown> | Record<number, unknown>;
+  const proofList = (
+    proofsMap instanceof Map
+      ? proofsMap.get(-1)
+      : (proofsMap as Record<number, unknown>)[-1]
+  ) as unknown[] | undefined;
+  if (!Array.isArray(proofList) || proofList.length === 0) {
+    throw new Error("Receipt proof -1 must be non-empty array");
+  }
+  const entry = proofList[0] as Record<number, unknown> | Map<number, unknown>;
+  const mmrIndexRaw =
+    entry instanceof Map ? entry.get(1) : (entry as Record<number, unknown>)[1];
+  const pathRaw =
+    entry instanceof Map ? entry.get(2) : (entry as Record<number, unknown>)[2];
+  if (mmrIndexRaw === undefined || !Array.isArray(pathRaw)) {
+    throw new Error("Proof entry must have 1: mmrIndex, 2: path");
+  }
+  const mmrIndex =
+    typeof mmrIndexRaw === "bigint" ? mmrIndexRaw : BigInt(Number(mmrIndexRaw));
+  const path = pathRaw.map((h: unknown) => {
+    if (!(h instanceof Uint8Array) || h.length !== 32) {
+      throw new Error("Proof path elements must be 32-byte hashes");
+    }
+    return h;
+  });
+
+  return {
+    explicitPeak,
+    proof: { path, mmrIndex },
+    receiptCbor: receiptBytes,
+    coseSign1,
+  };
+}

package/src/receipt-verify-result.ts

@@ -0,0 +1,13 @@
+/** Failure stage for falsifiable tests and CLI exit messaging (ADR-0045). */
+export type ReceiptVerifyStage =
+  | "parse"
+  | "signature"
+  | "inclusion"
+  | "binding";
+
+export type ReceiptVerifyResult = {
+  ok: boolean;
+  stage: ReceiptVerifyStage;
+  /** Present when ok === false; stable snake_case token for tests. */
+  reason?: string;
+};

package/src/root-verify-key.ts

@@ -0,0 +1,19 @@
+import { COSE_ALG_KS256 } from "./cose-key.js";
+
+export interface ParsedKs256RootKey {
+  kind: "KS256";
+  alg: typeof COSE_ALG_KS256;
+  address: Uint8Array;
+}
+
+export function isParsedKs256RootKey(key: unknown): key is ParsedKs256RootKey {
+  return (
+    typeof key === "object" &&
+    key !== null &&
+    (key as ParsedKs256RootKey).kind === "KS256" &&
+    (key as ParsedKs256RootKey).address instanceof Uint8Array &&
+    (key as ParsedKs256RootKey).address.length === 20
+  );
+}
+
+export type RootVerifyKey = CryptoKey | ParsedKs256RootKey;

package/src/subtle-hasher.ts

@@ -0,0 +1,26 @@
+import type { Hasher } from "@forestrie/merklelog";
+
+/** Web Crypto SHA-256 hasher for Node and browser offline verify. */
+export class SubtleHasher implements Hasher {
+  private chunks: Uint8Array[] = [];
+
+  reset(): void {
+    this.chunks = [];
+  }
+
+  update(data: Uint8Array): void {
+    this.chunks.push(data);
+  }
+
+  async digest(): Promise<Uint8Array> {
+    const totalLength = this.chunks.reduce((s, c) => s + c.length, 0);
+    const combined = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const c of this.chunks) {
+      combined.set(c, offset);
+      offset += c.length;
+    }
+    const h = await crypto.subtle.digest("SHA-256", combined);
+    return new Uint8Array(h);
+  }
+}

package/src/uuid-bytes.ts

@@ -0,0 +1,20 @@
+export const WIRE_LOG_ID_BYTES = 32;
+
+export function toPaddedWire32(bytes: Uint8Array): Uint8Array {
+  if (bytes.length === WIRE_LOG_ID_BYTES) return bytes;
+  const out = new Uint8Array(WIRE_LOG_ID_BYTES);
+  if (bytes.length >= WIRE_LOG_ID_BYTES) {
+    out.set(bytes.slice(-WIRE_LOG_ID_BYTES));
+  } else {
+    out.set(bytes, WIRE_LOG_ID_BYTES - bytes.length);
+  }
+  return out;
+}
+
+export function fromPaddedWire32(wire: Uint8Array): Uint8Array {
+  if (wire.length === 16) return wire;
+  if (wire.length !== WIRE_LOG_ID_BYTES) {
+    throw new Error(`Expected ${WIRE_LOG_ID_BYTES}-byte wire log id`);
+  }
+  return wire.slice(-16);
+}

package/src/verify-grant-receipt-offline.ts

@@ -0,0 +1,145 @@
+import { verifyCoseSign1WithParsedKey } from "@forestrie/encoding";
+import {
+  calculateRoot,
+  verifyInclusion,
+  type Proof,
+} from "@forestrie/merklelog";
+import type { Grant } from "./grant.js";
+import { grantCommitmentHashFromGrant } from "./grant-commitment.js";
+import { decodeTrustRootFromGenesis } from "./decode-trust-root-from-genesis.js";
+import { es256ReceiptVerifyKeys } from "./decode-trust-root-cbor.js";
+import { univocityLeafHash } from "./leaf-commitment.js";
+import { parseReceipt } from "./parse-receipt.js";
+import type { ReceiptVerifyResult } from "./receipt-verify-result.js";
+import { SubtleHasher } from "./subtle-hasher.js";
+
+export type VerifyGrantReceiptOfflineInput = {
+  genesisCbor: Uint8Array;
+  receiptCbor: Uint8Array;
+  grant: Grant;
+  idtimestampBe8: Uint8Array;
+};
+
+function readIdtimestampBe8(bytes: Uint8Array): bigint {
+  if (!bytes || bytes.length < 8) {
+    throw new Error("idtimestamp required for receipt verification (8 bytes)");
+  }
+  const view =
+    bytes.length === 8
+      ? new DataView(bytes.buffer, bytes.byteOffset, 8)
+      : new DataView(bytes.buffer, bytes.byteOffset + bytes.length - 8, 8);
+  return view.getBigUint64(0, false);
+}
+
+async function verifySignatureAndInclusion(opts: {
+  receiptCbor: Uint8Array;
+  explicitPeak: Uint8Array | null;
+  proof: Proof;
+  leafHash: Uint8Array;
+  verifyKeys: CryptoKey[];
+}): Promise<ReceiptVerifyResult> {
+  const hasher = new SubtleHasher();
+  const leafIdx =
+    opts.proof.leafIndex !== undefined
+      ? opts.proof.leafIndex
+      : opts.proof.mmrIndex!;
+  const peak =
+    opts.explicitPeak !== null
+      ? opts.explicitPeak
+      : await calculateRoot(hasher, opts.leafHash, opts.proof, leafIdx);
+
+  let sigOk = false;
+  for (const candidateKey of opts.verifyKeys) {
+    sigOk = await verifyCoseSign1WithParsedKey(opts.receiptCbor, candidateKey, {
+      logPrefix: "grant-receipt-offline",
+      detachedPayload: peak,
+    });
+    if (sigOk) break;
+    if (opts.explicitPeak !== null) {
+      sigOk = await verifyCoseSign1WithParsedKey(
+        opts.receiptCbor,
+        candidateKey,
+        { logPrefix: "grant-receipt-offline" },
+      );
+      if (sigOk) break;
+    }
+  }
+
+  if (!sigOk) {
+    if (opts.explicitPeak !== null) {
+      const inclusionOk = await verifyInclusion(
+        hasher,
+        opts.leafHash,
+        opts.proof,
+        opts.explicitPeak,
+      );
+      return {
+        ok: false,
+        stage: "signature",
+        reason: inclusionOk ? "signature_invalid" : "signature_invalid",
+      };
+    }
+    return { ok: false, stage: "signature", reason: "signature_invalid" };
+  }
+
+  const inclusionOk = await verifyInclusion(
+    hasher,
+    opts.leafHash,
+    opts.proof,
+    peak,
+  );
+  if (!inclusionOk) {
+    return { ok: false, stage: "inclusion", reason: "inclusion_failed" };
+  }
+  return { ok: true, stage: "binding" };
+}
+
+/**
+ * Offline grant receipt verify (layers A–C, ADR-0045). Pure over bytes; no network.
+ */
+export async function verifyGrantReceiptOffline(
+  input: VerifyGrantReceiptOfflineInput,
+): Promise<ReceiptVerifyResult> {
+  let parsed: ReturnType<typeof parseReceipt>;
+  try {
+    parsed = parseReceipt(input.receiptCbor);
+  } catch {
+    return { ok: false, stage: "parse", reason: "receipt_malformed" };
+  }
+
+  let trustRoot;
+  try {
+    trustRoot = await decodeTrustRootFromGenesis(input.genesisCbor);
+  } catch {
+    return { ok: false, stage: "parse", reason: "genesis_invalid" };
+  }
+
+  const verifyKeys = es256ReceiptVerifyKeys([trustRoot]);
+  if (!verifyKeys.length) {
+    return { ok: false, stage: "signature", reason: "no_es256_trust_key" };
+  }
+
+  let inner: Uint8Array;
+  try {
+    inner = await grantCommitmentHashFromGrant(input.grant);
+  } catch {
+    return { ok: false, stage: "binding", reason: "grant_invalid" };
+  }
+
+  let idtimestamp: bigint;
+  try {
+    idtimestamp = readIdtimestampBe8(input.idtimestampBe8);
+  } catch {
+    return { ok: false, stage: "binding", reason: "idtimestamp_invalid" };
+  }
+
+  const leafHash = await univocityLeafHash(idtimestamp, inner);
+
+  return verifySignatureAndInclusion({
+    receiptCbor: input.receiptCbor,
+    explicitPeak: parsed.explicitPeak,
+    proof: parsed.proof,
+    leafHash,
+    verifyKeys: verifyKeys as CryptoKey[],
+  });
+}