@forestrie/receipt-verify 0.12.0 → 1.0.0

package/src/session-key-endorsement.ts

@@ -1,27 +1,38 @@
 /**
- * Passkey session-key endorsement (devdocs ADR-0064, plan-2608-13 Q5).
+ * Passkey session-key endorsement, payload v2 (devdocs ADR-0064 as amended by
+ * ADR-0065 §3; plan-2608-14 1.2).
  *
  * A passkey log root signs ceremonies only; the per-turn user-envelope
- * signer is a separate session key, endorsed ONCE by the root via a COSE
- * Sign1 in the ADR-0063 WebAuthn envelope. This module owns both sides of
- * that artifact's byte-exact shape:
+ * signer is a separate session key, endorsed by the root via a COSE Sign1 in
+ * the ADR-0063 WebAuthn envelope. This module owns both sides of that
+ * artifact's byte-exact shape:
  *
  * - build/assemble: the client constructs the TBS, hashes its Sig_structure
  *   into the WebAuthn challenge, and attaches the assertion + signature;
  * - verify: given the passkey root as trust anchor, validate the artifact
- *   (typed, challenge-bound, fail-closed) and yield the session public key.
+ *   (typed, challenge-bound, fail-closed) and yield the session public key
+ *   and its validity window.
  *
- * The offline trust chain is then:
- *   grant (root = passkey x‖y) → endorsement → session key → plain-ES256
- *   per-turn leaves — zero per-leaf format change (ADR-0064 §4).
+ * The endorsement rides INSIDE every endorsed leaf (unprotected label
+ * `COSE_LABEL_SESSION_KEY_ENDORSEMENT`, -65801) and the chain
+ * root → endorsement → session key → leaf → receipt is walked by
+ * {@link verifyEndorsedLeaf} (the single offline rung, ADR-0065 §5) and by
+ * canopy SCRAPI admission (§4).
  *
- * Domain separation (ADR-0064 §2): the protected header carries the content
- * type below, and the payload is EXACTLY `{"sessionKey": bstr .size 64}`.
- * Anything else is a verification failure, never a fallback.
+ * Domain separation: the protected content type below names payload v2 and
+ * the payload is EXACTLY `{"sessionKey": bstr .size 64, "notBefore": uint,
+ * "notAfter": uint}` (unix milliseconds, the idtimestamp time domain).
+ * Anything else — including a v1 (window-less) artifact — is a verification
+ * failure, never a fallback (ADR-0065 §3: v1 is rejected, not grandfathered).
+ *
+ * The window itself is NOT checked here: the reference time differs per
+ * verifier (canopy's clock at admission; the receipted idtimestamp offline).
+ * Callers apply {@link checkEndorsementWindow} with the time they hold.
  */
 
 import {
   COSE_ALG_ES256_WEBAUTHN,
+  coseUnprotectedToMap,
   decodeCborDeterministic,
   decodeCoseSign1,
   encodeCborDeterministic,
@@ -34,20 +45,45 @@ import {
 import { importEs256PublicKeyFromGrantDataXy64 } from "./decode-trust-root-cbor.js";
 
 /**
- * Protected-header content type (label 3) naming the endorsement artifact.
- * Signed via Sig_structure, so the artifact's type is non-malleable.
+ * Protected-header content type (label 3) naming the v2 endorsement artifact.
+ * Signed via Sig_structure, so both the artifact's type AND its payload
+ * version are non-malleable.
  */
 export const SESSION_KEY_ENDORSEMENT_CONTENT_TYPE =
+  "application/vnd.forestrie.session-key-endorsement.v2+cbor";
+
+/**
+ * The retired ADR-0064 v1 content type (payload without a window). Exported
+ * only so verifiers and tests can name what is being REJECTED; no code path
+ * accepts it.
+ */
+export const SESSION_KEY_ENDORSEMENT_V1_CONTENT_TYPE =
   "application/vnd.forestrie.session-key-endorsement+cbor";
 
 /** Payload map key holding the endorsed session public key (x‖y, 64 bytes). */
 export const SESSION_KEY_PAYLOAD_KEY = "sessionKey";
+/** Payload map key: window start, unix milliseconds, inclusive. */
+export const NOT_BEFORE_PAYLOAD_KEY = "notBefore";
+/** Payload map key: window end, unix milliseconds, inclusive. */
+export const NOT_AFTER_PAYLOAD_KEY = "notAfter";
+
+/** Default client window length: 7 days (ADR-0065 §3). */
+export const DEFAULT_ENDORSEMENT_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+
+/** WebAuthn authenticatorData UV flag bit (WebAuthn L2 §6.1). */
+const AUTH_FLAG_UV = 0x04;
+
+/** Validity window of an endorsement, unix milliseconds, both ends inclusive. */
+export interface EndorsementWindow {
+  notBefore: number;
+  notAfter: number;
+}
 
 /** To-be-signed endorsement halves plus the challenge preimage. */
 export interface SessionKeyEndorsementTbs {
-  /** Protected header map bytes `{1: -65800, 3: cty, 4: root x}`. */
+  /** Protected header map bytes `{1: -65800, 3: cty(v2), 4: root x}`. */
   protectedBstr: Uint8Array;
-  /** Payload bytes: deterministic CBOR `{"sessionKey": x‖y}`. */
+  /** Payload bytes: deterministic CBOR `{sessionKey, notBefore, notAfter}`. */
   payloadBstr: Uint8Array;
   /**
    * `Sig_structure` over the halves. The WebAuthn challenge MUST be
@@ -56,16 +92,38 @@ export interface SessionKeyEndorsementTbs {
   sigStructureBytes: Uint8Array;
 }
 
+function isUnixMs(v: unknown): v is number {
+  return typeof v === "number" && Number.isSafeInteger(v) && v >= 0;
+}
+
+/**
+ * Structural window check shared by the builder and the verifier: both ends
+ * are unsigned safe integers and the window is non-empty (ADR-0065 §3
+ * "malformed windows are rejected": `notAfter ≤ notBefore`).
+ */
+function windowWellFormed(w: {
+  notBefore: unknown;
+  notAfter: unknown;
+}): w is EndorsementWindow {
+  return (
+    isUnixMs(w.notBefore) && isUnixMs(w.notAfter) && w.notAfter > w.notBefore
+  );
+}
+
 /**
- * Build the endorsement TBS. The caller hashes `sigStructureBytes` into the
- * `navigator.credentials.get` challenge, then assembles with the assertion.
+ * Build the v2 endorsement TBS. The caller hashes `sigStructureBytes` into
+ * the `navigator.credentials.get` challenge, then assembles with the assertion.
  *
  * @param input.rootPublicKeyX - Passkey root x coordinate (kid, 32 bytes)
  * @param input.sessionPublicKeyXY - Endorsed session public key x‖y (64 bytes)
+ * @param input.notBefore - Window start, unix ms inclusive
+ * @param input.notAfter - Window end, unix ms inclusive; must exceed notBefore
  */
 export function buildSessionKeyEndorsementTbs(input: {
   rootPublicKeyX: Uint8Array;
   sessionPublicKeyXY: Uint8Array;
+  notBefore: number;
+  notAfter: number;
 }): SessionKeyEndorsementTbs {
   if (input.rootPublicKeyX.length !== 32) {
     throw new Error("endorsement kid must be the 32-byte root x coordinate");
@@ -73,6 +131,11 @@ export function buildSessionKeyEndorsementTbs(input: {
   if (input.sessionPublicKeyXY.length !== 64) {
     throw new Error("endorsed session key must be 64 bytes (x||y)");
   }
+  if (!windowWellFormed(input)) {
+    throw new Error(
+      "endorsement window must be unsigned safe-integer unix ms with notAfter > notBefore",
+    );
+  }
   const protectedBstr = encodeCborDeterministic(
     new Map<number, unknown>([
       [1, COSE_ALG_ES256_WEBAUTHN],
@@ -80,9 +143,13 @@ export function buildSessionKeyEndorsementTbs(input: {
       [4, input.rootPublicKeyX],
     ]),
   );
+  // Deterministic CBOR sorts the keys (RFC 8949 §4.2.1); insertion order here
+  // is irrelevant to the bytes.
   const payloadBstr = encodeCborDeterministic(
     new Map<string, unknown>([
       [SESSION_KEY_PAYLOAD_KEY, input.sessionPublicKeyXY],
+      [NOT_BEFORE_PAYLOAD_KEY, input.notBefore],
+      [NOT_AFTER_PAYLOAD_KEY, input.notAfter],
     ]),
   );
   const sigStructureBytes = encodeSigStructure(
@@ -120,34 +187,37 @@ export function assembleSessionKeyEndorsement(input: {
   );
 }
 
+/** Verification failure reasons; the first check that broke. */
+export type SessionKeyEndorsementFailureReason =
+  | "endorsement_malformed"
+  | "wrong_alg"
+  | "wrong_content_type"
+  | "kid_invalid"
+  | "kid_mismatch"
+  | "payload_invalid"
+  | "window_invalid"
+  | "uv_required"
+  | "signature_invalid"
+  | "session_key_import_failed";
+
 /** Verification outcome; failures name the first check that broke. */
 export type SessionKeyEndorsementVerifyResult =
-  | {
+  | ({
       ok: true;
       /** Endorsed session public key, raw x‖y (64 bytes). */
       sessionPublicKeyXY: Uint8Array;
       /** The same key imported for ES256 verify of per-turn leaves. */
       sessionKey: CryptoKey;
-    }
-  | {
-      ok: false;
-      reason:
-        | "endorsement_malformed"
-        | "wrong_alg"
-        | "wrong_content_type"
-        | "kid_invalid"
-        | "kid_mismatch"
-        | "payload_invalid"
-        | "signature_invalid"
-        | "session_key_import_failed";
-    };
+    } & EndorsementWindow)
+  | { ok: false; reason: SessionKeyEndorsementFailureReason };
 
 /** Options for {@link verifySessionKeyEndorsement}. */
 export interface VerifySessionKeyEndorsementOptions {
   /**
-   * Require the assertion's UV flag. Onboarding UV is DEPLOYMENT config,
-   * not grant policy — the endorsement precedes the grant (ADR-0064 §3).
-   * User presence is always required regardless.
+   * Require the assertion's UV flag. At admission this is the grant's
+   * `GF_REQUIRES_USER_VERIFICATION` (ADR-0065 §4); at DO onboarding, where
+   * no grant exists yet, deployment config (ADR-0064 §3). User presence is
+   * always required regardless.
    */
   requireUserVerification?: boolean;
   /** Emit JSON warning lines on failure paths (no secrets). */
@@ -179,41 +249,89 @@ function protectedHeaderEntries(
   return null;
 }
 
-function decodePayloadSessionKeyXy(payloadBstr: Uint8Array): Uint8Array | null {
+type DecodedPayload =
+  | { kind: "ok"; sessionPublicKeyXY: Uint8Array; window: EndorsementWindow }
+  | { kind: "payload_invalid" }
+  | { kind: "window_invalid" };
+
+function toNumberIfInt(v: unknown): unknown {
+  // Deterministic decode may surface large ints as bigint; the window is
+  // unix ms (< 2^53) so a safe bigint is folded back to a number.
+  if (
+    typeof v === "bigint" &&
+    v >= 0n &&
+    v <= BigInt(Number.MAX_SAFE_INTEGER)
+  ) {
+    return Number(v);
+  }
+  return v;
+}
+
+function decodePayloadV2(payloadBstr: Uint8Array): DecodedPayload {
   let decoded: unknown;
   try {
     decoded = decodeCborDeterministic(payloadBstr);
   } catch {
-    return null;
+    return { kind: "payload_invalid" };
   }
-  // Exactly one entry, exactly the sessionKey label, exactly 64 bytes
-  // (ADR-0064 §2) — anything else is a failure, never a partial read.
+  // Exactly three entries, exactly the three labels, exactly these shapes
+  // (ADR-0065 §3) — anything else is a failure, never a partial read.
   let entries: [unknown, unknown][];
   if (decoded instanceof Map) {
     entries = [...decoded.entries()];
   } else if (typeof decoded === "object" && decoded !== null) {
     entries = Object.entries(decoded);
   } else {
+    return { kind: "payload_invalid" };
+  }
+  if (entries.length !== 3) return { kind: "payload_invalid" };
+  const byKey = new Map<unknown, unknown>(entries);
+  const sessionPublicKeyXY = byKey.get(SESSION_KEY_PAYLOAD_KEY);
+  if (
+    !(sessionPublicKeyXY instanceof Uint8Array) ||
+    sessionPublicKeyXY.length !== 64
+  ) {
+    return { kind: "payload_invalid" };
+  }
+  const notBefore = toNumberIfInt(byKey.get(NOT_BEFORE_PAYLOAD_KEY));
+  const notAfter = toNumberIfInt(byKey.get(NOT_AFTER_PAYLOAD_KEY));
+  if (!isUnixMs(notBefore) || !isUnixMs(notAfter)) {
+    return { kind: "payload_invalid" };
+  }
+  const window = { notBefore, notAfter };
+  if (!windowWellFormed(window)) return { kind: "window_invalid" };
+  return { kind: "ok", sessionPublicKeyXY, window };
+}
+
+/** Read the assertion's flags byte from the -65800 envelope, if well-shaped. */
+function envelopeFlags(unprotected: unknown): number | null {
+  const envelope = coseUnprotectedToMap(unprotected).get(
+    WEBAUTHN_ENVELOPE_LABEL,
+  );
+  if (!Array.isArray(envelope) || envelope.length !== 2) return null;
+  const authenticatorData = envelope[0];
+  if (
+    !(authenticatorData instanceof Uint8Array) ||
+    authenticatorData.length < 37
+  ) {
     return null;
   }
-  if (entries.length !== 1) return null;
-  const [key, value] = entries[0]!;
-  if (key !== SESSION_KEY_PAYLOAD_KEY) return null;
-  if (!(value instanceof Uint8Array) || value.length !== 64) return null;
-  return value;
+  return authenticatorData[32]!;
 }
 
 /**
- * Verify a session-key endorsement under the passkey root and yield the
- * endorsed session key. All the ADR-0063 envelope checks (challenge binding
- * to this artifact's `Sig_structure`, UP flag, ceremony type, low-s, both
- * fail-closed directions) run inside the shared `-65800` verify branch;
- * this function adds the ADR-0064 typing rules on top.
+ * Verify a v2 session-key endorsement under the passkey root and yield the
+ * endorsed session key plus its window. All the ADR-0063 envelope checks
+ * (challenge binding to this artifact's `Sig_structure`, UP flag, ceremony
+ * type, low-s, both fail-closed directions) run inside the shared `-65800`
+ * verify branch; this function adds the ADR-0064/0065 typing rules on top
+ * and reports a missing-UV rejection under its own reason so admission can
+ * name it (`endorsement_uv_required`, ADR-0065 §4).
  *
  * @param endorsementCbor - The endorsement COSE Sign1 bytes
  * @param rootKeys - Passkey root trust anchor(s), tried in order. Raw
  *   coordinate anchors additionally pin `kid == root x`.
- * @param opts - UV requirement (deployment config) and failure logging
+ * @param opts - UV requirement and failure logging
  */
 export async function verifySessionKeyEndorsement(
   endorsementCbor: Uint8Array,
@@ -239,8 +357,17 @@ export async function verifySessionKeyEndorsement(
     return { ok: false, reason: "kid_invalid" };
   }
 
-  const sessionPublicKeyXY = decodePayloadSessionKeyXy(decoded.payloadBstr);
-  if (!sessionPublicKeyXY) return { ok: false, reason: "payload_invalid" };
+  const payload = decodePayloadV2(decoded.payloadBstr);
+  if (payload.kind !== "ok") return { ok: false, reason: payload.kind };
+
+  if (opts?.requireUserVerification) {
+    const flags = envelopeFlags(decoded.unprotected);
+    // A malformed envelope is left to the shared branch to reject; only a
+    // well-shaped assertion that plainly lacks UV gets the distinct reason.
+    if (flags !== null && (flags & AUTH_FLAG_UV) === 0) {
+      return { ok: false, reason: "uv_required" };
+    }
+  }
 
   let kidMismatch = false;
   for (const anchor of anchors) {
@@ -266,12 +393,18 @@ export async function verifySessionKeyEndorsement(
 
     let sessionKey: CryptoKey;
     try {
-      sessionKey =
-        await importEs256PublicKeyFromGrantDataXy64(sessionPublicKeyXY);
+      sessionKey = await importEs256PublicKeyFromGrantDataXy64(
+        payload.sessionPublicKeyXY,
+      );
     } catch {
       return { ok: false, reason: "session_key_import_failed" };
     }
-    return { ok: true, sessionPublicKeyXY, sessionKey };
+    return {
+      ok: true,
+      sessionPublicKeyXY: payload.sessionPublicKeyXY,
+      sessionKey,
+      ...payload.window,
+    };
   }
 
   return {
@@ -279,3 +412,34 @@ export async function verifySessionKeyEndorsement(
     reason: kidMismatch ? "kid_mismatch" : "signature_invalid",
   };
 }
+
+/** Outcome of {@link checkEndorsementWindow}. */
+export type EndorsementWindowCheck =
+  | { ok: true }
+  | { ok: false; reason: "endorsement_not_yet_valid" | "endorsement_expired" };
+
+/**
+ * Is `atMs` inside the endorsement's window? `notBefore ≤ atMs ≤ notAfter`,
+ * both inclusive (ADR-0065 §3). `skewMs` (default 0) tolerates a `notBefore`
+ * slightly in the future of a wall-clock verifier; offline verifiers
+ * comparing against the receipted idtimestamp should leave it at 0 — that
+ * comparison is exact and authoritative.
+ *
+ * Deliberately a pure function of the two numbers so callers can (and must)
+ * run it on every request, structurally outside any verified-endorsement
+ * cache (ADR-0065 §4).
+ */
+export function checkEndorsementWindow(
+  window: EndorsementWindow,
+  atMs: number,
+  opts?: { skewMs?: number },
+): EndorsementWindowCheck {
+  const skew = opts?.skewMs ?? 0;
+  if (atMs + skew < window.notBefore) {
+    return { ok: false, reason: "endorsement_not_yet_valid" };
+  }
+  if (atMs > window.notAfter) {
+    return { ok: false, reason: "endorsement_expired" };
+  }
+  return { ok: true };
+}

package/src/verify-endorsed-leaf.ts

@@ -0,0 +1,287 @@
+/**
+ * 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,
+  type SessionKeyEndorsementFailureReason,
+} from "./session-key-endorsement.js";
+import { verifyReceiptOfflineWithKeys } from "./verify-grant-receipt-offline.js";
+
+/** COSE header label for key id (kid). */
+const COSE_KID = 4;
+
+export interface VerifyEndorsedLeafInput {
+  /**
+   * The log root as raw P-256 x‖y (64 bytes): the grant's `grantData`, the
+   * value univocity binds as `logRootKey`. The endorsement's trust anchor;
+   * its kid is pinned to this x.
+   */
+  rootPublicKeyXY: Uint8Array;
+  /** The EXACT registered leaf bytes (COSE Sign1 carrying -65801). */
+  statementCbor: Uint8Array;
+  /** The receipt over that leaf. */
+  receiptCbor: Uint8Array;
+  /** The receipted idtimestamp (8 bytes, big-endian). */
+  idtimestampBe8: Uint8Array;
+  /**
+   * Receipt trust anchors (the sealer or, for a delegated seal, the
+   * delegation-cert issuer — for a user log that is the root itself, which
+   * signs the sealing delegation with a passkey gesture). Defaults to the
+   * root. See `verifyReceiptOfflineWithKeys` for the trust model.
+   */
+  trustKeys?: CryptoKey[];
+}
+
+export interface VerifyEndorsedLeafOptions {
+  /**
+   * The grant's `GF_REQUIRES_USER_VERIFICATION` (ADR-0063 §4): when set the
+   * endorsement's assertion must carry UV. User presence is always required.
+   */
+  requireUserVerification?: boolean;
+  /** Emit JSON warning lines on failure paths (no secrets). */
+  logFailures?: boolean;
+  logPrefix?: string;
+}
+
+export type VerifyEndorsedLeafStage =
+  | "endorsement"
+  | "leaf"
+  | "window"
+  | "receipt";
+
+export type VerifyEndorsedLeafResult =
+  | {
+      ok: true;
+      /** The endorsed session public key, raw x‖y (64 bytes). */
+      sessionPublicKeyXY: Uint8Array;
+      /** The endorsement window, unix ms inclusive. */
+      notBefore: number;
+      notAfter: number;
+      /** The receipted idtimestamp's time component, unix ms. */
+      leafIdtimestampMs: number;
+    }
+  | { ok: false; stage: VerifyEndorsedLeafStage; reason: string };
+
+/** ADR-0065 §4 reason vocabulary, shared with canopy admission. */
+export type EndorsementAdmissionReason =
+  | "endorsement_missing"
+  | "endorsement_invalid"
+  | "endorsement_root_mismatch"
+  | "endorsement_uv_required"
+  | "endorsement_expired"
+  | "endorsement_not_yet_valid";
+
+/**
+ * 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: SessionKeyEndorsementFailureReason,
+): EndorsementAdmissionReason {
+  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: Uint8Array,
+):
+  | { kind: "ok"; endorsement: Uint8Array; kid: Uint8Array | null }
+  | { kind: "missing" }
+  | { kind: "invalid" } {
+  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: Uint8Array | null = null;
+  try {
+    const protectedMap = decodeCborDeterministic(decoded.protectedBstr);
+    const raw =
+      protectedMap instanceof Map
+        ? protectedMap.get(COSE_KID)
+        : (protectedMap as Record<number, unknown>)?.[COSE_KID];
+    if (raw instanceof Uint8Array) kid = raw;
+  } catch {
+    kid = null;
+  }
+  return { kind: "ok", endorsement: entry, kid };
+}
+
+function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  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: Uint8Array): bigint {
+  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: VerifyEndorsedLeafInput,
+  opts?: VerifyEndorsedLeafOptions,
+): Promise<VerifyEndorsedLeafResult> {
+  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: bigint;
+  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,
+  };
+}