@forestrie/receipt-verify 0.12.0 → 1.0.0

package/dist/index.d.ts

@@ -24,17 +24,25 @@ export { verifyReceiptOffline } from "./verify-grant-receipt-offline.js";
  */
 export { verifyGrantReceiptOfflineWithKeys, verifyReceiptOfflineWithKeys, } from "./verify-grant-receipt-offline.js";
 export type { VerifyGrantReceiptOfflineWithKeysInput, VerifyReceiptOfflineWithKeysInput, } from "./verify-grant-receipt-offline.js";
-export { checkDelegationConstraints, idtimestampToUnixSeconds, resolveDelegatedVerifyKey, } from "./resolve-delegated-verify-key.js";
+export { checkDelegationConstraints, idtimestampToUnixMs, idtimestampToUnixSeconds, resolveDelegatedVerifyKey, } from "./resolve-delegated-verify-key.js";
 export type { DelegatedResolution, DelegationConstraints, } from "./resolve-delegated-verify-key.js";
 /** 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, SESSION_KEY_ENDORSEMENT_CONTENT_TYPE, SESSION_KEY_PAYLOAD_KEY, verifySessionKeyEndorsement, } from "./session-key-endorsement.js";
-export type { SessionKeyEndorsementTbs, SessionKeyEndorsementVerifyResult, VerifySessionKeyEndorsementOptions, } from "./session-key-endorsement.js";
+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";
 /** Deterministic receipt construction (plan-2607-12 Phase 2, FOR-353). */

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,4BAA4B,CAAC;AACpC,oFAAoF;AACpF,YAAY,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACjD,YAAY,EAAE,8BAA8B,EAAE,MAAM,mCAAmC,CAAC;AACxF,YAAY,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AACnF,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EACV,wBAAwB,EACxB,uBAAuB,EACvB,eAAe,EACf,gBAAgB,GACjB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,wBAAwB,EACxB,mBAAmB,EACnB,sBAAsB,EACtB,mBAAmB,EACnB,eAAe,GAChB,MAAM,4BAA4B,CAAC;AACpC,+EAA+E;AAC/E,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EACV,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAC9B;;;GAGG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,0BAA0B,EAAE,MAAM,qCAAqC,CAAC;AACjF,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AACzE;;;;GAIG;AACH,OAAO,EACL,iCAAiC,EACjC,4BAA4B,GAC7B,MAAM,mCAAmC,CAAC;AAC3C,YAAY,EACV,sCAAsC,EACtC,iCAAiC,GAClC,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EACL,0BAA0B,EAC1B,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,mCAAmC,CAAC;AAC3C,YAAY,EACV,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,mCAAmC,CAAC;AAC3C,yEAAyE;AACzE,OAAO,EAAE,qCAAqC,EAAE,MAAM,6BAA6B,CAAC;AACpF;;;;GAIG;AACH,OAAO,EACL,6BAA6B,EAC7B,6BAA6B,EAC7B,oCAAoC,EACpC,uBAAuB,EACvB,2BAA2B,GAC5B,MAAM,8BAA8B,CAAC;AACtC,YAAY,EACV,wBAAwB,EACxB,iCAAiC,EACjC,kCAAkC,GACnC,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAE3E,0EAA0E;AAC1E,OAAO,EACL,cAAc,EACd,iDAAiD,GAClD,MAAM,2CAA2C,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAC;AAC7E,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,6EAA6E;AAC7E,OAAO,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAC;AACrE,oEAAoE;AACpE,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,YAAY,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,8EAA8E;AAC9E,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EACL,kBAAkB,EAClB,0BAA0B,EAC1B,4BAA4B,EAC5B,qBAAqB,EACrB,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,0BAA0B,GAChC,MAAM,uBAAuB,CAAC;AAC/B;;;;;GAKG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD;;;;;;GAMG;AACH,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,sBAAsB,EACtB,2CAA2C,EAC3C,KAAK,gBAAgB,GACtB,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -16,15 +16,22 @@ export { verifyReceiptOffline } from "./verify-grant-receipt-offline.js";
  * See the trust-ladder notes on verifyReceiptOfflineWithKeys.
  */
 export { verifyGrantReceiptOfflineWithKeys, verifyReceiptOfflineWithKeys, } from "./verify-grant-receipt-offline.js";
-export { checkDelegationConstraints, idtimestampToUnixSeconds, resolveDelegatedVerifyKey, } from "./resolve-delegated-verify-key.js";
+export { checkDelegationConstraints, idtimestampToUnixMs, idtimestampToUnixSeconds, resolveDelegatedVerifyKey, } from "./resolve-delegated-verify-key.js";
 /** 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, SESSION_KEY_ENDORSEMENT_CONTENT_TYPE, SESSION_KEY_PAYLOAD_KEY, verifySessionKeyEndorsement, } from "./session-key-endorsement.js";
+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";
+/**
+ * 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 { decodeForestrieGrantCose } from "./decode-forestrie-grant-cose.js";
 export { decodeGrantPayload, decodeGrantResponse } from "./grant-codec.js";
 /** Deterministic receipt construction (plan-2607-12 Phase 2, FOR-353). */

package/dist/resolve-delegated-verify-key.d.ts

@@ -35,6 +35,12 @@
  * earlier "does not yet enforce the window" gap.
  */
 export declare function idtimestampToUnixSeconds(idtimestamp: bigint): number;
+/**
+ * Snowflake idtimestamp → Unix milliseconds: the time component an
+ * ADR-0065 §3 endorsement window is expressed in
+ * (`ms = (id >> TimeShift) + EpochMS(epoch)`).
+ */
+export declare function idtimestampToUnixMs(idtimestamp: bigint): number;
 /**
  * Coverage + validity window a root-signed delegation cert imposes on its
  * delegated key. `mmrStart`/`mmrEnd` are inclusive MMR-index bounds;

package/dist/resolve-delegated-verify-key.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-delegated-verify-key.d.ts","sourceRoot":"","sources":["../src/resolve-delegated-verify-key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAqCH,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAKpE;AAED;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAC3B;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,GACrB;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,YAAY,EAAE,SAAS,CAAC;IACxB,WAAW,EAAE,qBAAqB,GAAG,IAAI,CAAC;CAC3C,GACD;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AAsGvB;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,qBAAqB,EAClC,YAAY,EAAE,MAAM,EACpB,eAAe,EAAE,MAAM,GACtB;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAS9C;AAED;;;;;GAKG;AACH,wBAAsB,yBAAyB,CAC7C,WAAW,EAAE,UAAU,EACvB,QAAQ,EAAE,SAAS,EAAE,GACpB,OAAO,CAAC,mBAAmB,CAAC,CAgC9B"}
+{"version":3,"file":"resolve-delegated-verify-key.d.ts","sourceRoot":"","sources":["../src/resolve-delegated-verify-key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAqCH,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAK/D;AAED;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAC3B;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,GACrB;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,YAAY,EAAE,SAAS,CAAC;IACxB,WAAW,EAAE,qBAAqB,GAAG,IAAI,CAAC;CAC3C,GACD;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AAsGvB;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,qBAAqB,EAClC,YAAY,EAAE,MAAM,EACpB,eAAe,EAAE,MAAM,GACtB;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAS9C;AAED;;;;;GAKG;AACH,wBAAsB,yBAAyB,CAC7C,WAAW,EAAE,UAAU,EACvB,QAAQ,EAAE,SAAS,EAAE,GACpB,OAAO,CAAC,mBAAmB,CAAC,CAgC9B"}

package/dist/resolve-delegated-verify-key.js

@@ -60,9 +60,16 @@ const COMMITMENT_EPOCH = 1n;
 const SNOWFLAKE_TIME_SHIFT = 24n;
 const SNOWFLAKE_EPOCH_SPAN_MS = (1n << 40n) - 1n;
 export function idtimestampToUnixSeconds(idtimestamp) {
-    const ms = COMMITMENT_EPOCH * SNOWFLAKE_EPOCH_SPAN_MS +
-        (idtimestamp >> SNOWFLAKE_TIME_SHIFT);
-    return Number(ms / 1000n);
+    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) {
+    return Number(COMMITMENT_EPOCH * SNOWFLAKE_EPOCH_SPAN_MS +
+        (idtimestamp >> SNOWFLAKE_TIME_SHIFT));
 }
 function extractDelegationCertBytes(unprotected) {
     const umap = coseUnprotectedToMap(unprotected);

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":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAUL,KAAK,eAAe,EACrB,MAAM,qBAAqB,CAAC;AAG7B;;;;GAIG;AACH,eAAO,MAAM,oCAAoC,8DACY,CAAC;AAE9D;;;;GAIG;AACH,eAAO,MAAM,uCAAuC,2DACM,CAAC;AAE3D,+EAA+E;AAC/E,eAAO,MAAM,uBAAuB,eAAe,CAAC;AACpD,mEAAmE;AACnE,eAAO,MAAM,sBAAsB,cAAc,CAAC;AAClD,iEAAiE;AACjE,eAAO,MAAM,qBAAqB,aAAa,CAAC;AAEhD,0DAA0D;AAC1D,eAAO,MAAM,6BAA6B,QAA0B,CAAC;AAKrE,iFAAiF;AACjF,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,mEAAmE;AACnE,MAAM,WAAW,wBAAwB;IACvC,uEAAuE;IACvE,aAAa,EAAE,UAAU,CAAC;IAC1B,6EAA6E;IAC7E,WAAW,EAAE,UAAU,CAAC;IACxB;;;OAGG;IACH,iBAAiB,EAAE,UAAU,CAAC;CAC/B;AAoBD;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE;IACnD,cAAc,EAAE,UAAU,CAAC;IAC3B,kBAAkB,EAAE,UAAU,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,wBAAwB,CAkC3B;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,gEAAgE;AAChE,MAAM,MAAM,kCAAkC,GAC1C,uBAAuB,GACvB,WAAW,GACX,oBAAoB,GACpB,aAAa,GACb,cAAc,GACd,iBAAiB,GACjB,gBAAgB,GAChB,aAAa,GACb,mBAAmB,GACnB,2BAA2B,CAAC;AAEhC,sEAAsE;AACtE,MAAM,MAAM,iCAAiC,GACzC,CAAC;IACC,EAAE,EAAE,IAAI,CAAC;IACT,uDAAuD;IACvD,kBAAkB,EAAE,UAAU,CAAC;IAC/B,iEAAiE;IACjE,UAAU,EAAE,SAAS,CAAC;CACvB,GAAG,iBAAiB,CAAC,GACtB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,kCAAkC,CAAA;CAAE,CAAC;AAE9D,uDAAuD;AACvD,MAAM,WAAW,kCAAkC;IACjD;;;;;OAKG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,6DAA6D;IAC7D,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,kCAAkC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA+FD;;;;;;;;;;;;;GAaG;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,CA0E5C;AAED,iDAAiD;AACjD,MAAM,MAAM,sBAAsB,GAC9B;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GACZ;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,2BAA2B,GAAG,qBAAqB,CAAA;CAAE,CAAC;AAE/E;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,iBAAiB,EACzB,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACzB,sBAAsB,CASxB"}

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 };
+}