@forestrie/receipt-verify 0.12.0 → 1.1.0

package/dist/verify-endorsed-leaf.js

@@ -0,0 +1,189 @@
+/**
+ * The single offline rung for a passkey-rooted log (devdocs ADR-0065 §5,
+ * plan-2608-14 1.2). From public artifacts only — the log root (on-chain
+ * `logRootKey` == the grant's `grantData`), the exact registered leaf bytes,
+ * the receipt and its idtimestamp — reconstruct:
+ *
+ *   root → endorsement (-65801 inside the leaf; -65800 verify under the
+ *   root, UV per the grant flag, window from the payload)
+ *     → session key
+ *       → leaf: kid == session x, ES256 signature under the session key
+ *         → receipt: leaf bytes hash to the receipted index (inclusion),
+ *           receipted idtimestamp ∈ [notBefore, notAfter]
+ *
+ * There is exactly one route and no fallback: a leaf without an endorsement
+ * is not verified under the root here (that is the plain
+ * `verifyReceiptOffline*` path for root-signed logs), and the ADR-0064
+ * export-fed rung (`resolveEndorsedSessionKey` over a `/receipts` export)
+ * is gone — the endorsement an auditor needs is inside the committed leaf.
+ *
+ * Tampering closes both ways (ADR-0065 §5): editing the endorsement changes
+ * `contentHash`, so inclusion fails; substituting a different valid
+ * endorsement changes the session key, so the leaf signature fails.
+ */
+import { COSE_LABEL_SESSION_KEY_ENDORSEMENT, coseUnprotectedToMap, decodeCborDeterministic, decodeCoseSign1, verifyCoseSign1WithParsedKey, } from "@forestrie/encoding";
+import { importEs256PublicKeyFromGrantDataXy64 } from "./decode-trust-root-cbor.js";
+import { idtimestampToUnixMs } from "./resolve-delegated-verify-key.js";
+import { checkEndorsementWindow, verifySessionKeyEndorsement, } from "./session-key-endorsement.js";
+import { verifyReceiptOfflineWithKeys } from "./verify-grant-receipt-offline.js";
+/** COSE header label for key id (kid). */
+const COSE_KID = 4;
+/**
+ * Fold the endorsement verifier's fine-grained reasons into the ADR-0065 §4
+ * admission vocabulary. `signature_invalid` under a coordinate anchor means
+ * "a well-formed endorsement that does not chain to THIS root" — the
+ * `endorsement_root_mismatch` case; a malformed window is
+ * `endorsement_expired` (§4: "window, both directions, and malformed
+ * windows" — no instant is inside it); everything else structural is
+ * `endorsement_invalid`.
+ */
+export function endorsementAdmissionReason(reason) {
+    switch (reason) {
+        case "kid_mismatch":
+        case "signature_invalid":
+            return "endorsement_root_mismatch";
+        case "uv_required":
+            return "endorsement_uv_required";
+        case "window_invalid":
+            return "endorsement_expired";
+        default:
+            return "endorsement_invalid";
+    }
+}
+/**
+ * Read the endorsement bytes from a leaf's unprotected header.
+ * `missing` when there is no -65801 entry; `invalid` when the entry is not
+ * a byte string (present-but-unusable is never "absent").
+ */
+export function extractLeafEndorsement(statementCbor) {
+    const decoded = decodeCoseSign1(statementCbor);
+    if (!decoded)
+        return { kind: "invalid" };
+    const entry = coseUnprotectedToMap(decoded.unprotected).get(COSE_LABEL_SESSION_KEY_ENDORSEMENT);
+    if (entry === undefined)
+        return { kind: "missing" };
+    if (!(entry instanceof Uint8Array) || entry.length === 0) {
+        return { kind: "invalid" };
+    }
+    let kid = null;
+    try {
+        const protectedMap = decodeCborDeterministic(decoded.protectedBstr);
+        const raw = protectedMap instanceof Map
+            ? protectedMap.get(COSE_KID)
+            : protectedMap?.[COSE_KID];
+        if (raw instanceof Uint8Array)
+            kid = raw;
+    }
+    catch {
+        kid = null;
+    }
+    return { kind: "ok", endorsement: entry, kid };
+}
+function bytesEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let d = 0;
+    for (let i = 0; i < a.length; i++)
+        d |= a[i] ^ b[i];
+    return d === 0;
+}
+function readIdtimestampBe8(bytes) {
+    if (!bytes || bytes.length < 8) {
+        throw new Error("idtimestamp required (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);
+}
+/**
+ * Verify an endorsed leaf and its receipt from public artifacts only.
+ * Pure over bytes; no network (rules-of-the-road C1).
+ */
+export async function verifyEndorsedLeaf(input, opts) {
+    if (input.rootPublicKeyXY.length !== 64) {
+        return { ok: false, stage: "endorsement", reason: "root_invalid" };
+    }
+    const logPrefix = opts?.logPrefix ?? "verify-endorsed-leaf";
+    // 1. The endorsement, from the leaf itself.
+    const extracted = extractLeafEndorsement(input.statementCbor);
+    if (extracted.kind === "missing") {
+        return { ok: false, stage: "endorsement", reason: "endorsement_missing" };
+    }
+    if (extracted.kind === "invalid") {
+        return { ok: false, stage: "endorsement", reason: "endorsement_invalid" };
+    }
+    // 2. Under the root (kid pinned to root x by the coordinate anchor).
+    const endorsed = await verifySessionKeyEndorsement(extracted.endorsement, {
+        x: input.rootPublicKeyXY.subarray(0, 32),
+        y: input.rootPublicKeyXY.subarray(32, 64),
+        curve: "P-256",
+    }, {
+        requireUserVerification: opts?.requireUserVerification,
+        logFailures: opts?.logFailures,
+        logPrefix,
+    });
+    if (!endorsed.ok) {
+        return {
+            ok: false,
+            stage: "endorsement",
+            reason: endorsementAdmissionReason(endorsed.reason),
+        };
+    }
+    // 3. The leaf: kid == session x, signature under the session key. The
+    // shared verify branch rejects a -65800 entry on a plain-ES256 leaf.
+    const sessionX = endorsed.sessionPublicKeyXY.subarray(0, 32);
+    if (!extracted.kid || !bytesEqual(extracted.kid, sessionX)) {
+        return { ok: false, stage: "leaf", reason: "signer_mismatch" };
+    }
+    const leafOk = await verifyCoseSign1WithParsedKey(input.statementCbor, endorsed.sessionKey, { logFailures: opts?.logFailures, logPrefix: `${logPrefix}:leaf` });
+    if (!leafOk) {
+        return { ok: false, stage: "leaf", reason: "leaf_signature_invalid" };
+    }
+    // 4. The window, against the receipted idtimestamp (never wall-clock —
+    // a valid receipt verifies forever). Exact: no skew.
+    let idtimestamp;
+    try {
+        idtimestamp = readIdtimestampBe8(input.idtimestampBe8);
+    }
+    catch {
+        return { ok: false, stage: "window", reason: "idtimestamp_invalid" };
+    }
+    const leafIdtimestampMs = idtimestampToUnixMs(idtimestamp);
+    const window = checkEndorsementWindow(endorsed, leafIdtimestampMs);
+    if (!window.ok) {
+        return { ok: false, stage: "window", reason: window.reason };
+    }
+    // 5. Inclusion of the EXACT leaf bytes (the endorsement is inside them).
+    let trustKeys = input.trustKeys;
+    if (!trustKeys) {
+        try {
+            trustKeys = [
+                await importEs256PublicKeyFromGrantDataXy64(input.rootPublicKeyXY),
+            ];
+        }
+        catch {
+            return { ok: false, stage: "receipt", reason: "root_invalid" };
+        }
+    }
+    const receipt = await verifyReceiptOfflineWithKeys({
+        receiptCbor: input.receiptCbor,
+        payload: input.statementCbor,
+        idtimestampBe8: input.idtimestampBe8,
+        trustKeys,
+    });
+    if (!receipt.ok) {
+        return {
+            ok: false,
+            stage: "receipt",
+            reason: receipt.reason ?? "receipt_invalid",
+        };
+    }
+    return {
+        ok: true,
+        sessionPublicKeyXY: endorsed.sessionPublicKeyXY,
+        notBefore: endorsed.notBefore,
+        notAfter: endorsed.notAfter,
+        leafIdtimestampMs,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forestrie/receipt-verify",
-  "version": "0.12.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.6.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";
 /**
@@ -49,6 +79,7 @@ export type {
 } from "./verify-grant-receipt-offline.js";
 export {
   checkDelegationConstraints,
+  idtimestampToUnixMs,
   idtimestampToUnixSeconds,
   resolveDelegatedVerifyKey,
 } from "./resolve-delegated-verify-key.js";
@@ -59,22 +90,48 @@ export type {
 /** Import a raw 64-byte x||y P-256 public key as an ES256 verify key. */
 export { importEs256PublicKeyFromGrantDataXy64 } from "./decode-trust-root-cbor.js";
 /**
- * Passkey session-key endorsement (ADR-0064): build, assemble, and verify
- * the one-gesture artifact chaining a passkey log root to the plain-ES256
- * per-turn session key — the offline rung root → endorsement → leaves.
+ * Passkey session-key endorsement v2 (ADR-0064 as amended by ADR-0065):
+ * build, assemble, and verify the artifact chaining a passkey log root to the
+ * plain-ES256 per-turn session key for a validity window. The endorsement
+ * rides inside every endorsed leaf at unprotected label -65801
+ * (`COSE_LABEL_SESSION_KEY_ENDORSEMENT`, @forestrie/encoding).
  */
 export {
   assembleSessionKeyEndorsement,
   buildSessionKeyEndorsementTbs,
+  checkEndorsementWindow,
+  DEFAULT_ENDORSEMENT_WINDOW_MS,
+  NOT_AFTER_PAYLOAD_KEY,
+  NOT_BEFORE_PAYLOAD_KEY,
   SESSION_KEY_ENDORSEMENT_CONTENT_TYPE,
+  SESSION_KEY_ENDORSEMENT_V1_CONTENT_TYPE,
   SESSION_KEY_PAYLOAD_KEY,
   verifySessionKeyEndorsement,
 } from "./session-key-endorsement.js";
 export type {
+  EndorsementWindow,
+  EndorsementWindowCheck,
+  SessionKeyEndorsementFailureReason,
   SessionKeyEndorsementTbs,
   SessionKeyEndorsementVerifyResult,
   VerifySessionKeyEndorsementOptions,
 } from "./session-key-endorsement.js";
+/**
+ * The single offline rung for a passkey-rooted log (ADR-0065 §5): root →
+ * endorsement (inside the leaf) → session key → leaf → receipt + window.
+ */
+export {
+  endorsementAdmissionReason,
+  extractLeafEndorsement,
+  verifyEndorsedLeaf,
+} from "./verify-endorsed-leaf.js";
+export type {
+  EndorsementAdmissionReason,
+  VerifyEndorsedLeafInput,
+  VerifyEndorsedLeafOptions,
+  VerifyEndorsedLeafResult,
+  VerifyEndorsedLeafStage,
+} from "./verify-endorsed-leaf.js";
 export { decodeForestrieGrantCose } from "./decode-forestrie-grant-cose.js";
 export { decodeGrantPayload, decodeGrantResponse } from "./grant-codec.js";
 

package/src/resolve-delegated-verify-key.ts

@@ -71,10 +71,19 @@ const SNOWFLAKE_TIME_SHIFT = 24n;
 const SNOWFLAKE_EPOCH_SPAN_MS = (1n << 40n) - 1n;
 
 export function idtimestampToUnixSeconds(idtimestamp: bigint): number {
-  const ms =
+  return Math.floor(idtimestampToUnixMs(idtimestamp) / 1000);
+}
+
+/**
+ * Snowflake idtimestamp → Unix milliseconds: the time component an
+ * ADR-0065 §3 endorsement window is expressed in
+ * (`ms = (id >> TimeShift) + EpochMS(epoch)`).
+ */
+export function idtimestampToUnixMs(idtimestamp: bigint): number {
+  return Number(
     COMMITMENT_EPOCH * SNOWFLAKE_EPOCH_SPAN_MS +
-    (idtimestamp >> SNOWFLAKE_TIME_SHIFT);
-  return Number(ms / 1000n);
+      (idtimestamp >> SNOWFLAKE_TIME_SHIFT),
+  );
 }
 
 /**