@forestrie/receipt-verify 0.1.0

package/dist/parse-receipt.js

@@ -0,0 +1,91 @@
+import { decode as decodeCbor } from "cbor-x";
+const VDS_COSE_RECEIPT_PROOFS_TAG = 396;
+function unwrapCoseSign1Tag(value) {
+    if (value && typeof value === "object" && !(value instanceof Map)) {
+        const tagged = value;
+        if (Object.prototype.hasOwnProperty.call(tagged, "value") &&
+            tagged.tag === 18) {
+            return tagged.value;
+        }
+    }
+    return value;
+}
+function requireCoseSign1(value) {
+    if (!Array.isArray(value) || value.length !== 4) {
+        throw new Error("Receipt is not a COSE Sign1 array");
+    }
+    const [p, u, payload, sig] = value;
+    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,
+        payload,
+        sig,
+    ];
+}
+function toHeaderMap(value) {
+    if (value instanceof Map)
+        return value;
+    const out = new Map();
+    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) {
+    const decoded = decodeCbor(receiptBytes);
+    const unwrapped = unwrapCoseSign1Tag(decoded);
+    requireCoseSign1(unwrapped);
+    const coseSign1 = requireCoseSign1(unwrapped);
+    const payload = coseSign1[2];
+    let explicitPeak = 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;
+    const proofList = (proofsMap instanceof Map
+        ? proofsMap.get(-1)
+        : proofsMap[-1]);
+    if (!Array.isArray(proofList) || proofList.length === 0) {
+        throw new Error("Receipt proof -1 must be non-empty array");
+    }
+    const entry = proofList[0];
+    const mmrIndexRaw = entry instanceof Map ? entry.get(1) : entry[1];
+    const pathRaw = entry instanceof Map ? entry.get(2) : entry[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) => {
+        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/dist/receipt-verify-result.d.ts

@@ -0,0 +1,9 @@
+/** 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;
+};
+//# sourceMappingURL=receipt-verify-result.d.ts.map

package/dist/receipt-verify-result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"receipt-verify-result.d.ts","sourceRoot":"","sources":["../src/receipt-verify-result.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,MAAM,MAAM,kBAAkB,GAC1B,OAAO,GACP,WAAW,GACX,WAAW,GACX,SAAS,CAAC;AAEd,MAAM,MAAM,mBAAmB,GAAG;IAChC,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,EAAE,kBAAkB,CAAC;IAC1B,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC"}

package/dist/receipt-verify-result.js

@@ -0,0 +1 @@
+export {};

package/dist/root-verify-key.d.ts

@@ -0,0 +1,9 @@
+import { COSE_ALG_KS256 } from "./cose-key.js";
+export interface ParsedKs256RootKey {
+    kind: "KS256";
+    alg: typeof COSE_ALG_KS256;
+    address: Uint8Array;
+}
+export declare function isParsedKs256RootKey(key: unknown): key is ParsedKs256RootKey;
+export type RootVerifyKey = CryptoKey | ParsedKs256RootKey;
+//# sourceMappingURL=root-verify-key.d.ts.map

package/dist/root-verify-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-verify-key.d.ts","sourceRoot":"","sources":["../src/root-verify-key.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,OAAO,CAAC;IACd,GAAG,EAAE,OAAO,cAAc,CAAC;IAC3B,OAAO,EAAE,UAAU,CAAC;CACrB;AAED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,kBAAkB,CAQ5E;AAED,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,kBAAkB,CAAC"}

package/dist/root-verify-key.js

@@ -0,0 +1,7 @@
+export function isParsedKs256RootKey(key) {
+    return (typeof key === "object" &&
+        key !== null &&
+        key.kind === "KS256" &&
+        key.address instanceof Uint8Array &&
+        key.address.length === 20);
+}

package/dist/subtle-hasher.d.ts

@@ -0,0 +1,9 @@
+import type { Hasher } from "@forestrie/merklelog";
+/** Web Crypto SHA-256 hasher for Node and browser offline verify. */
+export declare class SubtleHasher implements Hasher {
+    private chunks;
+    reset(): void;
+    update(data: Uint8Array): void;
+    digest(): Promise<Uint8Array>;
+}
+//# sourceMappingURL=subtle-hasher.d.ts.map

package/dist/subtle-hasher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subtle-hasher.d.ts","sourceRoot":"","sources":["../src/subtle-hasher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAEnD,qEAAqE;AACrE,qBAAa,YAAa,YAAW,MAAM;IACzC,OAAO,CAAC,MAAM,CAAoB;IAElC,KAAK,IAAI,IAAI;IAIb,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IAIxB,MAAM,IAAI,OAAO,CAAC,UAAU,CAAC;CAWpC"}

package/dist/subtle-hasher.js

@@ -0,0 +1,21 @@
+/** Web Crypto SHA-256 hasher for Node and browser offline verify. */
+export class SubtleHasher {
+    chunks = [];
+    reset() {
+        this.chunks = [];
+    }
+    update(data) {
+        this.chunks.push(data);
+    }
+    async digest() {
+        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/dist/uuid-bytes.d.ts

@@ -0,0 +1,4 @@
+export declare const WIRE_LOG_ID_BYTES = 32;
+export declare function toPaddedWire32(bytes: Uint8Array): Uint8Array;
+export declare function fromPaddedWire32(wire: Uint8Array): Uint8Array;
+//# sourceMappingURL=uuid-bytes.d.ts.map

package/dist/uuid-bytes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid-bytes.d.ts","sourceRoot":"","sources":["../src/uuid-bytes.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAEpC,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAS5D;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAM7D"}

package/dist/uuid-bytes.js

@@ -0,0 +1,21 @@
+export const WIRE_LOG_ID_BYTES = 32;
+export function toPaddedWire32(bytes) {
+    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) {
+    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/dist/verify-grant-receipt-offline.d.ts

@@ -0,0 +1,13 @@
+import type { Grant } from "./grant.js";
+import type { ReceiptVerifyResult } from "./receipt-verify-result.js";
+export type VerifyGrantReceiptOfflineInput = {
+    genesisCbor: Uint8Array;
+    receiptCbor: Uint8Array;
+    grant: Grant;
+    idtimestampBe8: Uint8Array;
+};
+/**
+ * Offline grant receipt verify (layers A–C, ADR-0045). Pure over bytes; no network.
+ */
+export declare function verifyGrantReceiptOffline(input: VerifyGrantReceiptOfflineInput): Promise<ReceiptVerifyResult>;
+//# sourceMappingURL=verify-grant-receipt-offline.d.ts.map

package/dist/verify-grant-receipt-offline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-grant-receipt-offline.d.ts","sourceRoot":"","sources":["../src/verify-grant-receipt-offline.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAMxC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAGtE,MAAM,MAAM,8BAA8B,GAAG;IAC3C,WAAW,EAAE,UAAU,CAAC;IACxB,WAAW,EAAE,UAAU,CAAC;IACxB,KAAK,EAAE,KAAK,CAAC;IACb,cAAc,EAAE,UAAU,CAAC;CAC5B,CAAC;AA4EF;;GAEG;AACH,wBAAsB,yBAAyB,CAC7C,KAAK,EAAE,8BAA8B,GACpC,OAAO,CAAC,mBAAmB,CAAC,CA2C9B"}

package/dist/verify-grant-receipt-offline.js

@@ -0,0 +1,101 @@
+import { verifyCoseSign1WithParsedKey } from "@forestrie/encoding";
+import { calculateRoot, verifyInclusion, } from "@forestrie/merklelog";
+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 { SubtleHasher } from "./subtle-hasher.js";
+function readIdtimestampBe8(bytes) {
+    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) {
+    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) {
+    let parsed;
+    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;
+    try {
+        inner = await grantCommitmentHashFromGrant(input.grant);
+    }
+    catch {
+        return { ok: false, stage: "binding", reason: "grant_invalid" };
+    }
+    let idtimestamp;
+    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,
+    });
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@forestrie/receipt-verify",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "description": "Offline SCITT grant receipt verification (ADR-0045)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/forestrie/canopy.git",
+    "directory": "packages/libs/receipt-verify"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@noble/hashes": "^1.7.1",
+    "cbor-x": "^1.5.9",
+    "@forestrie/encoding": "0.0.1",
+    "@forestrie/merklelog": "0.0.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest --run",
+    "test:watch": "vitest"
+  }
+}

package/src/cose-key.ts

@@ -0,0 +1,9 @@
+export const COSE_ALG_ES256 = -7;
+export const COSE_ALG_KS256 = -65799;
+export const COSE_KEY_KTY = 1;
+export const COSE_KEY_ALG = 3;
+export const COSE_EC2_CRV = -1;
+export const COSE_EC2_X = -2;
+export const COSE_EC2_Y = -3;
+export const COSE_KTY_EC2 = 2;
+export const COSE_CRV_P256 = 1;

package/src/decode-forestrie-grant-cose.ts

@@ -0,0 +1,79 @@
+import { sha256 } from "@noble/hashes/sha256";
+import { decode as decodeCbor } from "cbor-x";
+import type { Grant } from "./grant.js";
+import {
+  HEADER_FORESTRIE_GRANT_V0,
+  HEADER_IDTIMESTAMP,
+} from "./forest-genesis-labels.js";
+import { decodeGrantPayload } from "./grant-codec.js";
+
+const IDTIMESTAMP_BYTES = 8;
+
+function toHeaderMap(
+  value: Map<number, unknown> | Record<string, unknown> | unknown,
+): Map<number, unknown> {
+  if (value instanceof Map) return value as Map<number, unknown>;
+  if (
+    typeof value === "object" &&
+    value !== null &&
+    !(value instanceof Uint8Array)
+  ) {
+    const out = new Map<number, unknown>();
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      const n = Number(k);
+      if (Number.isFinite(n)) out.set(n, v);
+    }
+    return out;
+  }
+  return new Map();
+}
+
+function digestEquals(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  let x = 0;
+  for (let i = 0; i < a.length; i++) x |= a[i]! ^ b[i]!;
+  return x === 0;
+}
+
+/**
+ * Decode Forestrie-Grant COSE Sign1 (Custodian transparent statement profile).
+ */
+export function decodeForestrieGrantCose(bytes: Uint8Array): {
+  grant: Grant;
+  idtimestampBe8: Uint8Array;
+} {
+  const raw = decodeCbor(bytes) as unknown;
+  const arr = Array.isArray(raw) ? raw : null;
+  if (!arr || arr.length !== 4) {
+    throw new Error("Forestrie-Grant must be COSE Sign1 (array of 4)");
+  }
+  const [, unprotectedRaw, payloadRaw] = arr as [
+    unknown,
+    Map<number, unknown> | Record<string, unknown>,
+    Uint8Array | null,
+    unknown,
+  ];
+  if (!(payloadRaw instanceof Uint8Array) || payloadRaw.length !== 32) {
+    throw new Error("Forestrie-Grant COSE payload must be 32-byte digest");
+  }
+  const unprotected = toHeaderMap(unprotectedRaw);
+  const embedded = unprotected.get(HEADER_FORESTRIE_GRANT_V0);
+  if (!(embedded instanceof Uint8Array) || embedded.length === 0) {
+    throw new Error("Forestrie-Grant missing unprotected -65538 grant CBOR");
+  }
+  if (!digestEquals(sha256(embedded), payloadRaw)) {
+    throw new Error("Forestrie-Grant digest mismatch");
+  }
+  const idtimestampVal = unprotected.get(HEADER_IDTIMESTAMP);
+  const idtimestampBe8 =
+    idtimestampVal instanceof Uint8Array &&
+    idtimestampVal.length >= IDTIMESTAMP_BYTES
+      ? idtimestampVal.length === IDTIMESTAMP_BYTES
+        ? idtimestampVal
+        : idtimestampVal.slice(-IDTIMESTAMP_BYTES)
+      : new Uint8Array(IDTIMESTAMP_BYTES);
+  return {
+    grant: decodeGrantPayload(embedded),
+    idtimestampBe8: new Uint8Array(idtimestampBe8),
+  };
+}

package/src/decode-trust-root-cbor.ts

@@ -0,0 +1,113 @@
+import { COSE_ALG_ES256, COSE_ALG_KS256 } from "@forestrie/encoding";
+import type { ParsedVerifyKey } from "@forestrie/encoding";
+import {
+  isParsedKs256RootKey,
+  type ParsedKs256RootKey,
+  type RootVerifyKey,
+} from "./root-verify-key.js";
+
+export async function importEs256PublicKeyFromGrantDataXy64(
+  xy: Uint8Array,
+): Promise<CryptoKey> {
+  if (xy.length !== 64) {
+    throw new Error(
+      "ES256 grantData must be 64 bytes (x||y) for raw public key import",
+    );
+  }
+  const raw = new Uint8Array(65);
+  raw[0] = 0x04;
+  raw.set(xy, 1);
+  return crypto.subtle.importKey(
+    "raw",
+    raw,
+    { name: "ECDSA", namedCurve: "P-256" },
+    false,
+    ["verify"],
+  );
+}
+
+function asUint8Array(v: unknown): Uint8Array | null {
+  if (v instanceof Uint8Array) return v;
+  return null;
+}
+
+function parseAlgInt(raw: unknown): number | null {
+  if (typeof raw === "number" && Number.isInteger(raw)) return raw;
+  if (typeof raw === "bigint") {
+    const n = Number(raw);
+    return Number.isSafeInteger(n) ? n : null;
+  }
+  if (typeof raw === "string") {
+    const n = Number(raw);
+    if (Number.isInteger(n)) return n;
+  }
+  return null;
+}
+
+function ks256RootFromAddress(address: Uint8Array): ParsedKs256RootKey {
+  return { kind: "KS256", alg: COSE_ALG_KS256, address };
+}
+
+function recordToTrustRootFields(decoded: unknown): Record<string, unknown> {
+  if (decoded instanceof Map) {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of decoded.entries()) {
+      out[String(k)] = v;
+    }
+    return out;
+  }
+  if (typeof decoded === "object" && decoded !== null) {
+    return decoded as Record<string, unknown>;
+  }
+  throw new Error("trust-root CBOR must be a map");
+}
+
+export async function decodeTrustRootCbor(
+  decoded: unknown,
+): Promise<RootVerifyKey> {
+  const fields = recordToTrustRootFields(decoded);
+  const algRaw = fields.alg;
+  const key = asUint8Array(fields.key);
+  const algInt = parseAlgInt(algRaw);
+
+  if (algInt === COSE_ALG_KS256) {
+    if (!key || key.length !== 20) {
+      throw new Error("KS256 trust-root key must be 20 bytes");
+    }
+    return ks256RootFromAddress(key);
+  }
+
+  if (algInt === COSE_ALG_ES256 && key) {
+    if (key.length !== 64) {
+      throw new Error("ES256 trust-root key must be 64 bytes (x||y)");
+    }
+    return importEs256PublicKeyFromGrantDataXy64(key);
+  }
+
+  if (typeof algRaw === "string" && algRaw.toUpperCase() === "KS256") {
+    if (!key || key.length !== 20) {
+      throw new Error("KS256 trust-root key must be 20 bytes");
+    }
+    return ks256RootFromAddress(key);
+  }
+
+  if (typeof algRaw === "string" && algRaw.toUpperCase() === "ES256") {
+    const x = asUint8Array(fields.x);
+    const y = asUint8Array(fields.y);
+    if (!x || x.length !== 32 || !y || y.length !== 32) {
+      throw new Error("ES256 trust-root x/y must be 32 bytes each");
+    }
+    const xy = new Uint8Array(64);
+    xy.set(x, 0);
+    xy.set(y, 32);
+    return importEs256PublicKeyFromGrantDataXy64(xy);
+  }
+
+  throw new Error(`unsupported trust-root alg ${String(algRaw)}`);
+}
+
+export function es256ReceiptVerifyKeys(
+  keys: RootVerifyKey[],
+): ParsedVerifyKey[] {
+  return keys.filter((k): k is CryptoKey => !isParsedKs256RootKey(k));
+}

package/src/decode-trust-root-from-genesis.ts

@@ -0,0 +1,87 @@
+import { decode as decodeCbor } from "cbor-x";
+import {
+  COSE_ALG_ES256,
+  COSE_CRV_P256,
+  COSE_EC2_CRV,
+  COSE_EC2_X,
+  COSE_EC2_Y,
+  COSE_KEY_ALG,
+  COSE_KEY_KTY,
+  COSE_KTY_EC2,
+} from "./cose-key.js";
+import {
+  FOREST_GENESIS_LABEL_BOOTSTRAP_KEY,
+  FOREST_GENESIS_LABEL_GENESIS_ALG,
+  FOREST_GENESIS_LABEL_GENESIS_VERSION,
+  FOREST_GENESIS_SCHEMA_V1,
+  FOREST_GENESIS_SCHEMA_V2,
+} from "./forest-genesis-labels.js";
+import { decodeTrustRootCbor } from "./decode-trust-root-cbor.js";
+import type { RootVerifyKey } from "./root-verify-key.js";
+
+function decodeBodyAsIntKeyMap(raw: unknown): Map<number, unknown> | null {
+  if (raw instanceof Map) return raw as Map<number, unknown>;
+  if (typeof raw === "object" && raw !== null && !Array.isArray(raw)) {
+    const out = new Map<number, unknown>();
+    for (const [k, v] of Object.entries(raw as Record<string, unknown>)) {
+      const n = Number(k);
+      if (Number.isFinite(n)) out.set(n, v);
+    }
+    return out;
+  }
+  return null;
+}
+
+function asGenesisUint8Array(v: unknown): Uint8Array | null {
+  return v instanceof Uint8Array ? v : null;
+}
+
+/**
+ * Extract receipt verify key from a forest genesis document CBOR blob.
+ * Offline path: genesis-only trust anchor (ADR-0045).
+ */
+export async function decodeTrustRootFromGenesis(
+  genesisCbor: Uint8Array,
+): Promise<RootVerifyKey> {
+  let raw: unknown;
+  try {
+    raw = decodeCbor(genesisCbor);
+  } catch {
+    throw new Error("genesis CBOR decode failed");
+  }
+  const m = decodeBodyAsIntKeyMap(raw);
+  if (!m) throw new Error("genesis document must be a CBOR map");
+
+  const versionRaw = m.get(FOREST_GENESIS_LABEL_GENESIS_VERSION);
+  if (versionRaw === FOREST_GENESIS_SCHEMA_V2) {
+    const alg = m.get(FOREST_GENESIS_LABEL_GENESIS_ALG);
+    const bootstrapKey = asGenesisUint8Array(
+      m.get(FOREST_GENESIS_LABEL_BOOTSTRAP_KEY),
+    );
+    if (bootstrapKey === null) {
+      throw new Error("v2 genesis missing bootstrapKey");
+    }
+    return decodeTrustRootCbor({ alg, key: bootstrapKey });
+  }
+
+  const kty = m.get(COSE_KEY_KTY);
+  const crv = m.get(COSE_EC2_CRV);
+  const x = asGenesisUint8Array(m.get(COSE_EC2_X));
+  const y = asGenesisUint8Array(m.get(COSE_EC2_Y));
+  if (kty === COSE_KTY_EC2 && crv === COSE_CRV_P256 && x && y) {
+    const alg = m.get(COSE_KEY_ALG);
+    if (alg !== undefined && alg !== COSE_ALG_ES256) {
+      throw new Error("genesis EC2 key must be ES256");
+    }
+    const xy = new Uint8Array(64);
+    xy.set(x, 0);
+    xy.set(y, 32);
+    return decodeTrustRootCbor({ alg: COSE_ALG_ES256, key: xy });
+  }
+
+  if (versionRaw === FOREST_GENESIS_SCHEMA_V1 || versionRaw === undefined) {
+    throw new Error("unsupported or invalid genesis schema for trust root");
+  }
+
+  throw new Error("unsupported genesis document");
+}

package/src/forest-genesis-labels.ts

@@ -0,0 +1,10 @@
+export const FOREST_GENESIS_LABEL_GENESIS_VERSION = -68009;
+export const FOREST_GENESIS_LABEL_GENESIS_ALG = -68014;
+export const FOREST_GENESIS_LABEL_BOOTSTRAP_KEY = -68015;
+export const FOREST_GENESIS_LABEL_UNIVOCITY_ADDR = -68011;
+export const FOREST_GENESIS_LABEL_CHAIN_ID = -68013;
+export const FOREST_GENESIS_SCHEMA_V2 = 2;
+export const FOREST_GENESIS_SCHEMA_V1 = 1;
+
+export const HEADER_IDTIMESTAMP = -65537;
+export const HEADER_FORESTRIE_GRANT_V0 = -65538;