@forestrie/receipt-verify 1.0.0 → 1.1.0

package/dist/chain-binding.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Genesis-bound chain binding: which univocity contract and chain a
+ * forest's on-chain checkpoints are anchored to, plus the forest's own log
+ * id (labels -68011 / -68013 / -68010). Bound once at genesis and public
+ * (ADR-0045) — the address and chain id are properties of the FOREST, not
+ * of the operator serving it. See {@link decodeChainBindingFromGenesis}.
+ * Mirrors mcp-resolve's `ChainBinding` (plan-2609-07 L3) so that consumer
+ * can delete its own copy, except `logId` here is the raw 32-byte wire
+ * value rather than a formatted UUID string.
+ */
+export interface ChainBinding {
+    /** `0x` + 40 lowercase hex univocity contract address. */
+    univocity: string;
+    chainId: number;
+    /** Raw 32 bytes of label -68010: 16 zero bytes then the 16-byte forest
+     *  bootstrap log id. */
+    logId: Uint8Array;
+}
+//# sourceMappingURL=chain-binding.d.ts.map

package/dist/chain-binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain-binding.d.ts","sourceRoot":"","sources":["../src/chain-binding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB;4BACwB;IACxB,KAAK,EAAE,UAAU,CAAC;CACnB"}

package/dist/chain-binding.js

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

package/dist/decode-chain-binding-from-genesis.d.ts

@@ -0,0 +1,15 @@
+import type { ChainBinding } from "./chain-binding.js";
+/**
+ * Decode the chain binding — univocity contract address, chain id, and the
+ * forest's own log id — out of a forest genesis document CBOR blob (labels
+ * -68011 / -68013 / -68010). Mirrors mcp-resolve's `genesis-binding.ts`
+ * `decodeChainBindingFromGenesis` (plan-2609-07 L3) so that consumer can
+ * delete its own copy, except `logId` here stays the raw 32-byte wire value
+ * rather than being reformatted as a UUID string.
+ *
+ * Throws a plain `Error` for any genesis document that does not decode into
+ * a usable chain binding: not CBOR, not a map, wrong schema version, or a
+ * label absent or mis-sized/mistyped.
+ */
+export declare function decodeChainBindingFromGenesis(genesis: Uint8Array): ChainBinding;
+//# sourceMappingURL=decode-chain-binding-from-genesis.d.ts.map

package/dist/decode-chain-binding-from-genesis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode-chain-binding-from-genesis.d.ts","sourceRoot":"","sources":["../src/decode-chain-binding-from-genesis.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAMvD;;;;;;;;;;;GAWG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,UAAU,GAClB,YAAY,CA4Cd"}

package/dist/decode-chain-binding-from-genesis.js

@@ -0,0 +1,55 @@
+import { decodeCborDeterministic } from "@forestrie/encoding";
+import { asGenesisUint8Array, decodeGenesisBodyAsIntKeyMap, } from "./decode-genesis-cbor-map.js";
+import { FOREST_GENESIS_LABEL_CHAIN_ID, FOREST_GENESIS_LABEL_GENESIS_VERSION, FOREST_GENESIS_LABEL_LOG_ID, FOREST_GENESIS_LABEL_UNIVOCITY_ADDR, FOREST_GENESIS_SCHEMA_V2, } from "./forest-genesis-labels.js";
+function bytesToLowerHex(bytes) {
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+/**
+ * Decode the chain binding — univocity contract address, chain id, and the
+ * forest's own log id — out of a forest genesis document CBOR blob (labels
+ * -68011 / -68013 / -68010). Mirrors mcp-resolve's `genesis-binding.ts`
+ * `decodeChainBindingFromGenesis` (plan-2609-07 L3) so that consumer can
+ * delete its own copy, except `logId` here stays the raw 32-byte wire value
+ * rather than being reformatted as a UUID string.
+ *
+ * Throws a plain `Error` for any genesis document that does not decode into
+ * a usable chain binding: not CBOR, not a map, wrong schema version, or a
+ * label absent or mis-sized/mistyped.
+ */
+export function decodeChainBindingFromGenesis(genesis) {
+    let raw;
+    try {
+        raw = decodeCborDeterministic(genesis);
+    }
+    catch (err) {
+        throw new Error(`genesis CBOR decode failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const m = decodeGenesisBodyAsIntKeyMap(raw);
+    if (!m)
+        throw new Error("genesis document must be a CBOR map");
+    const versionRaw = m.get(FOREST_GENESIS_LABEL_GENESIS_VERSION);
+    if (versionRaw === undefined) {
+        throw new Error("genesis version label absent");
+    }
+    const version = typeof versionRaw === "bigint" ? Number(versionRaw) : versionRaw;
+    if (version !== FOREST_GENESIS_SCHEMA_V2) {
+        throw new Error(`genesis version ${String(version)} is not ${FOREST_GENESIS_SCHEMA_V2}`);
+    }
+    const addr = asGenesisUint8Array(m.get(FOREST_GENESIS_LABEL_UNIVOCITY_ADDR));
+    if (!addr || addr.length !== 20) {
+        throw new Error("univocity address label absent or not 20 bytes");
+    }
+    const chainIdRaw = m.get(FOREST_GENESIS_LABEL_CHAIN_ID);
+    if (typeof chainIdRaw !== "string" || !/^[0-9]+$/.test(chainIdRaw)) {
+        throw new Error("chain id label absent or not a decimal string");
+    }
+    const logId = asGenesisUint8Array(m.get(FOREST_GENESIS_LABEL_LOG_ID));
+    if (!logId || logId.length !== 32) {
+        throw new Error("log id label absent or not 32 bytes");
+    }
+    return {
+        univocity: `0x${bytesToLowerHex(addr)}`,
+        chainId: Number(chainIdRaw),
+        logId,
+    };
+}

package/dist/decode-genesis-cbor-map.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Shared decode step for a genesis document's CBOR body: deterministic CBOR
+ * decodes an integer-keyed map either as a native `Map` or as a plain
+ * object (encoder-dependent), so callers that read genesis labels normalise
+ * to a `Map<number, unknown>` once here rather than each re-implementing
+ * the same fallback. Used by {@link decodeTrustRootFromGenesis} and
+ * {@link decodeChainBindingFromGenesis}.
+ */
+export declare function decodeGenesisBodyAsIntKeyMap(raw: unknown): Map<number, unknown> | null;
+/** Narrow a decoded genesis field to `Uint8Array`, or `null` if it is not one. */
+export declare function asGenesisUint8Array(v: unknown): Uint8Array | null;
+//# sourceMappingURL=decode-genesis-cbor-map.d.ts.map

package/dist/decode-genesis-cbor-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode-genesis-cbor-map.d.ts","sourceRoot":"","sources":["../src/decode-genesis-cbor-map.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,OAAO,GACX,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAW7B;AAED,kFAAkF;AAClF,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,OAAO,GAAG,UAAU,GAAG,IAAI,CAEjE"}

package/dist/decode-genesis-cbor-map.js

@@ -0,0 +1,26 @@
+/**
+ * Shared decode step for a genesis document's CBOR body: deterministic CBOR
+ * decodes an integer-keyed map either as a native `Map` or as a plain
+ * object (encoder-dependent), so callers that read genesis labels normalise
+ * to a `Map<number, unknown>` once here rather than each re-implementing
+ * the same fallback. Used by {@link decodeTrustRootFromGenesis} and
+ * {@link decodeChainBindingFromGenesis}.
+ */
+export function decodeGenesisBodyAsIntKeyMap(raw) {
+    if (raw instanceof Map)
+        return raw;
+    if (typeof raw === "object" && raw !== null && !Array.isArray(raw)) {
+        const out = new Map();
+        for (const [k, v] of Object.entries(raw)) {
+            const n = Number(k);
+            if (Number.isFinite(n))
+                out.set(n, v);
+        }
+        return out;
+    }
+    return null;
+}
+/** Narrow a decoded genesis field to `Uint8Array`, or `null` if it is not one. */
+export function asGenesisUint8Array(v) {
+    return v instanceof Uint8Array ? v : null;
+}

package/dist/decode-trust-root-from-genesis.d.ts

@@ -1,7 +1,25 @@
-import type { RootVerifyKey } from "./root-verify-key.js";
+import { type RootVerifyKey } from "./root-verify-key.js";
+import type { DecodedTrustRoot } from "./decoded-trust-root.js";
 /**
- * Extract receipt verify key from a forest genesis document CBOR blob.
- * Offline path: genesis-only trust anchor (ADR-0045).
+ * Extract the receipt verify key from a forest genesis document CBOR blob,
+ * alongside `bootstrapKeyXy` when the bootstrap key is ES256. Offline path:
+ * genesis-only trust anchor (ADR-0045). See {@link DecodedTrustRoot}.
+ * `bootstrapKeyXy` is read directly from the genesis-encoded bytes (never
+ * exported from the non-extractable `CryptoKey` in `key`), and is
+ * `undefined` for a KS256 v2 bootstrap key (an on-chain address — there is
+ * no P-256 public key to give up in that case).
+ *
+ * This is the single decode path: {@link decodeTrustRootFromGenesis} is
+ * `(await decodeTrustRootDetailsFromGenesis(genesisCbor)).key`.
+ */
+export declare function decodeTrustRootDetailsFromGenesis(genesisCbor: Uint8Array): Promise<DecodedTrustRoot>;
+/**
+ * Extract the receipt verify key from a forest genesis document CBOR blob.
+ * Offline path: genesis-only trust anchor (ADR-0045). The origin/main
+ * signature and behaviour (including a KS256 v2 bootstrap key resolving to
+ * the `ParsedKs256RootKey` on-chain address, not a throw): callers pinned
+ * to `RootVerifyKey` keep working unchanged. For the raw bootstrap public
+ * key bytes as well, use {@link decodeTrustRootDetailsFromGenesis}.
  */
 export declare function decodeTrustRootFromGenesis(genesisCbor: Uint8Array): Promise<RootVerifyKey>;
 //# sourceMappingURL=decode-trust-root-from-genesis.d.ts.map

package/dist/decode-trust-root-from-genesis.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decode-trust-root-from-genesis.d.ts","sourceRoot":"","sources":["../src/decode-trust-root-from-genesis.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAmB1D;;;GAGG;AACH,wBAAsB,0BAA0B,CAC9C,WAAW,EAAE,UAAU,GACtB,OAAO,CAAC,aAAa,CAAC,CA0CxB"}
+{"version":3,"file":"decode-trust-root-from-genesis.d.ts","sourceRoot":"","sources":["../src/decode-trust-root-from-genesis.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAKhF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE;;;;;;;;;;;GAWG;AACH,wBAAsB,iCAAiC,CACrD,WAAW,EAAE,UAAU,GACtB,OAAO,CAAC,gBAAgB,CAAC,CA+C3B;AAED;;;;;;;GAOG;AACH,wBAAsB,0BAA0B,CAC9C,WAAW,EAAE,UAAU,GACtB,OAAO,CAAC,aAAa,CAAC,CAExB"}

package/dist/decode-trust-root-from-genesis.js

@@ -2,28 +2,21 @@ import { decodeCborDeterministic } from "@forestrie/encoding";
 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";
-function decodeBodyAsIntKeyMap(raw) {
-    if (raw instanceof Map)
-        return raw;
-    if (typeof raw === "object" && raw !== null && !Array.isArray(raw)) {
-        const out = new Map();
-        for (const [k, v] of Object.entries(raw)) {
-            const n = Number(k);
-            if (Number.isFinite(n))
-                out.set(n, v);
-        }
-        return out;
-    }
-    return null;
-}
-function asGenesisUint8Array(v) {
-    return v instanceof Uint8Array ? v : null;
-}
+import { isParsedKs256RootKey } from "./root-verify-key.js";
+import { asGenesisUint8Array, decodeGenesisBodyAsIntKeyMap, } from "./decode-genesis-cbor-map.js";
 /**
- * Extract receipt verify key from a forest genesis document CBOR blob.
- * Offline path: genesis-only trust anchor (ADR-0045).
+ * Extract the receipt verify key from a forest genesis document CBOR blob,
+ * alongside `bootstrapKeyXy` when the bootstrap key is ES256. Offline path:
+ * genesis-only trust anchor (ADR-0045). See {@link DecodedTrustRoot}.
+ * `bootstrapKeyXy` is read directly from the genesis-encoded bytes (never
+ * exported from the non-extractable `CryptoKey` in `key`), and is
+ * `undefined` for a KS256 v2 bootstrap key (an on-chain address — there is
+ * no P-256 public key to give up in that case).
+ *
+ * This is the single decode path: {@link decodeTrustRootFromGenesis} is
+ * `(await decodeTrustRootDetailsFromGenesis(genesisCbor)).key`.
  */
-export async function decodeTrustRootFromGenesis(genesisCbor) {
+export async function decodeTrustRootDetailsFromGenesis(genesisCbor) {
     let raw;
     try {
         raw = decodeCborDeterministic(genesisCbor);
@@ -31,7 +24,7 @@ export async function decodeTrustRootFromGenesis(genesisCbor) {
     catch {
         throw new Error("genesis CBOR decode failed");
     }
-    const m = decodeBodyAsIntKeyMap(raw);
+    const m = decodeGenesisBodyAsIntKeyMap(raw);
     if (!m)
         throw new Error("genesis document must be a CBOR map");
     const versionRaw = m.get(FOREST_GENESIS_LABEL_GENESIS_VERSION);
@@ -41,7 +34,11 @@ export async function decodeTrustRootFromGenesis(genesisCbor) {
         if (bootstrapKey === null) {
             throw new Error("v2 genesis missing bootstrapKey");
         }
-        return decodeTrustRootCbor({ alg, key: bootstrapKey });
+        const key = await decodeTrustRootCbor({ alg, key: bootstrapKey });
+        return {
+            key,
+            bootstrapKeyXy: isParsedKs256RootKey(key) ? undefined : bootstrapKey,
+        };
     }
     const kty = m.get(COSE_KEY_KTY);
     const crv = m.get(COSE_EC2_CRV);
@@ -55,10 +52,22 @@ export async function decodeTrustRootFromGenesis(genesisCbor) {
         const xy = new Uint8Array(64);
         xy.set(x, 0);
         xy.set(y, 32);
-        return decodeTrustRootCbor({ alg: COSE_ALG_ES256, key: xy });
+        const key = await decodeTrustRootCbor({ alg: COSE_ALG_ES256, key: xy });
+        return { key, bootstrapKeyXy: 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");
 }
+/**
+ * Extract the receipt verify key from a forest genesis document CBOR blob.
+ * Offline path: genesis-only trust anchor (ADR-0045). The origin/main
+ * signature and behaviour (including a KS256 v2 bootstrap key resolving to
+ * the `ParsedKs256RootKey` on-chain address, not a throw): callers pinned
+ * to `RootVerifyKey` keep working unchanged. For the raw bootstrap public
+ * key bytes as well, use {@link decodeTrustRootDetailsFromGenesis}.
+ */
+export async function decodeTrustRootFromGenesis(genesisCbor) {
+    return (await decodeTrustRootDetailsFromGenesis(genesisCbor)).key;
+}

package/dist/decoded-trust-root.d.ts

@@ -0,0 +1,17 @@
+import type { RootVerifyKey } from "./root-verify-key.js";
+/**
+ * Result of {@link decodeTrustRootDetailsFromGenesis}: the decoded verify
+ * key (an ES256 `CryptoKey`, or a KS256 on-chain address) plus, for the
+ * ES256 case, the raw 64-byte x||y P-256 public key coordinates the genesis
+ * document carries. `bootstrapKeyXy` is read directly from the
+ * genesis-encoded bytes, not exported from `key` (`key` stays
+ * non-extractable) — plan-2609-07 L3, for callers that need the
+ * serialisable public key material the `CryptoKey` cannot give up.
+ * `bootstrapKeyXy` is `undefined` for a KS256 v2 bootstrap key (an on-chain
+ * address — there is no P-256 public key to give up).
+ */
+export interface DecodedTrustRoot {
+    key: RootVerifyKey;
+    bootstrapKeyXy?: Uint8Array;
+}
+//# sourceMappingURL=decoded-trust-root.d.ts.map

package/dist/decoded-trust-root.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decoded-trust-root.d.ts","sourceRoot":"","sources":["../src/decoded-trust-root.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;;;;;;;;;GAUG;AACH,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,aAAa,CAAC;IACnB,cAAc,CAAC,EAAE,UAAU,CAAC;CAC7B"}

package/dist/decoded-trust-root.js

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

package/dist/forest-genesis-labels.d.ts

@@ -1,6 +1,13 @@
 export declare const FOREST_GENESIS_LABEL_GENESIS_VERSION = -68009;
 export declare const FOREST_GENESIS_LABEL_GENESIS_ALG = -68014;
 export declare const FOREST_GENESIS_LABEL_BOOTSTRAP_KEY = -68015;
+/**
+ * The forest's own log id, wire-encoded as 32 bytes: 16 zero bytes then the
+ * 16-byte forest bootstrap log id (plan-2609-07 L3; mirrors mcp-resolve's
+ * `genesis-binding.ts` naming so that consumer can import this instead of
+ * defining it locally). See {@link decodeChainBindingFromGenesis}.
+ */
+export declare const FOREST_GENESIS_LABEL_LOG_ID = -68010;
 export declare const FOREST_GENESIS_LABEL_UNIVOCITY_ADDR = -68011;
 export declare const FOREST_GENESIS_LABEL_CHAIN_ID = -68013;
 export declare const FOREST_GENESIS_SCHEMA_V2 = 2;

package/dist/forest-genesis-labels.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"forest-genesis-labels.d.ts","sourceRoot":"","sources":["../src/forest-genesis-labels.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,oCAAoC,SAAS,CAAC;AAC3D,eAAO,MAAM,gCAAgC,SAAS,CAAC;AACvD,eAAO,MAAM,kCAAkC,SAAS,CAAC;AACzD,eAAO,MAAM,mCAAmC,SAAS,CAAC;AAC1D,eAAO,MAAM,6BAA6B,SAAS,CAAC;AACpD,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAC1C,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C,eAAO,MAAM,kBAAkB,SAAS,CAAC;AACzC,eAAO,MAAM,yBAAyB,SAAS,CAAC"}
+{"version":3,"file":"forest-genesis-labels.d.ts","sourceRoot":"","sources":["../src/forest-genesis-labels.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,oCAAoC,SAAS,CAAC;AAC3D,eAAO,MAAM,gCAAgC,SAAS,CAAC;AACvD,eAAO,MAAM,kCAAkC,SAAS,CAAC;AACzD;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,SAAS,CAAC;AAClD,eAAO,MAAM,mCAAmC,SAAS,CAAC;AAC1D,eAAO,MAAM,6BAA6B,SAAS,CAAC;AACpD,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAC1C,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C,eAAO,MAAM,kBAAkB,SAAS,CAAC;AACzC,eAAO,MAAM,yBAAyB,SAAS,CAAC"}

package/dist/forest-genesis-labels.js

@@ -1,6 +1,13 @@
 export const FOREST_GENESIS_LABEL_GENESIS_VERSION = -68009;
 export const FOREST_GENESIS_LABEL_GENESIS_ALG = -68014;
 export const FOREST_GENESIS_LABEL_BOOTSTRAP_KEY = -68015;
+/**
+ * The forest's own log id, wire-encoded as 32 bytes: 16 zero bytes then the
+ * 16-byte forest bootstrap log id (plan-2609-07 L3; mirrors mcp-resolve's
+ * `genesis-binding.ts` naming so that consumer can import this instead of
+ * defining it locally). See {@link decodeChainBindingFromGenesis}.
+ */
+export const FOREST_GENESIS_LABEL_LOG_ID = -68010;
 export const FOREST_GENESIS_LABEL_UNIVOCITY_ADDR = -68011;
 export const FOREST_GENESIS_LABEL_CHAIN_ID = -68013;
 export const FOREST_GENESIS_SCHEMA_V2 = 2;

package/dist/index.d.ts

@@ -14,7 +14,27 @@ export type { FreshenReceiptInput, FreshenReceiptResult, } from "./freshen-recei
  * re-exported here to preserve the receipt-verify public surface.
  */
 export { peakMMRIndexes } from "@forestrie/merklelog";
-export { decodeTrustRootFromGenesis } from "./decode-trust-root-from-genesis.js";
+/**
+ * `decodeTrustRootFromGenesis` keeps its origin/main signature and
+ * behaviour (`Promise<RootVerifyKey>`, including a KS256 v2 bootstrap key
+ * resolving without a throw) so pinned consumers (mcp-verify 1.0.0) are
+ * unaffected. `decodeTrustRootDetailsFromGenesis` is the additive sibling
+ * (plan-2609-07 L3) carrying `bootstrapKeyXy` alongside `key`.
+ */
+export { decodeTrustRootDetailsFromGenesis, decodeTrustRootFromGenesis, } from "./decode-trust-root-from-genesis.js";
+export type { DecodedTrustRoot } from "./decoded-trust-root.js";
+/**
+ * Genesis document label constants (plan-2609-07 L3): exported from the
+ * package root so consumers stop redefining them locally (mcp-resolve's own
+ * `genesis-binding.ts` did, before this).
+ */
+export { FOREST_GENESIS_LABEL_BOOTSTRAP_KEY, FOREST_GENESIS_LABEL_CHAIN_ID, FOREST_GENESIS_LABEL_GENESIS_ALG, FOREST_GENESIS_LABEL_GENESIS_VERSION, FOREST_GENESIS_LABEL_LOG_ID, FOREST_GENESIS_LABEL_UNIVOCITY_ADDR, } from "./forest-genesis-labels.js";
+/**
+ * Genesis-bound chain binding (plan-2609-07 L3): mirrors mcp-resolve's own
+ * `decodeChainBindingFromGenesis` so that consumer can delete its copy.
+ */
+export { decodeChainBindingFromGenesis } from "./decode-chain-binding-from-genesis.js";
+export type { ChainBinding } from "./chain-binding.js";
 export { verifyGrantReceiptOffline } from "./verify-grant-receipt-offline.js";
 export { verifyReceiptOffline } from "./verify-grant-receipt-offline.js";
 /**

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -7,7 +7,25 @@ export { freshenReceipt } from "./freshen-receipt.js";
  * re-exported here to preserve the receipt-verify public surface.
  */
 export { peakMMRIndexes } from "@forestrie/merklelog";
-export { decodeTrustRootFromGenesis } from "./decode-trust-root-from-genesis.js";
+/**
+ * `decodeTrustRootFromGenesis` keeps its origin/main signature and
+ * behaviour (`Promise<RootVerifyKey>`, including a KS256 v2 bootstrap key
+ * resolving without a throw) so pinned consumers (mcp-verify 1.0.0) are
+ * unaffected. `decodeTrustRootDetailsFromGenesis` is the additive sibling
+ * (plan-2609-07 L3) carrying `bootstrapKeyXy` alongside `key`.
+ */
+export { decodeTrustRootDetailsFromGenesis, decodeTrustRootFromGenesis, } from "./decode-trust-root-from-genesis.js";
+/**
+ * Genesis document label constants (plan-2609-07 L3): exported from the
+ * package root so consumers stop redefining them locally (mcp-resolve's own
+ * `genesis-binding.ts` did, before this).
+ */
+export { FOREST_GENESIS_LABEL_BOOTSTRAP_KEY, FOREST_GENESIS_LABEL_CHAIN_ID, FOREST_GENESIS_LABEL_GENESIS_ALG, FOREST_GENESIS_LABEL_GENESIS_VERSION, FOREST_GENESIS_LABEL_LOG_ID, FOREST_GENESIS_LABEL_UNIVOCITY_ADDR, } from "./forest-genesis-labels.js";
+/**
+ * Genesis-bound chain binding (plan-2609-07 L3): mirrors mcp-resolve's own
+ * `decodeChainBindingFromGenesis` so that consumer can delete its copy.
+ */
+export { decodeChainBindingFromGenesis } from "./decode-chain-binding-from-genesis.js";
 export { verifyGrantReceiptOffline } from "./verify-grant-receipt-offline.js";
 export { verifyReceiptOffline } from "./verify-grant-receipt-offline.js";
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forestrie/receipt-verify",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "license": "MIT",
   "type": "module",
   "description": "Offline SCITT grant receipt verification (ADR-0045)",
@@ -28,9 +28,9 @@
   ],
   "dependencies": {
     "@noble/hashes": "^1.7.1",
-    "@forestrie/chain-rpc": "0.2.0",
-    "@forestrie/encoding": "0.7.0",
-    "@forestrie/merklelog": "0.3.0"
+    "@forestrie/chain-rpc": "0.3.0",
+    "@forestrie/merklelog": "0.3.0",
+    "@forestrie/encoding": "0.7.0"
   },
   "devDependencies": {
     "esbuild": "^0.24.0",

package/src/chain-binding.ts

@@ -0,0 +1,18 @@
+/**
+ * Genesis-bound chain binding: which univocity contract and chain a
+ * forest's on-chain checkpoints are anchored to, plus the forest's own log
+ * id (labels -68011 / -68013 / -68010). Bound once at genesis and public
+ * (ADR-0045) — the address and chain id are properties of the FOREST, not
+ * of the operator serving it. See {@link decodeChainBindingFromGenesis}.
+ * Mirrors mcp-resolve's `ChainBinding` (plan-2609-07 L3) so that consumer
+ * can delete its own copy, except `logId` here is the raw 32-byte wire
+ * value rather than a formatted UUID string.
+ */
+export interface ChainBinding {
+  /** `0x` + 40 lowercase hex univocity contract address. */
+  univocity: string;
+  chainId: number;
+  /** Raw 32 bytes of label -68010: 16 zero bytes then the 16-byte forest
+   *  bootstrap log id. */
+  logId: Uint8Array;
+}

package/src/decode-chain-binding-from-genesis.ts

@@ -0,0 +1,77 @@
+import { decodeCborDeterministic } from "@forestrie/encoding";
+import {
+  asGenesisUint8Array,
+  decodeGenesisBodyAsIntKeyMap,
+} from "./decode-genesis-cbor-map.js";
+import {
+  FOREST_GENESIS_LABEL_CHAIN_ID,
+  FOREST_GENESIS_LABEL_GENESIS_VERSION,
+  FOREST_GENESIS_LABEL_LOG_ID,
+  FOREST_GENESIS_LABEL_UNIVOCITY_ADDR,
+  FOREST_GENESIS_SCHEMA_V2,
+} from "./forest-genesis-labels.js";
+import type { ChainBinding } from "./chain-binding.js";
+
+function bytesToLowerHex(bytes: Uint8Array): string {
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+/**
+ * Decode the chain binding — univocity contract address, chain id, and the
+ * forest's own log id — out of a forest genesis document CBOR blob (labels
+ * -68011 / -68013 / -68010). Mirrors mcp-resolve's `genesis-binding.ts`
+ * `decodeChainBindingFromGenesis` (plan-2609-07 L3) so that consumer can
+ * delete its own copy, except `logId` here stays the raw 32-byte wire value
+ * rather than being reformatted as a UUID string.
+ *
+ * Throws a plain `Error` for any genesis document that does not decode into
+ * a usable chain binding: not CBOR, not a map, wrong schema version, or a
+ * label absent or mis-sized/mistyped.
+ */
+export function decodeChainBindingFromGenesis(
+  genesis: Uint8Array,
+): ChainBinding {
+  let raw: unknown;
+  try {
+    raw = decodeCborDeterministic(genesis);
+  } catch (err) {
+    throw new Error(
+      `genesis CBOR decode failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  const m = decodeGenesisBodyAsIntKeyMap(raw);
+  if (!m) throw new Error("genesis document must be a CBOR map");
+
+  const versionRaw = m.get(FOREST_GENESIS_LABEL_GENESIS_VERSION);
+  if (versionRaw === undefined) {
+    throw new Error("genesis version label absent");
+  }
+  const version =
+    typeof versionRaw === "bigint" ? Number(versionRaw) : versionRaw;
+  if (version !== FOREST_GENESIS_SCHEMA_V2) {
+    throw new Error(
+      `genesis version ${String(version)} is not ${FOREST_GENESIS_SCHEMA_V2}`,
+    );
+  }
+
+  const addr = asGenesisUint8Array(m.get(FOREST_GENESIS_LABEL_UNIVOCITY_ADDR));
+  if (!addr || addr.length !== 20) {
+    throw new Error("univocity address label absent or not 20 bytes");
+  }
+
+  const chainIdRaw = m.get(FOREST_GENESIS_LABEL_CHAIN_ID);
+  if (typeof chainIdRaw !== "string" || !/^[0-9]+$/.test(chainIdRaw)) {
+    throw new Error("chain id label absent or not a decimal string");
+  }
+
+  const logId = asGenesisUint8Array(m.get(FOREST_GENESIS_LABEL_LOG_ID));
+  if (!logId || logId.length !== 32) {
+    throw new Error("log id label absent or not 32 bytes");
+  }
+
+  return {
+    univocity: `0x${bytesToLowerHex(addr)}`,
+    chainId: Number(chainIdRaw),
+    logId,
+  };
+}

package/src/decode-genesis-cbor-map.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared decode step for a genesis document's CBOR body: deterministic CBOR
+ * decodes an integer-keyed map either as a native `Map` or as a plain
+ * object (encoder-dependent), so callers that read genesis labels normalise
+ * to a `Map<number, unknown>` once here rather than each re-implementing
+ * the same fallback. Used by {@link decodeTrustRootFromGenesis} and
+ * {@link decodeChainBindingFromGenesis}.
+ */
+export function decodeGenesisBodyAsIntKeyMap(
+  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;
+}
+
+/** Narrow a decoded genesis field to `Uint8Array`, or `null` if it is not one. */
+export function asGenesisUint8Array(v: unknown): Uint8Array | null {
+  return v instanceof Uint8Array ? v : null;
+}

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

@@ -17,39 +17,35 @@ import {
   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;
-}
+import { isParsedKs256RootKey, type RootVerifyKey } from "./root-verify-key.js";
+import {
+  asGenesisUint8Array,
+  decodeGenesisBodyAsIntKeyMap,
+} from "./decode-genesis-cbor-map.js";
+import type { DecodedTrustRoot } from "./decoded-trust-root.js";
 
 /**
- * Extract receipt verify key from a forest genesis document CBOR blob.
- * Offline path: genesis-only trust anchor (ADR-0045).
+ * Extract the receipt verify key from a forest genesis document CBOR blob,
+ * alongside `bootstrapKeyXy` when the bootstrap key is ES256. Offline path:
+ * genesis-only trust anchor (ADR-0045). See {@link DecodedTrustRoot}.
+ * `bootstrapKeyXy` is read directly from the genesis-encoded bytes (never
+ * exported from the non-extractable `CryptoKey` in `key`), and is
+ * `undefined` for a KS256 v2 bootstrap key (an on-chain address — there is
+ * no P-256 public key to give up in that case).
+ *
+ * This is the single decode path: {@link decodeTrustRootFromGenesis} is
+ * `(await decodeTrustRootDetailsFromGenesis(genesisCbor)).key`.
  */
-export async function decodeTrustRootFromGenesis(
+export async function decodeTrustRootDetailsFromGenesis(
   genesisCbor: Uint8Array,
-): Promise<RootVerifyKey> {
+): Promise<DecodedTrustRoot> {
   let raw: unknown;
   try {
     raw = decodeCborDeterministic(genesisCbor);
   } catch {
     throw new Error("genesis CBOR decode failed");
   }
-  const m = decodeBodyAsIntKeyMap(raw);
+  const m = decodeGenesisBodyAsIntKeyMap(raw);
   if (!m) throw new Error("genesis document must be a CBOR map");
 
   const versionRaw = m.get(FOREST_GENESIS_LABEL_GENESIS_VERSION);
@@ -61,7 +57,11 @@ export async function decodeTrustRootFromGenesis(
     if (bootstrapKey === null) {
       throw new Error("v2 genesis missing bootstrapKey");
     }
-    return decodeTrustRootCbor({ alg, key: bootstrapKey });
+    const key = await decodeTrustRootCbor({ alg, key: bootstrapKey });
+    return {
+      key,
+      bootstrapKeyXy: isParsedKs256RootKey(key) ? undefined : bootstrapKey,
+    };
   }
 
   const kty = m.get(COSE_KEY_KTY);
@@ -76,7 +76,8 @@ export async function decodeTrustRootFromGenesis(
     const xy = new Uint8Array(64);
     xy.set(x, 0);
     xy.set(y, 32);
-    return decodeTrustRootCbor({ alg: COSE_ALG_ES256, key: xy });
+    const key = await decodeTrustRootCbor({ alg: COSE_ALG_ES256, key: xy });
+    return { key, bootstrapKeyXy: xy };
   }
 
   if (versionRaw === FOREST_GENESIS_SCHEMA_V1 || versionRaw === undefined) {
@@ -85,3 +86,17 @@ export async function decodeTrustRootFromGenesis(
 
   throw new Error("unsupported genesis document");
 }
+
+/**
+ * Extract the receipt verify key from a forest genesis document CBOR blob.
+ * Offline path: genesis-only trust anchor (ADR-0045). The origin/main
+ * signature and behaviour (including a KS256 v2 bootstrap key resolving to
+ * the `ParsedKs256RootKey` on-chain address, not a throw): callers pinned
+ * to `RootVerifyKey` keep working unchanged. For the raw bootstrap public
+ * key bytes as well, use {@link decodeTrustRootDetailsFromGenesis}.
+ */
+export async function decodeTrustRootFromGenesis(
+  genesisCbor: Uint8Array,
+): Promise<RootVerifyKey> {
+  return (await decodeTrustRootDetailsFromGenesis(genesisCbor)).key;
+}

package/src/decoded-trust-root.ts

@@ -0,0 +1,17 @@
+import type { RootVerifyKey } from "./root-verify-key.js";
+
+/**
+ * Result of {@link decodeTrustRootDetailsFromGenesis}: the decoded verify
+ * key (an ES256 `CryptoKey`, or a KS256 on-chain address) plus, for the
+ * ES256 case, the raw 64-byte x||y P-256 public key coordinates the genesis
+ * document carries. `bootstrapKeyXy` is read directly from the
+ * genesis-encoded bytes, not exported from `key` (`key` stays
+ * non-extractable) — plan-2609-07 L3, for callers that need the
+ * serialisable public key material the `CryptoKey` cannot give up.
+ * `bootstrapKeyXy` is `undefined` for a KS256 v2 bootstrap key (an on-chain
+ * address — there is no P-256 public key to give up).
+ */
+export interface DecodedTrustRoot {
+  key: RootVerifyKey;
+  bootstrapKeyXy?: Uint8Array;
+}

package/src/forest-genesis-labels.ts

@@ -1,6 +1,13 @@
 export const FOREST_GENESIS_LABEL_GENESIS_VERSION = -68009;
 export const FOREST_GENESIS_LABEL_GENESIS_ALG = -68014;
 export const FOREST_GENESIS_LABEL_BOOTSTRAP_KEY = -68015;
+/**
+ * The forest's own log id, wire-encoded as 32 bytes: 16 zero bytes then the
+ * 16-byte forest bootstrap log id (plan-2609-07 L3; mirrors mcp-resolve's
+ * `genesis-binding.ts` naming so that consumer can import this instead of
+ * defining it locally). See {@link decodeChainBindingFromGenesis}.
+ */
+export const FOREST_GENESIS_LABEL_LOG_ID = -68010;
 export const FOREST_GENESIS_LABEL_UNIVOCITY_ADDR = -68011;
 export const FOREST_GENESIS_LABEL_CHAIN_ID = -68013;
 export const FOREST_GENESIS_SCHEMA_V2 = 2;

package/src/index.ts

@@ -31,7 +31,37 @@ export type {
  * re-exported here to preserve the receipt-verify public surface.
  */
 export { peakMMRIndexes } from "@forestrie/merklelog";
-export { decodeTrustRootFromGenesis } from "./decode-trust-root-from-genesis.js";
+/**
+ * `decodeTrustRootFromGenesis` keeps its origin/main signature and
+ * behaviour (`Promise<RootVerifyKey>`, including a KS256 v2 bootstrap key
+ * resolving without a throw) so pinned consumers (mcp-verify 1.0.0) are
+ * unaffected. `decodeTrustRootDetailsFromGenesis` is the additive sibling
+ * (plan-2609-07 L3) carrying `bootstrapKeyXy` alongside `key`.
+ */
+export {
+  decodeTrustRootDetailsFromGenesis,
+  decodeTrustRootFromGenesis,
+} from "./decode-trust-root-from-genesis.js";
+export type { DecodedTrustRoot } from "./decoded-trust-root.js";
+/**
+ * Genesis document label constants (plan-2609-07 L3): exported from the
+ * package root so consumers stop redefining them locally (mcp-resolve's own
+ * `genesis-binding.ts` did, before this).
+ */
+export {
+  FOREST_GENESIS_LABEL_BOOTSTRAP_KEY,
+  FOREST_GENESIS_LABEL_CHAIN_ID,
+  FOREST_GENESIS_LABEL_GENESIS_ALG,
+  FOREST_GENESIS_LABEL_GENESIS_VERSION,
+  FOREST_GENESIS_LABEL_LOG_ID,
+  FOREST_GENESIS_LABEL_UNIVOCITY_ADDR,
+} from "./forest-genesis-labels.js";
+/**
+ * Genesis-bound chain binding (plan-2609-07 L3): mirrors mcp-resolve's own
+ * `decodeChainBindingFromGenesis` so that consumer can delete its copy.
+ */
+export { decodeChainBindingFromGenesis } from "./decode-chain-binding-from-genesis.js";
+export type { ChainBinding } from "./chain-binding.js";
 export { verifyGrantReceiptOffline } from "./verify-grant-receipt-offline.js";
 export { verifyReceiptOffline } from "./verify-grant-receipt-offline.js";
 /**