@forestrie/receipt-verify 0.12.0 → 1.1.0

package/dist/session-key-endorsement.d.ts

@@ -1,37 +1,65 @@
 /**
- * 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 { type ParsedVerifyKey } from "@forestrie/encoding";
 /**
- * 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 declare 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 declare const SESSION_KEY_ENDORSEMENT_CONTENT_TYPE = "application/vnd.forestrie.session-key-endorsement+cbor";
+export declare 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 declare const SESSION_KEY_PAYLOAD_KEY = "sessionKey";
+/** Payload map key: window start, unix milliseconds, inclusive. */
+export declare const NOT_BEFORE_PAYLOAD_KEY = "notBefore";
+/** Payload map key: window end, unix milliseconds, inclusive. */
+export declare const NOT_AFTER_PAYLOAD_KEY = "notAfter";
+/** Default client window length: 7 days (ADR-0065 §3). */
+export declare const DEFAULT_ENDORSEMENT_WINDOW_MS: number;
+/** 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
@@ -40,15 +68,19 @@ export interface SessionKeyEndorsementTbs {
     sigStructureBytes: Uint8Array;
 }
 /**
- * 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 declare function buildSessionKeyEndorsementTbs(input: {
     rootPublicKeyX: Uint8Array;
     sessionPublicKeyXY: Uint8Array;
+    notBefore: number;
+    notAfter: number;
 }): SessionKeyEndorsementTbs;
 /**
  * Assemble the final endorsement COSE Sign1: the assertion rides in the
@@ -63,23 +95,26 @@ export declare function assembleSessionKeyEndorsement(input: {
     /** Low-s P1363 r‖s (64 bytes). */
     signature: Uint8Array;
 }): Uint8Array;
+/** 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 = {
+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;
-} | {
+} & EndorsementWindow) | {
     ok: false;
-    reason: "endorsement_malformed" | "wrong_alg" | "wrong_content_type" | "kid_invalid" | "kid_mismatch" | "payload_invalid" | "signature_invalid" | "session_key_import_failed";
+    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). */
@@ -88,16 +123,39 @@ export interface VerifySessionKeyEndorsementOptions {
     logPrefix?: string;
 }
 /**
- * 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 declare function verifySessionKeyEndorsement(endorsementCbor: Uint8Array, rootKeys: ParsedVerifyKey | ParsedVerifyKey[], opts?: VerifySessionKeyEndorsementOptions): Promise<SessionKeyEndorsementVerifyResult>;
+/** 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 declare function checkEndorsementWindow(window: EndorsementWindow, atMs: number, opts?: {
+    skewMs?: number;
+}): EndorsementWindowCheck;
 //# sourceMappingURL=session-key-endorsement.d.ts.map

package/dist/session-key-endorsement.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-key-endorsement.d.ts","sourceRoot":"","sources":["../src/session-key-endorsement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EASL,KAAK,eAAe,EACrB,MAAM,qBAAqB,CAAC;AAG7B;;;GAGG;AACH,eAAO,MAAM,oCAAoC,2DACS,CAAC;AAE3D,+EAA+E;AAC/E,eAAO,MAAM,uBAAuB,eAAe,CAAC;AAEpD,mEAAmE;AACnE,MAAM,WAAW,wBAAwB;IACvC,mEAAmE;IACnE,aAAa,EAAE,UAAU,CAAC;IAC1B,+DAA+D;IAC/D,WAAW,EAAE,UAAU,CAAC;IACxB;;;OAGG;IACH,iBAAiB,EAAE,UAAU,CAAC;CAC/B;AAED;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE;IACnD,cAAc,EAAE,UAAU,CAAC;IAC3B,kBAAkB,EAAE,UAAU,CAAC;CAChC,GAAG,wBAAwB,CAyB3B;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE;IACnD,GAAG,EAAE,wBAAwB,CAAC;IAC9B,iBAAiB,EAAE,UAAU,CAAC;IAC9B,cAAc,EAAE,UAAU,CAAC;IAC3B,kCAAkC;IAClC,SAAS,EAAE,UAAU,CAAC;CACvB,GAAG,UAAU,CAab;AAED,sEAAsE;AACtE,MAAM,MAAM,iCAAiC,GACzC;IACE,EAAE,EAAE,IAAI,CAAC;IACT,uDAAuD;IACvD,kBAAkB,EAAE,UAAU,CAAC;IAC/B,iEAAiE;IACjE,UAAU,EAAE,SAAS,CAAC;CACvB,GACD;IACE,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EACF,uBAAuB,GACvB,WAAW,GACX,oBAAoB,GACpB,aAAa,GACb,cAAc,GACd,iBAAiB,GACjB,mBAAmB,GACnB,2BAA2B,CAAC;CACjC,CAAC;AAEN,uDAAuD;AACvD,MAAM,WAAW,kCAAkC;IACjD;;;;OAIG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,6DAA6D;IAC7D,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,kCAAkC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAiDD;;;;;;;;;;;GAWG;AACH,wBAAsB,2BAA2B,CAC/C,eAAe,EAAE,UAAU,EAC3B,QAAQ,EAAE,eAAe,GAAG,eAAe,EAAE,EAC7C,IAAI,CAAC,EAAE,kCAAkC,GACxC,OAAO,CAAC,iCAAiC,CAAC,CA2D5C"}
+{"version":3,"file":"session-key-endorsement.d.ts","sourceRoot":"","sources":["../src/session-key-endorsement.ts"],"names":[],"mappings":"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"}

package/dist/session-key-endorsement.js

@@ -1,39 +1,77 @@
 /**
- * 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, decodeCborDeterministic, decodeCoseSign1, encodeCborDeterministic, encodeCoseSign1Raw, encodeSigStructure, verifyCoseSign1WithParsedKey, WEBAUTHN_ENVELOPE_LABEL, } from "@forestrie/encoding";
+import { COSE_ALG_ES256_WEBAUTHN, coseUnprotectedToMap, decodeCborDeterministic, decodeCoseSign1, encodeCborDeterministic, encodeCoseSign1Raw, encodeSigStructure, verifyCoseSign1WithParsedKey, WEBAUTHN_ENVELOPE_LABEL, } from "@forestrie/encoding";
 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_CONTENT_TYPE = "application/vnd.forestrie.session-key-endorsement+cbor";
+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;
+function isUnixMs(v) {
+    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) {
+    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) {
     if (input.rootPublicKeyX.length !== 32) {
@@ -42,13 +80,20 @@ 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([
         [1, COSE_ALG_ES256_WEBAUTHN],
         [3, SESSION_KEY_ENDORSEMENT_CONTENT_TYPE],
         [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([
         [SESSION_KEY_PAYLOAD_KEY, input.sessionPublicKeyXY],
+        [NOT_BEFORE_PAYLOAD_KEY, input.notBefore],
+        [NOT_AFTER_PAYLOAD_KEY, input.notAfter],
     ]));
     const sigStructureBytes = encodeSigStructure(protectedBstr, new Uint8Array(0), payloadBstr);
     return { protectedBstr, payloadBstr, sigStructureBytes };
@@ -89,16 +134,26 @@ function protectedHeaderEntries(protectedBstr) {
     }
     return null;
 }
-function decodePayloadSessionKeyXy(payloadBstr) {
+function toNumberIfInt(v) {
+    // 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) {
     let decoded;
     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;
     if (decoded instanceof Map) {
         entries = [...decoded.entries()];
@@ -107,28 +162,51 @@ function decodePayloadSessionKeyXy(payloadBstr) {
         entries = Object.entries(decoded);
     }
     else {
-        return null;
+        return { kind: "payload_invalid" };
     }
-    if (entries.length !== 1)
-        return null;
-    const [key, value] = entries[0];
-    if (key !== SESSION_KEY_PAYLOAD_KEY)
+    if (entries.length !== 3)
+        return { kind: "payload_invalid" };
+    const byKey = new Map(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) {
+    const envelope = coseUnprotectedToMap(unprotected).get(WEBAUTHN_ENVELOPE_LABEL);
+    if (!Array.isArray(envelope) || envelope.length !== 2)
         return null;
-    if (!(value instanceof Uint8Array) || value.length !== 64)
+    const authenticatorData = envelope[0];
+    if (!(authenticatorData instanceof Uint8Array) ||
+        authenticatorData.length < 37) {
         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, rootKeys, opts) {
     const anchors = Array.isArray(rootKeys) ? rootKeys : [rootKeys];
@@ -148,9 +226,17 @@ export async function verifySessionKeyEndorsement(endorsementCbor, rootKeys, opt
     if (!(header.kid instanceof Uint8Array) || header.kid.length !== 32) {
         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) {
         // When the anchor exposes raw coordinates, the signed kid must name it —
@@ -173,16 +259,41 @@ export async function verifySessionKeyEndorsement(endorsementCbor, rootKeys, opt
             continue;
         let sessionKey;
         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 {
         ok: false,
         reason: kidMismatch ? "kid_mismatch" : "signature_invalid",
     };
 }
+/**
+ * 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, atMs, opts) {
+    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/dist/verify-endorsed-leaf.d.ts

@@ -0,0 +1,102 @@
+/**
+ * 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 { type SessionKeyEndorsementFailureReason } from "./session-key-endorsement.js";
+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 declare function endorsementAdmissionReason(reason: SessionKeyEndorsementFailureReason): EndorsementAdmissionReason;
+/**
+ * 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 declare function extractLeafEndorsement(statementCbor: Uint8Array): {
+    kind: "ok";
+    endorsement: Uint8Array;
+    kid: Uint8Array | null;
+} | {
+    kind: "missing";
+} | {
+    kind: "invalid";
+};
+/**
+ * Verify an endorsed leaf and its receipt from public artifacts only.
+ * Pure over bytes; no network (rules-of-the-road C1).
+ */
+export declare function verifyEndorsedLeaf(input: VerifyEndorsedLeafInput, opts?: VerifyEndorsedLeafOptions): Promise<VerifyEndorsedLeafResult>;
+//# sourceMappingURL=verify-endorsed-leaf.d.ts.map

package/dist/verify-endorsed-leaf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-endorsed-leaf.d.ts","sourceRoot":"","sources":["../src/verify-endorsed-leaf.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAWH,OAAO,EAGL,KAAK,kCAAkC,EACxC,MAAM,8BAA8B,CAAC;AAMtC,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,eAAe,EAAE,UAAU,CAAC;IAC5B,oEAAoE;IACpE,aAAa,EAAE,UAAU,CAAC;IAC1B,kCAAkC;IAClC,WAAW,EAAE,UAAU,CAAC;IACxB,uDAAuD;IACvD,cAAc,EAAE,UAAU,CAAC;IAC3B;;;;;OAKG;IACH,SAAS,CAAC,EAAE,SAAS,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,6DAA6D;IAC7D,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,uBAAuB,GAC/B,aAAa,GACb,MAAM,GACN,QAAQ,GACR,SAAS,CAAC;AAEd,MAAM,MAAM,wBAAwB,GAChC;IACE,EAAE,EAAE,IAAI,CAAC;IACT,2DAA2D;IAC3D,kBAAkB,EAAE,UAAU,CAAC;IAC/B,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,2DAA2D;IAC3D,iBAAiB,EAAE,MAAM,CAAC;CAC3B,GACD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,uBAAuB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAElE,mEAAmE;AACnE,MAAM,MAAM,0BAA0B,GAClC,qBAAqB,GACrB,qBAAqB,GACrB,2BAA2B,GAC3B,yBAAyB,GACzB,qBAAqB,GACrB,2BAA2B,CAAC;AAEhC;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,kCAAkC,GACzC,0BAA0B,CAY5B;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,aAAa,EAAE,UAAU,GAEvB;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,WAAW,EAAE,UAAU,CAAC;IAAC,GAAG,EAAE,UAAU,GAAG,IAAI,CAAA;CAAE,GAC/D;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAsBtB;AAoBD;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,uBAAuB,EAC9B,IAAI,CAAC,EAAE,yBAAyB,GAC/B,OAAO,CAAC,wBAAwB,CAAC,CAkGnC"}