unjwt 0.9.0 → 0.9.2

package/dist/_chunks/error.d.mts

@@ -13,7 +13,7 @@ import { UnsecureError, UnsecureErrorCode } from "./libs/unsecure.mjs";
  * {@link isJWTError} takes this type, so a misspelled code such as `"ERR_JWS_INVALD"` is a type error.
  * Use {@link JWTErrorCode} for a value that may hold a code outside this union.
  */
-export type KnownJWTErrorCode = "ERR_JWT_EXPIRED" | "ERR_JWT_NBF" | "ERR_JWT_CLAIM_INVALID" | "ERR_JWT_CLAIM_MISSING" | "ERR_JWS_INVALID" | "ERR_JWS_INVALID_SERIALIZATION" | "ERR_JWS_SIGNATURE_INVALID" | "ERR_JWS_ALG_NOT_ALLOWED" | "ERR_JWS_ALG_MISSING" | "ERR_JWS_SIGNER_ALG_INFERENCE" | "ERR_JWS_NO_MATCHING_SIGNER" | "ERR_JWS_HEADER_PARAMS_NOT_DISJOINT" | "ERR_JWS_B64_INCONSISTENT" | "ERR_JWE_INVALID" | "ERR_JWE_INVALID_SERIALIZATION" | "ERR_JWE_DECRYPTION_FAILED" | "ERR_JWE_ALG_NOT_ALLOWED" | "ERR_JWE_ALG_MISSING" | "ERR_JWE_ALG_FORBIDDEN_IN_MULTI" | "ERR_JWE_ENC_MISSING" | "ERR_JWE_RECIPIENT_ALG_INFERENCE" | "ERR_JWE_NO_MATCHING_RECIPIENT" | "ERR_JWE_HEADER_PARAMS_NOT_DISJOINT" | "ERR_JWK_INVALID" | "ERR_JWK_KEY_NOT_FOUND" | "ERR_JWK_UNSUPPORTED" | "ERR_DPOP_INVALID" | "ERR_DPOP_CLAIM_INVALID" | "ERR_DPOP_NONCE_INVALID" | "ERR_DPOP_REPLAY" | "ERR_SESSION_TOKEN_INVALID" | "ERR_SESSION_READ_FAILED" | "ERR_SESSION_READONLY_EVENT" | "ERR_SESSION_KEY_INVALID" | "ERR_SESSION_CONFIG_INVALID" | "ERR_INVALID_OPTION";
+export type KnownJWTErrorCode = "ERR_JWT_EXPIRED" | "ERR_JWT_NBF" | "ERR_JWT_CLAIM_INVALID" | "ERR_JWT_CLAIM_MISSING" | "ERR_JWS_INVALID" | "ERR_JWS_INVALID_SERIALIZATION" | "ERR_JWS_SIGNATURE_INVALID" | "ERR_JWS_ALG_NOT_ALLOWED" | "ERR_JWS_ALG_MISSING" | "ERR_JWS_SIGNER_ALG_INFERENCE" | "ERR_JWS_NO_MATCHING_SIGNER" | "ERR_JWS_HEADER_PARAMS_NOT_DISJOINT" | "ERR_JWS_B64_INCONSISTENT" | "ERR_JWE_INVALID" | "ERR_JWE_INVALID_SERIALIZATION" | "ERR_JWE_DECRYPTION_FAILED" | "ERR_JWE_ALG_NOT_ALLOWED" | "ERR_JWE_ALG_MISSING" | "ERR_JWE_ALG_FORBIDDEN_IN_MULTI" | "ERR_JWE_ENC_MISSING" | "ERR_JWE_RECIPIENT_ALG_INFERENCE" | "ERR_JWE_NO_MATCHING_RECIPIENT" | "ERR_JWE_HEADER_PARAMS_NOT_DISJOINT" | "ERR_JWK_INVALID" | "ERR_JWK_KEY_NOT_FOUND" | "ERR_JWK_UNSUPPORTED" | "ERR_DPOP_INVALID" | "ERR_DPOP_CLAIM_INVALID" | "ERR_DPOP_NONCE_INVALID" | "ERR_DPOP_REPLAY" | "ERR_SESSION_INVALID" | "ERR_SESSION_TOKEN_INVALID" | "ERR_SESSION_READ_FAILED" | "ERR_SESSION_READONLY_EVENT" | "ERR_SESSION_KEY_INVALID" | "ERR_SESSION_CONFIG_INVALID" | "ERR_INVALID_OPTION";
 /**
  * A {@link JWTError} `code`: any {@link KnownJWTErrorCode} or any other string.
  * A `JWTError` built outside unjwt can hold a code outside the union.

package/dist/session/index.d.mts

@@ -17,7 +17,16 @@ type SessionData<T extends SessionRecord = SessionClaims> = StrictOmit<T, "jti"
 type SessionSource = "cookie" | "header" | "token";
 /** Why `onUpdate` ran: an `update()` call, or `rolling` reissuing a session that was read. */
 type SessionUpdateTrigger = "update" | "rolling";
-/** What `update()` merges: a partial data object, or a function of the current data that returns one or `undefined`. */
+/** Why `onError` ran: `"read"` when the request's token could not be opened, else the {@link SessionUpdateTrigger} of the update that failed. */
+type SessionErrorTrigger = "read" | SessionUpdateTrigger;
+/** The roll `onRead` receives: whether `rolling` reissues the session after the hook, and a way to keep its token on this request. */
+interface SessionRoll {
+  /** `true` when `rolling` reissues this session after the hook. An `update()` in the hook is that reissue, and a `clear()` cancels it. */
+  readonly due: boolean;
+  /** Keeps `rolling` from reissuing the session after the hook on this request. The next request finds the roll due again. Does nothing when no roll is due, or once the hook has returned. */
+  readonly skip: () => void;
+}
+/** What `update()` merges: a partial data object, or a function of the current data that returns one, or changes that data in place and returns `undefined`. */
 type SessionUpdate<T extends SessionRecord = SessionClaims> = Partial<SessionData<T>> | ((oldData: SessionData<T>) => Partial<SessionData<T>> | undefined);
 /** The session of one request. Its getters read the current state of that request. */
 interface SessionManager<T extends SessionRecord = SessionClaims, ConfigMaxAge extends ExpiresIn | undefined = ExpiresIn | undefined> {
@@ -54,10 +63,10 @@ interface SessionManager<T extends SessionRecord = SessionClaims, ConfigMaxAge e
   /**
    * Merges `update` into the data and issues a token with a fresh `jti` and `iat`. `options.maxAge` overrides the config's `maxAge` for this token.
    * A `"cookie"` session writes the token to the response's cookie. A `"header"` or `"token"` session writes nothing: the token is on `token` alone, for you to send. Later requests read the data back through JSON.
-   * If issuing or the cookie write fails, the session is restored, `onError` runs and the call rejects. A throwing `onUpdate` rejects the call and keeps the new session.
+   * A failed update rejects and leaves the session as it was. When issuing or the cookie write fails, `onError` runs before it rejects. A throwing `onUpdate` cancels the update the same way, without `onError`.
    * @throws `ERR_SESSION_READONLY_EVENT` if a `"cookie"` session has no response, or the response was already sent.
-   * @throws `ERR_INVALID_OPTION` if the update is not a plain object or holds `__proto__`, `constructor` or `prototype`.
-   * @throws `ERR_SESSION_CONFIG_INVALID` if a `"cookie"` session's token needs more than 16 cookie chunks.
+   * @throws `ERR_INVALID_OPTION` if the update is not a plain object or holds `__proto__`, `constructor` or `prototype`, or `options.maxAge` is not a valid duration.
+   * @throws `ERR_SESSION_INVALID` if a `"cookie"` session's token needs more than 16 cookie chunks.
    */
   update: (update?: SessionUpdate<T>, options?: SessionIssueOptions) => Promise<SessionManager<T, ConfigMaxAge>>;
   /**
@@ -94,7 +103,9 @@ interface SessionBaseConfig<MaxAge extends ExpiresIn | undefined = ExpiresIn | u
   /** Session ID (`jti`) generator. @default crypto.randomUUID */
   generateId?: () => string;
 }
-/** Lifecycle hooks. `onRead`, `onExpire` and `onError` are mutually exclusive per token. `session` is the live manager, open to `update()` and `clear()`. `oldSession` is a snapshot. */
+/** The config a session holds once defined, as its hooks receive it: each property is read-only at every object level. Arrays, functions and `CryptoKey`, `Date` and typed array values keep their types. */
+type ReadonlyConfig<T> = { readonly [K in keyof T]: ReadonlyConfigValue<T[K]>; };
+/** Lifecycle hooks. A read ends in exactly one of `onRead`, `onExpire` and `onError`. In `onRead`, `session` is the live manager, open to `update()` and `clear()`. `onUpdate` and `onError` get copies, and every `oldSession` is a copy. */
 interface SessionHooks<TSession, TManager, TArgs extends Record<string, unknown>, TConfig> {
   /** Runs once per request, after a token is read and verified. A throw empties the session and rejects the read. */
   onRead?: (args: TArgs & {
@@ -102,11 +113,14 @@ interface SessionHooks<TSession, TManager, TArgs extends Record<string, unknown>
       id: string;
       token: string;
     };
+    /** Whether `rolling` reissues this session after the hook, and `skip()` to hold that reissue back on this request. */
+    roll: SessionRoll;
     config: TConfig;
   }) => void | Promise<void>;
-  /** Runs after `update()` or `rolling` issues a token and, on a cookie session, writes its cookie. A throw rejects the call and keeps the new session. */
+  /** Runs after `update()` or `rolling` issues a token, before it is written. A throw cancels the update: nothing is written, the session stays as it was, and the call rejects. */
   onUpdate?: (args: TArgs & {
-    session: TManager & {
+    /** The session just issued, its data deep-copied. */
+    session: TSession & {
       id: string;
       token: string;
     };
@@ -134,12 +148,28 @@ interface SessionHooks<TSession, TManager, TArgs extends Record<string, unknown>
     config: TConfig;
   }) => void | Promise<void>;
   /**
-   * Runs when a token fails to open for a reason other than expiry, and when an issue or cookie write fails. The session is empty after a read.
+   * Runs when the request's token fails to open for a reason other than expiry, and when an `update()` or a roll fails to issue or write its token. `trigger` names which.
+   * `session` and `oldSession` are copies, and `use(event)` returns the live session. The session is empty after a read.
    * - `ERR_SESSION_TOKEN_INVALID`: the token failed its checks, or `onKeyLookup` found no key for it. Its cookie is expired.
-   * - `ERR_SESSION_READ_FAILED`: `onKeyLookup` threw, its error as `cause`, or returned a key that cannot be used, an `ERR_JWK_INVALID` as `cause`. The cookie is kept, and `clear()` expires it.
+   * - `ERR_SESSION_READ_FAILED`: `onKeyLookup` threw, its error as `cause`, or returned a key that cannot be used, an `ERR_JWK_INVALID` as `cause`. The cookie is kept, and `clear()` on the session `use(event)` returns expires it.
    */
-  onError?: (args: TArgs & {
-    session: TManager;
+  onError?: (args: TArgs & ({
+    /** The session the failed update produced, its data deep-copied. `token` is set when `onUpdate` ran for it. */
+    session: TSession & {
+      id: string;
+    };
+    /** The session before the update, its data deep-copied. */
+    oldSession: TSession;
+    /** The operation that failed: an `update()` call, or the reissue by `rolling`. */
+    trigger: SessionUpdateTrigger;
+  } | {
+    /** An empty copy of the session, with the read's `error`. */
+    session: TSession;
+    /** `undefined`: a read has no session before it. */
+    oldSession: undefined;
+    /** The operation that failed: the read of the request's token. */
+    trigger: "read";
+  }) & {
     error: any;
     config: TConfig;
   }) => void | Promise<void>;
@@ -175,6 +205,7 @@ interface SessionDefinition<T extends SessionRecord = SessionClaims, MaxAge exte
    * Reads the request's session and returns its manager. Later calls on the same request share that state.
    * @throws `ERR_SESSION_CONFIG_INVALID` if the session has no token source, or a session of the other family uses its name on this request.
    * @throws `ERR_SESSION_KEY_INVALID` if a configured key fails to import.
+   * @throws `ERR_SESSION_INVALID` if the event is not one the driver can use, or a roll issues a token that needs more than 16 cookie chunks.
    */
   use: (event: TEvent) => Promise<SessionManager<T, MaxAge>>;
   /**
@@ -200,7 +231,7 @@ interface SessionRequestBase {
     readonly headers: Headers;
     readonly errHeaders?: Headers;
   };
-  /** Per-request state shared with the framework. Sessions are stored in its `sessions` member. Without it, state is keyed on `req`, else on the event. */
+  /** Per-request state shared with the framework. Sessions are stored in its `unjwt` member. Without it, state is keyed on `req`, else on the event. */
   readonly context?: Record<string, unknown>;
 }
 /** A request event, by its `Request` or by its `Headers` (a `Request` itself, a WebSocket upgrade request). `req` is read first. */
@@ -215,8 +246,9 @@ type SessionRequestEvent = SessionRequestBase & ({
 interface SessionHandedToken {
   token: string | undefined;
 }
-/** What the Web session driver accepts: a request event, or a token in hand. Any other shape throws `ERR_SESSION_CONFIG_INVALID`. */
+/** What the Web session driver accepts: a request event, or a token in hand. Any other shape throws `ERR_SESSION_INVALID`. */
 type WebSessionEvent = SessionRequestEvent | SessionHandedToken;
+type ReadonlyConfigValue<V> = V extends ((...args: never) => unknown) | CryptoKey | Date | ArrayBufferView ? V : V extends readonly unknown[] ? { [K in keyof V]: ReadonlyConfigValue<V[K]>; } : V extends object ? ReadonlyConfig<V> : V;
 /**
  * A symmetric key that signs and verifies, an HMAC `oct` JWK or a secret `CryptoKey`, a JWK Set of HMAC `oct` JWKs, or a pair:
  * `privateKey` signs and `publicKey` (a JWK, a JWK list, a JWK Set or a `CryptoKey`) verifies. A key without `alg` (a `CryptoKey`, an
@@ -231,6 +263,8 @@ type JWSSessionKey = CryptoKey | JWK_oct<JWK_HMAC> | JWKSet<JWK_oct<JWK_HMAC>[]>
   privateKey: JWSAsymmetricPrivateJWK | CryptoKey;
   publicKey: JWSAsymmetricPublicJWK | JWSAsymmetricPublicJWK[] | JWKSet | CryptoKey;
 };
+/** A copy of `value` whose plain objects and arrays are copied and frozen at every level. Functions and other objects stay as they are. */
+export declare function frozenCopy<T>(value: T): T;
 interface ExpirableCookieAttributes {
   expires?: Date;
   maxAge?: number;
@@ -261,6 +295,96 @@ interface SessionDriver<TEvent> {
     token: string | undefined;
   } | undefined;
 }
+/** The `Set-Cookie` attributes of a session cookie (RFC 6265, RFC 6265bis, and CHIPS: Cookies Having Independent Partitioned State). */
+interface CookieAttributes {
+  /** `Domain`. A `__Host-` name refuses it. */
+  domain?: string;
+  /** `Expires`. An issued token with an `exp` sets it to that time. */
+  expires?: Date;
+  /** `HttpOnly`: page scripts cannot read the cookie. */
+  httpOnly?: boolean;
+  /** `Max-Age` in seconds. An issued token with an `exp` replaces it with `expires`. */
+  maxAge?: number;
+  /** `Path`. A `__Host-` name requires `"/"`. */
+  path?: string;
+  /** `Priority`. */
+  priority?: "low" | "medium" | "high";
+  /** `SameSite`. `true` is `Strict`, and `"none"` requires `secure`. */
+  sameSite?: boolean | "lax" | "strict" | "none";
+  /** `Secure`. A `__Host-` or `__Secure-` name requires it. */
+  secure?: boolean;
+  /** `Partitioned` (CHIPS). Requires `secure`. */
+  partitioned?: boolean;
+}
+/** The attributes a session cookie gets unless its config sets them: `path` `"/"`, `secure`, `httpOnly` and `sameSite` `"lax"`. */
+export declare const DEFAULT_SESSION_COOKIE: Readonly<CookieAttributes>;
+/** The token sources of one session, and the attributes its cookie is written with. */
+interface SessionTransportOptions {
+  /** Session name: the cookie name, and the base of the default session header. */
+  name: string;
+  /** Request header to read the token from, before the cookie: a name, or `true` for `x-<name>-session`. Unset or `false` reads no header. */
+  sessionHeader?: boolean | string;
+  /** The cookie's attributes and the chunk size its token is split at (`4000` when unset), or `false` for no cookie. */
+  cookie: false | {
+    attrs: CookieAttributes;
+    chunkMaxLength?: number;
+  };
+}
+/** How one session reads its token from the request and writes it to the response. */
+interface SessionTransport {
+  /** Where the token is read from: the driver's token in hand, the session header, or the cookie. Only a cookie is written back. */
+  source: SessionSource;
+  /** The token in hand, else the session header's, else the cookie this response wrote, else the request's. Absent without a token source. */
+  read?: () => string | undefined;
+  /** The session header the request sent, by its lowercase name, when it holds neither a bare token nor `Bearer <token>`. The session decides how to report it. */
+  malformed?: {
+    header: string;
+  };
+  /**
+   * Writes the token to the cookie, split into chunks past `chunkMaxLength`, and returns `true`. With `expiresAt` (ms), the cookie gets that `expires` and no
+   * `maxAge`, which would take precedence (RFC 6265 §5.3). Once the response was sent, writes nothing and returns `false`.
+   * Present when the session reads its token from a cookie the event can write.
+   * @throws `ERR_SESSION_INVALID` if the token needs more than 16 cookie chunks.
+   */
+  write?: (token: string, options?: {
+    expiresAt?: number;
+  }) => boolean;
+  /**
+   * Checks that `write` can take the token, and writes nothing. Present when `write` is.
+   * @throws `ERR_SESSION_INVALID` if the token needs more than 16 cookie chunks.
+   */
+  assertFits?: (token: string) => void;
+  /**
+   * Expires the cookie and every chunk, and returns `true`. Once the response was sent, writes nothing and returns `false`.
+   * Present when the session reads its token from a cookie the event can write.
+   */
+  drop?: () => boolean;
+  /** The session reads its token from a cookie, but the event cannot write one (a request without a response). */
+  readonly: boolean;
+  /** Whether the response can still change. `false` once it was sent. */
+  writable: () => boolean;
+}
+/**
+ * Resolves the transport of one request, before any token is opened: a token the driver hands in, else the session header the request sends, else the cookie.
+ * A header that holds the very token of the request's cookie is the cookie. Any other header is read alone, the cookie left as it is.
+ * A token in hand or a header token is reissued onto the session only. Only a cookie session writes back.
+ */
+export declare function resolveSessionTransport<TEvent>(driver: SessionDriver<TEvent>, event: TEvent, options: SessionTransportOptions): SessionTransport;
+/** Throws `ERR_SESSION_CONFIG_INVALID` for a transport without a reader: the session has no token source to read or clear. */
+export declare function assertSessionTokenSource(transport: SessionTransport, options: {
+  prefix: string;
+}): asserts transport is SessionTransport & {
+  read: () => string | undefined;
+};
+/** Throws `ERR_SESSION_READONLY_EVENT` on an update when a cookie session cannot write its cookie, and on an update or clear once the response was sent. */
+export declare function assertSessionWritable(transport: SessionTransport, options: {
+  operation: "update" | "clear";
+  prefix: string;
+}): void;
+/** Refuses a `sessionHeader` that is neither a boolean nor a header name (RFC 7230 §3.2). */
+export declare function assertSessionHeader(header: unknown, options: {
+  prefix: string;
+}): void;
 /**
  * JWS verify options a session accepts. `algorithms` names the `alg` values a key without its own `alg` (a `CryptoKey`, an `oct` or RSA JWK
  * without `alg`) verifies, and with `onKeyLookup` set, may also name those only the keys it returns serve. The session sets `typ`,
@@ -292,33 +416,12 @@ interface JWSSessionConfig<MaxAge extends ExpiresIn | undefined = ExpiresIn | un
    */
   jws?: JWSSessionOptions;
 }
-/** The `Set-Cookie` attributes of a session cookie (RFC 6265, RFC 6265bis, and CHIPS: Cookies Having Independent Partitioned State). */
-interface CookieAttributes {
-  /** `Domain`. A `__Host-` name refuses it. */
-  domain?: string;
-  /** `Expires`. An issued token with an `exp` sets it to that time. */
-  expires?: Date;
-  /** `HttpOnly`: page scripts cannot read the cookie. */
-  httpOnly?: boolean;
-  /** `Max-Age` in seconds. An issued token with an `exp` replaces it with `expires`. */
-  maxAge?: number;
-  /** `Path`. A `__Host-` name requires `"/"`. */
-  path?: string;
-  /** `Priority`. */
-  priority?: "low" | "medium" | "high";
-  /** `SameSite`. `true` is `Strict`, and `"none"` requires `secure`. */
-  sameSite?: boolean | "lax" | "strict" | "none";
-  /** `Secure`. A `__Host-` or `__Secure-` name requires it. */
-  secure?: boolean;
-  /** `Partitioned` (CHIPS). Requires `secure`. */
-  partitioned?: boolean;
-}
 /** Session state for the current request, from the claims of its JWS token. */
 interface SessionJWS<T extends SessionRecord = SessionClaims, MaxAge extends ExpiresIn | undefined = ExpiresIn | undefined> extends SessionState<T, MaxAge> {}
-/** JWS session hooks. `onRead`, `onExpire` and `onError` are mutually exclusive per token. */
+/** JWS session hooks. A read ends in exactly one of `onRead`, `onExpire` and `onError`. */
 interface SessionHooksJWS<T extends SessionRecord = SessionClaims, MaxAge extends ExpiresIn | undefined = ExpiresIn | undefined, TEvent = WebSessionEvent> extends SessionHooks<SessionJWS<T, MaxAge>, SessionManager<T, MaxAge>, {
   event: TEvent;
-}, SessionConfigJWS<T, MaxAge, TEvent>> {
+}, ReadonlyConfig<SessionConfigJWS<T, MaxAge, TEvent>>> {
   /** Returns the key that verifies an incoming token. See {@link JWSSessionKeyLookup}. */
   onKeyLookup?: JWSSessionKeyLookup<T, MaxAge, TEvent>;
 }
@@ -335,7 +438,7 @@ interface SessionHooksJWS<T extends SessionRecord = SessionClaims, MaxAge extend
  */
 type JWSSessionKeyLookup<T extends SessionRecord = SessionClaims, MaxAge extends ExpiresIn | undefined = ExpiresIn | undefined, TEvent = WebSessionEvent> = (lookup: {
   header: JWSHeaderParameters;
-  config: SessionConfigJWS<T, MaxAge, TEvent>;
+  config: ReadonlyConfig<SessionConfigJWS<T, MaxAge, TEvent>>;
   event?: TEvent;
 }) => JWSVerifyJWK | CryptoKey | JWKSet | undefined | Promise<JWSVerifyJWK | CryptoKey | JWKSet | undefined>;
 /** Configuration of a JWS session, signed but not encrypted. */
@@ -346,14 +449,14 @@ interface SessionConfigJWS<T extends SessionRecord = SessionClaims, MaxAge exten
   hooks?: SessionHooksJWS<T, MaxAge, TEvent>;
 }
 /**
- * Defines a JWS session once: signed, not encrypted, so clients can read its data. `use`, `token`, `issue` and `open` serve every request.
+ * Defines a JWS session once: signed, not encrypted, so clients can read its data. `use`, `token`, `issue` and `open` serve every request. It keeps a frozen copy of `config`, so later changes to the object passed have no effect.
  * @throws `ERR_SESSION_CONFIG_INVALID` if `name`, `sessionHeader`, a `__Host-` or `__Secure-` cookie's attributes or `rolling` is invalid, or a key that names no algorithm (a `CryptoKey`, an `oct` JWK without `alg`, a pair when neither half names one) lacks a pinned `jws.signOptions.alg`, or `jws.verifyOptions.algorithms` is empty or lists one no key serves without `onKeyLookup`, or names none of those a `publicKey` entry without `alg` carries, or a token of a JWK Set `key` entry without `kid` meets more than `jws.verifyOptions.limits.keyCandidates` entries.
  * @throws `ERR_SESSION_KEY_INVALID` if `key` is missing, a string, a lone asymmetric key, not an HMAC `oct` JWK, a JWK Set of them, a secret `CryptoKey` or a key pair, an empty JWK Set or one holding a key that is not an `oct` JWK, a pair with a half that is not what it is named, serves no JWS algorithm, or cannot serve the pinned `alg` or, for a pair's half that names none, the one its other half names, or a pair whose single `publicKey` names another algorithm than the one it issues under, or whose `publicKey` list or JWK Set holds no key that serves it.
  * @throws `ERR_INVALID_OPTION` if `rolling` is neither `true` nor a duration.
  */
 export declare function defineJWSSession<T extends SessionRecord = SessionClaims, MaxAge extends ExpiresIn | undefined = ExpiresIn | undefined, TEvent extends WebSessionEvent = WebSessionEvent>(config: SessionConfigJWS<T, MaxAge, TEvent>): SessionDefinition<T, MaxAge, TEvent>;
 /**
- * Defines a JWS session over a framework driver of your own, passed as `{ driver }`.
+ * Defines a JWS session over a framework driver of your own, passed as `{ driver }`. It keeps a frozen copy of `config`, so later changes to the object passed have no effect.
  * @throws `ERR_SESSION_CONFIG_INVALID` if `name`, `sessionHeader`, a `__Host-` or `__Secure-` cookie's attributes or `rolling` is invalid, or a key that names no algorithm (a `CryptoKey`, an `oct` JWK without `alg`, a pair when neither half names one) lacks a pinned `jws.signOptions.alg`, or `jws.verifyOptions.algorithms` is empty or lists one no key serves without `onKeyLookup`, or names none of those a `publicKey` entry without `alg` carries, or a token of a JWK Set `key` entry without `kid` meets more than `jws.verifyOptions.limits.keyCandidates` entries.
  * @throws `ERR_SESSION_KEY_INVALID` if `key` is missing, a string, a lone asymmetric key, not an HMAC `oct` JWK, a JWK Set of them, a secret `CryptoKey` or a key pair, an empty JWK Set or one holding a key that is not an `oct` JWK, a pair with a half that is not what it is named, serves no JWS algorithm, or cannot serve the pinned `alg` or, for a pair's half that names none, the one its other half names, or a pair whose single `publicKey` names another algorithm than the one it issues under, or whose `publicKey` list or JWK Set holds no key that serves it.
  * @throws `ERR_INVALID_OPTION` if `rolling` is neither `true` nor a duration.
@@ -406,10 +509,10 @@ interface JWESessionConfig<MaxAge extends ExpiresIn | undefined = ExpiresIn | un
 }
 /** Session state for the current request, from the claims of its JWE token. */
 interface SessionJWE<T extends SessionRecord = SessionClaims, MaxAge extends ExpiresIn | undefined = ExpiresIn | undefined> extends SessionState<T, MaxAge> {}
-/** JWE session hooks. `onRead`, `onExpire` and `onError` are mutually exclusive per token. */
+/** JWE session hooks. A read ends in exactly one of `onRead`, `onExpire` and `onError`. */
 interface SessionHooksJWE<T extends SessionRecord = SessionClaims, MaxAge extends ExpiresIn | undefined = ExpiresIn | undefined, TEvent = WebSessionEvent> extends SessionHooks<SessionJWE<T, MaxAge>, SessionManager<T, MaxAge>, {
   event: TEvent;
-}, SessionConfigJWE<T, MaxAge, TEvent>> {
+}, ReadonlyConfig<SessionConfigJWE<T, MaxAge, TEvent>>> {
   /** Returns the key that decrypts an incoming token. See {@link JWESessionKeyLookup}. */
   onKeyLookup?: JWESessionKeyLookup<T, MaxAge, TEvent>;
 }
@@ -426,7 +529,7 @@ interface SessionHooksJWE<T extends SessionRecord = SessionClaims, MaxAge extend
  */
 type JWESessionKeyLookup<T extends SessionRecord = SessionClaims, MaxAge extends ExpiresIn | undefined = ExpiresIn | undefined, TEvent = WebSessionEvent> = (lookup: {
   header: JWEHeaderParameters;
-  config: SessionConfigJWE<T, MaxAge, TEvent>;
+  config: ReadonlyConfig<SessionConfigJWE<T, MaxAge, TEvent>>;
   event?: TEvent;
 }) => JWEDecryptJWK | CryptoKey | JWKSet | undefined | Promise<JWEDecryptJWK | CryptoKey | JWKSet | undefined>;
 /** Configuration of an encrypted JWE session. */
@@ -437,14 +540,14 @@ interface SessionConfigJWE<T extends SessionRecord = SessionClaims, MaxAge exten
   hooks?: SessionHooksJWE<T, MaxAge, TEvent>;
 }
 /**
- * Defines a JWE session once: encrypted, so clients cannot read its data. `use`, `token`, `issue` and `open` serve every request.
+ * Defines a JWE session once: encrypted, so clients cannot read its data. `use`, `token`, `issue` and `open` serve every request. It keeps a frozen copy of `config`, so later changes to the object passed have no effect.
  * @throws `ERR_SESSION_CONFIG_INVALID` if `name`, `sessionHeader`, a `__Host-` or `__Secure-` cookie's attributes or `rolling` is invalid, or a key that names no algorithm (a `CryptoKey`, an `oct` JWK without `alg`) lacks a pinned `jwe.encryptOptions.alg` and `enc`, or `jwe.decryptOptions.algorithms` is empty or lists one no key serves without `onKeyLookup`, or a token of a JWK Set `key` entry without `kid` meets more than `jwe.decryptOptions.limits.keyCandidates` entries.
  * @throws `ERR_SESSION_KEY_INVALID` if `key` is missing, a string, asymmetric, not an `oct` JWK, a JWK Set of them or a secret `CryptoKey`, an empty JWK Set or one holding a key that is not an `oct` JWK, serves no JWE algorithm, or cannot serve the pinned `alg` or `enc`.
  * @throws `ERR_INVALID_OPTION` if `rolling` is neither `true` nor a duration.
  */
 export declare function defineJWESession<T extends SessionRecord = SessionClaims, MaxAge extends ExpiresIn | undefined = ExpiresIn | undefined, TEvent extends WebSessionEvent = WebSessionEvent>(config: SessionConfigJWE<T, MaxAge, TEvent>): SessionDefinition<T, MaxAge, TEvent>;
 /**
- * Defines a JWE session over a framework driver of your own, passed as `{ driver }`.
+ * Defines a JWE session over a framework driver of your own, passed as `{ driver }`. It keeps a frozen copy of `config`, so later changes to the object passed have no effect.
  * @throws `ERR_SESSION_CONFIG_INVALID` if `name`, `sessionHeader`, a `__Host-` or `__Secure-` cookie's attributes or `rolling` is invalid, or a key that names no algorithm (a `CryptoKey`, an `oct` JWK without `alg`) lacks a pinned `jwe.encryptOptions.alg` and `enc`, or `jwe.decryptOptions.algorithms` is empty or lists one no key serves without `onKeyLookup`, or a token of a JWK Set `key` entry without `kid` meets more than `jwe.decryptOptions.limits.keyCandidates` entries.
  * @throws `ERR_SESSION_KEY_INVALID` if `key` is missing, a string, asymmetric, not an `oct` JWK, a JWK Set of them or a secret `CryptoKey`, an empty JWK Set or one holding a key that is not an `oct` JWK, serves no JWE algorithm, or cannot serve the pinned `alg` or `enc`.
  * @throws `ERR_INVALID_OPTION` if `rolling` is neither `true` nor a duration.
@@ -452,6 +555,75 @@ export declare function defineJWESession<T extends SessionRecord = SessionClaims
 export declare function defineJWESession<T extends SessionRecord = SessionClaims, MaxAge extends ExpiresIn | undefined = ExpiresIn | undefined, TEvent = WebSessionEvent>(config: SessionConfigJWE<T, MaxAge, TEvent>, options: {
   driver: SessionDriver<TEvent>;
 }): SessionDefinition<T, MaxAge, TEvent>;
-/** Returns `driver` typed as a `SessionDriver`. Pass it to `defineJWSSession` or `defineJWESession` as `{ driver }`. */
+/**
+ * Returns `driver` typed as a `SessionDriver`. Pass it to `defineJWSSession` or `defineJWESession` as `{ driver }`.
+ * The Web driver, `webSessionDriver()`, is the reference implementation of the contract.
+ */
 export declare function defineSessionDriver<TEvent>(driver: SessionDriver<TEvent>): SessionDriver<TEvent>;
-export { type CompositeKey, type ContentEncryptionAlgorithm, type CookieAttributes, type CookieJar, type DeriveJWKOptions, type DeriveJWKReturn, type DeriveKeyOptions, type DeriveKeyReturn, type Duration, type ECDHEphemeralKeyInput, type ExpiresIn, type GenerateJWKOptions, type GenerateJWKReturn, type GenerateKeyAlgorithm, type GenerateKeyOptions, type GenerateKeyReturn, type GeneratedJWKMap, type GeneratedKeyMap, type ImportedKey, type ImportedKeyMap, type ImportedPEMJWK, type JOSEConsumerOptions, type JOSELimits, type JOSEPayload, type JOSEPayloadMode, type JOSEPayloadTypeMap, type JWEAsymmetricPrivateJWK, type JWEAsymmetricPublicJWK, type JWEDecryptJWK, type JWEDecryptOptions, type JWEDecryptResult, type JWEEncryptJWK, type JWEEncryptOptions, type JWEFlattenedSerialization, type JWEGeneralRecipient, type JWEGeneralSerialization, type JWEHeaderParameters, type JWEKeyLookup, type JWEKeyManagementHeaderParameters, type JWELibraryHeaderName, type JWEMultiDecryptKey, type JWEMultiDecryptOptions, type JWEMultiDecryptResult, type JWEMultiEncryptOptions, type JWEMultiRecipient, type JWEProtectedHeader, type JWESessionKey, type JWESessionKeyLookup, type JWESessionOctJWK, type JWK, type JWKAlgorithm, type JWKCacheAdapter, type JWKLookupFunction, type JWKLookupFunctionHeader, type JWKMetadata, type JWKPEMAlgorithm, type JWKParameters, type JWKSet, type JWK_AES_Algorithm, type JWK_AES_CBC_HMAC, type JWK_AES_GCM, type JWK_AES_GCM_KW, type JWK_AES_KW, type JWK_Asymmetric, type JWK_Asymmetric_Algorithm, type JWK_EC, type JWK_ECDH_ES, type JWK_ECDSA, type JWK_EC_Private, type JWK_EC_Public, type JWK_HMAC, type JWK_OKP, type JWK_OKP_Private, type JWK_OKP_Public, type JWK_OKP_SIGN, type JWK_PBES2, type JWK_Pair, type JWK_Private, type JWK_Public, type JWK_RSA, type JWK_RSA_ENC, type JWK_RSA_PSS, type JWK_RSA_Private, type JWK_RSA_Public, type JWK_RSA_SIGN, type JWK_Symmetric, type JWK_Symmetric_Algorithm, type JWK_oct, type JWSAlgorithm, type JWSAsymmetricPrivateJWK, type JWSAsymmetricPublicJWK, type JWSFlattenedSerialization, type JWSGeneralSerialization, type JWSGeneralSignature, type JWSHashedAlgorithm, type JWSHeaderParameters, type JWSKeyLookup, type JWSMultiSignOptions, type JWSMultiSigner, type JWSMultiVerifyAllOptions, type JWSMultiVerifyOptions, type JWSMultiVerifyOutcome, type JWSMultiVerifyResult, type JWSProtectedHeader, type JWSSessionKey, type JWSSessionKeyLookup, type JWSSignJWK, type JWSSignOptions, type JWSVerifyJWK, type JWSVerifyOptions, type JWSVerifyResult, type JWT, type JWTClaimValidationOptions, type JWTClaims, type JWTConfirmation, type JWTTimeClaimOptions, type JoseHeaderParameters, type KeyManagementAlgorithm, type KeyWrapAlgorithmOf, type KeyWrappingAlgorithm, type MaxTokenAge, type NotBeforeIn, type OpenedSessionState, type PEMType, type PayloadOf, type SessionClaims, type SessionConfigJWE, type SessionConfigJWS, type SessionData, type SessionDecryptOptions, type SessionDefinition, type SessionDriver, type SessionEncryptOptions, type SessionHandedToken, type SessionHooksJWE, type SessionHooksJWS, type SessionIssueOptions, type SessionJWE, type SessionJWS, type SessionManager, type SessionRequestEvent, type SessionSignOptions, type SessionSource, type SessionUpdate, type SessionUpdateTrigger, type SessionVerifyOptions, type ToPublicJWKReturn, type UnwrapKeyOptions, type UnwrapKeyResult, type UnwrappingKeyFor, type WebSessionEvent, type WrapKeyOptions, type WrapKeyResult, type WrappingKeyFor, deriveJWKFromPassword, exportPEM, generateJWK, importPEM, thumbprint, toPublicJWK };
+/**
+ * The Web session driver: a request event by its `Request` or its `Headers`, or a token in hand.
+ * `prefix` (default `"[unjwt/session]"`) starts the message of every error a session over it throws, the driver's own included.
+ * Every driver it returns shares the state of a request with the others.
+ */
+export declare function webSessionDriver(options?: {
+  prefix?: string;
+}): SessionDriver<WebSessionEvent>;
+/**
+ * A cookie jar over a request's `Headers` and, when given, its response's: `read` parses the request's `Cookie` header,
+ * `write` sets a `Set-Cookie` line on `response.headers` through `serializeCookie`, replacing the line of the same cookie
+ * (name, domain, path, partition) instead of adding a second one, and `written` reads back what the response sets.
+ * Each write is copied to `errHeaders` too: h3 and Nitro send only these for a thrown handler.
+ * Without `response`, the jar only reads.
+ */
+export declare function webCookieJar(request: Headers, response?: {
+  headers: Headers;
+  errHeaders?: Headers;
+}): CookieJar<CookieAttributes>;
+/** The cookies of a `Cookie` header value, by name, values percent-decoded. The first of two cookies with one name wins. The record has no prototype. */
+export declare function parseCookie(header: string): Record<string, string | undefined>;
+/** One `Set-Cookie` line, the value percent-encoded and `path` `"/"` unless `attrs` sets one. Throws a `TypeError` for a name or attribute RFC 6265bis refuses. */
+export declare function serializeCookie(name: string, value: string, attrs?: CookieAttributes): string;
+/** The members of a session config that {@link assertSessionConfig} checks. */
+interface SessionConfigChecks {
+  /** Request header to read the token from: a name, or `true` for `x-<name>-session`. */
+  sessionHeader?: boolean | string;
+  /** Cookie attributes over the defaults, or `false` for no cookie. */
+  cookie?: false | (CookieAttributes & {
+    chunkMaxLength?: number;
+  });
+  /** Session lifetime. */
+  maxAge?: ExpiresIn;
+  /** Reissues a session read from its cookie: on every read with `true`, else once the token is that old. Requires `maxAge`, and is shorter than it. */
+  rolling?: true | ExpiresIn;
+}
+/**
+ * Checks what the config alone decides: its name, session header, cookie prefix over `defaultCookie`, and `rolling`.
+ * `defaultCookie` is {@link DEFAULT_SESSION_COOKIE} when unset.
+ * @throws `ERR_SESSION_CONFIG_INVALID` if `name` is not a cookie name or ends in a dot and digits, `sessionHeader` is not a header name,
+ * a `__Host-` or `__Secure-` cookie's attributes break its prefix rules, or `rolling` has no `maxAge` or is not shorter than it. The message starts with `prefix`.
+ * @throws `ERR_INVALID_OPTION` if `rolling` is neither `true` nor a duration.
+ */
+export declare function assertSessionConfig(config: SessionConfigChecks, options: {
+  name: string;
+  prefix: string;
+  defaultCookie?: CookieAttributes;
+}): void;
+/**
+ * The transport options of a session config: its session header, and its cookie attributes over `defaultCookie` with `chunkMaxLength` set apart.
+ * `defaultCookie` is {@link DEFAULT_SESSION_COOKIE} when unset. `cookie: false` is no cookie.
+ */
+export declare function sessionTransportOptions(config: Pick<SessionConfigChecks, "sessionHeader" | "cookie">, options: {
+  name: string;
+  defaultCookie?: CookieAttributes;
+}): SessionTransportOptions;
+/**
+ * Claims a session name on one request: one name is one cookie, so the first family to claim a name on a request keeps it.
+ * `state` is `driver.state(event)`. The same family may claim a name again on the same request.
+ * @throws `ERR_SESSION_CONFIG_INVALID` if another family already claimed `name` on this request. The message starts with `prefix`.
+ */
+export declare function claimSessionName(state: Record<string, unknown>, options: {
+  name: string;
+  family: string;
+  prefix: string;
+}): void;
+export { type CompositeKey, type ContentEncryptionAlgorithm, type CookieAttributes, type CookieJar, type DeriveJWKOptions, type DeriveJWKReturn, type DeriveKeyOptions, type DeriveKeyReturn, type Duration, type ECDHEphemeralKeyInput, type ExpiresIn, type GenerateJWKOptions, type GenerateJWKReturn, type GenerateKeyAlgorithm, type GenerateKeyOptions, type GenerateKeyReturn, type GeneratedJWKMap, type GeneratedKeyMap, type ImportedKey, type ImportedKeyMap, type ImportedPEMJWK, type JOSEConsumerOptions, type JOSELimits, type JOSEPayload, type JOSEPayloadMode, type JOSEPayloadTypeMap, type JWEAsymmetricPrivateJWK, type JWEAsymmetricPublicJWK, type JWEDecryptJWK, type JWEDecryptOptions, type JWEDecryptResult, type JWEEncryptJWK, type JWEEncryptOptions, type JWEFlattenedSerialization, type JWEGeneralRecipient, type JWEGeneralSerialization, type JWEHeaderParameters, type JWEKeyLookup, type JWEKeyManagementHeaderParameters, type JWELibraryHeaderName, type JWEMultiDecryptKey, type JWEMultiDecryptOptions, type JWEMultiDecryptResult, type JWEMultiEncryptOptions, type JWEMultiRecipient, type JWEProtectedHeader, type JWESessionKey, type JWESessionKeyLookup, type JWESessionOctJWK, type JWK, type JWKAlgorithm, type JWKCacheAdapter, type JWKLookupFunction, type JWKLookupFunctionHeader, type JWKMetadata, type JWKPEMAlgorithm, type JWKParameters, type JWKSet, type JWK_AES_Algorithm, type JWK_AES_CBC_HMAC, type JWK_AES_GCM, type JWK_AES_GCM_KW, type JWK_AES_KW, type JWK_Asymmetric, type JWK_Asymmetric_Algorithm, type JWK_EC, type JWK_ECDH_ES, type JWK_ECDSA, type JWK_EC_Private, type JWK_EC_Public, type JWK_HMAC, type JWK_OKP, type JWK_OKP_Private, type JWK_OKP_Public, type JWK_OKP_SIGN, type JWK_PBES2, type JWK_Pair, type JWK_Private, type JWK_Public, type JWK_RSA, type JWK_RSA_ENC, type JWK_RSA_PSS, type JWK_RSA_Private, type JWK_RSA_Public, type JWK_RSA_SIGN, type JWK_Symmetric, type JWK_Symmetric_Algorithm, type JWK_oct, type JWSAlgorithm, type JWSAsymmetricPrivateJWK, type JWSAsymmetricPublicJWK, type JWSFlattenedSerialization, type JWSGeneralSerialization, type JWSGeneralSignature, type JWSHashedAlgorithm, type JWSHeaderParameters, type JWSKeyLookup, type JWSMultiSignOptions, type JWSMultiSigner, type JWSMultiVerifyAllOptions, type JWSMultiVerifyOptions, type JWSMultiVerifyOutcome, type JWSMultiVerifyResult, type JWSProtectedHeader, type JWSSessionKey, type JWSSessionKeyLookup, type JWSSignJWK, type JWSSignOptions, type JWSVerifyJWK, type JWSVerifyOptions, type JWSVerifyResult, type JWT, type JWTClaimValidationOptions, type JWTClaims, type JWTConfirmation, type JWTTimeClaimOptions, type JoseHeaderParameters, type KeyManagementAlgorithm, type KeyWrapAlgorithmOf, type KeyWrappingAlgorithm, type MaxTokenAge, type NotBeforeIn, type OpenedSessionState, type PEMType, type PayloadOf, type ReadonlyConfig, type SessionClaims, type SessionConfigChecks, type SessionConfigJWE, type SessionConfigJWS, type SessionData, type SessionDecryptOptions, type SessionDefinition, type SessionDriver, type SessionEncryptOptions, type SessionErrorTrigger, type SessionHandedToken, type SessionHooksJWE, type SessionHooksJWS, type SessionIssueOptions, type SessionJWE, type SessionJWS, type SessionManager, type SessionRequestEvent, type SessionRoll, type SessionSignOptions, type SessionSource, type SessionTransport, type SessionTransportOptions, type SessionUpdate, type SessionUpdateTrigger, type SessionVerifyOptions, type ToPublicJWKReturn, type UnwrapKeyOptions, type UnwrapKeyResult, type UnwrappingKeyFor, type WebSessionEvent, type WrapKeyOptions, type WrapKeyResult, type WrappingKeyFor, deriveJWKFromPassword, exportPEM, generateJWK, importPEM, thumbprint, toPublicJWK };

package/dist/session/index.mjs

@@ -28,6 +28,9 @@ function invalidKeyError(message, cause) {
 function invalidConfigError(message, cause) {
 	return new JWTError(message, "ERR_SESSION_CONFIG_INVALID", cause);
 }
+function invalidSessionError(message) {
+	return new JWTError(message, "ERR_SESSION_INVALID");
+}
 function invalidTokenError(message, cause) {
 	return new JWTError(message, "ERR_SESSION_TOKEN_INVALID", cause);
 }
@@ -47,6 +50,9 @@ function expiredSessionError(options) {
 function readFailedError(cause, options) {
 	return new JWTError(`${options.prefix} Session could not be read: ${messageOf(cause)}`, "ERR_SESSION_READ_FAILED", cause);
 }
+function malformedHeaderError(header, options) {
+	return invalidTokenError(`${options.prefix} Invalid session token: the "${header}" header holds neither a token nor "Bearer <token>".`);
+}
 function rethrowAsInvalidToken(error, options) {
 	if (isJWTError(error, "ERR_JWT_EXPIRED") || isJWTError(error, "ERR_SESSION_READ_FAILED")) throw error;
 	throw invalidTokenError(`${options.prefix} Invalid session token: ${messageOf(error)}`, error);
@@ -65,7 +71,7 @@ function assertCookiePrefix(name, attrs, options) {
 	const host = lower.startsWith("__host-");
 	if (!host && !lower.startsWith("__secure-")) return;
 	const rule = host ? "\"__Host-\" cookie must be Secure, with Path=/ and no Domain" : "\"__Secure-\" cookie must be Secure";
-	if (attrs.secure === false || host && (attrs.domain !== void 0 || attrs.path !== void 0 && attrs.path !== "/")) throw invalidConfigError(`${options.prefix} Session ${quoteTokenValue(name)}: a ${rule}.`);
+	if (!attrs.secure || host && (attrs.domain !== void 0 || attrs.path !== void 0 && attrs.path !== "/")) throw invalidConfigError(`${options.prefix} Session ${quoteTokenValue(name)}: a ${rule}.`);
 }
 function assertRolling(config, options) {
 	const { rolling } = config;
@@ -161,7 +167,6 @@ function createSessionCodec(spec) {
 	return {
 		family: spec.family,
 		defaultName: spec.defaultName,
-		defaultCookie: spec.defaultCookie,
 		now,
 		keys: (config) => {
 			const { issueKey, issueAlg, key, algorithms } = spec.resolveKeys(config);
@@ -503,19 +508,12 @@ const RSA_SIGNATURES = [
 	"PS384",
 	"PS512"
 ];
-const JWS_DEFAULT_COOKIE = {
-	path: "/",
-	secure: true,
-	httpOnly: true,
-	sameSite: "lax"
-};
 function createJWSCodec(options) {
 	const { prefix, defaultName } = options;
 	return createSessionCodec({
 		family: "jws",
 		prefix,
 		defaultName,
-		defaultCookie: JWS_DEFAULT_COOKIE,
 		issueOptions: (config) => config.jws?.signOptions,
 		openOptions: (config) => config.jws?.verifyOptions,
 		resolveKeys: (config) => resolveSessionKeys$1(config.key, {
@@ -543,6 +541,12 @@ function createJWSCodec(options) {
 		}
 	});
 }
+const DEFAULT_SESSION_COOKIE = /* @__PURE__ */ Object.freeze({
+	path: "/",
+	secure: true,
+	httpOnly: true,
+	sameSite: "lax"
+});
 const kSessionPending = Symbol("unjwt_session_pending");
 function sessionInstant(source) {
 	const now = source.codec.now(source.config);
@@ -573,18 +577,46 @@ function blankSession() {
 		data: {}
 	});
 }
-function openSessionToken(keys, options) {
+async function openSessionToken(keys, options) {
 	return keys.open(options.token, options.args).then((opened) => typedOpened({
 		...opened,
 		source: "token"
 	}));
 }
+function snapshotSession(session) {
+	return {
+		...session,
+		data: safeJsonParse(JSON.stringify(session.data))
+	};
+}
+function frozenCopy(value) {
+	return frozenValue(value, /* @__PURE__ */ new Map());
+}
 function typedSession(state) {
 	return state;
 }
 function typedOpened(opened) {
 	return opened;
 }
+function frozenValue(value, seen) {
+	if (typeof value !== "object" || value === null) return value;
+	const known = seen.get(value);
+	if (known) return known;
+	if (Array.isArray(value)) {
+		const copy = [];
+		seen.set(value, copy);
+		for (const item of value) copy.push(frozenValue(item, seen));
+		return Object.freeze(copy);
+	}
+	if (!isPlainObject(value)) return value;
+	const copy = Object.create(Object.getPrototypeOf(value));
+	seen.set(value, copy);
+	for (const key of Object.keys(value)) Object.defineProperty(copy, key, {
+		value: frozenValue(value[key], seen),
+		enumerable: true
+	});
+	return Object.freeze(copy);
+}
 const CHUNK_MARKER = "__chunked__";
 const DEFAULT_CHUNK_MAX_LENGTH = 4e3;
 function readChunked(store, name) {
@@ -602,10 +634,9 @@ function readChunked(store, name) {
 	return parts.join("");
 }
 function writeChunked(store, name, value, options) {
-	const { attrs, chunkMaxLength, prefix } = options;
-	const max = chunkMaxLength && chunkMaxLength > 0 ? chunkMaxLength : DEFAULT_CHUNK_MAX_LENGTH;
-	const chunkCount = Math.ceil(value.length / max);
-	if (chunkCount > 16) throw invalidConfigError(`${prefix} Session token requires ${chunkCount} cookie chunks, exceeding the limit of 16.`);
+	const { attrs, chunkMaxLength } = options;
+	const max = chunkLength(chunkMaxLength);
+	const chunkCount = countChunks(value, options);
 	const previousCount = parseChunkCount(store.read(name));
 	const firstSurplus = chunkCount <= 1 ? 1 : chunkCount + 1;
 	for (let index = firstSurplus; index <= previousCount; index++) expire(store, chunkName(name, index), attrs);
@@ -616,6 +647,11 @@ function writeChunked(store, name, value, options) {
 	store.write(name, `${CHUNK_MARKER}${chunkCount}`, attrs);
 	for (let index = 1; index <= chunkCount; index++) store.write(chunkName(name, index), value.slice((index - 1) * max, index * max), attrs);
 }
+function countChunks(value, options) {
+	const chunkCount = Math.ceil(value.length / chunkLength(options.chunkMaxLength));
+	if (chunkCount > 16) throw invalidSessionError(`${options.prefix} Session token requires ${chunkCount} cookie chunks, exceeding the limit of 16.`);
+	return chunkCount;
+}
 function removeChunked(store, name, options) {
 	const count = parseChunkCount(store.read(name));
 	expire(store, name, options.attrs);
@@ -650,6 +686,9 @@ function parseChunkCount(main) {
 	if (count < 1 || count > 16) return 0;
 	return count;
 }
+function chunkLength(chunkMaxLength) {
+	return chunkMaxLength && chunkMaxLength > 0 ? chunkMaxLength : DEFAULT_CHUNK_MAX_LENGTH;
+}
 function expire(store, name, attrs) {
 	store.write(name, "", {
 		...attrs,
@@ -674,7 +713,7 @@ function decodeValue(value) {
 		return value;
 	}
 }
-function resolveTransport(driver, event, options) {
+function resolveSessionTransport(driver, event, options) {
 	const handed = driver.handed?.(event);
 	if (handed) return {
 		source: "token",
@@ -682,11 +721,11 @@ function resolveTransport(driver, event, options) {
 		readonly: false,
 		writable: () => true
 	};
-	const { config, name } = options;
+	const { name, cookie } = options;
 	const header = presentedHeader(driver, event, options);
-	if (config.cookie === false) return headerTransport(config, header);
+	if (cookie === false) return headerTransport(options, header);
 	const jar = driver.cookies(event);
-	if (header && (header.token === void 0 || header.token !== readChunked(jar, name))) return headerTransport(config, header);
+	if (header && (header.token === void 0 || header.token !== readChunked(jar, name))) return headerTransport(options, header);
 	const store = responseStore(jar);
 	const transport = {
 		source: "cookie",
@@ -695,22 +734,38 @@ function resolveTransport(driver, event, options) {
 		writable: () => driver.writable?.(event) ?? true
 	};
 	if (!store) return transport;
-	transport.write = (token, { attrs, chunkMaxLength }) => {
+	const { attrs, chunkMaxLength } = cookie;
+	transport.write = (token, { expiresAt } = {}) => {
+		if (!transport.writable()) return false;
+		const written = expiresAt === void 0 ? { ...attrs } : {
+			...attrs,
+			expires: new Date(expiresAt),
+			maxAge: void 0
+		};
 		writeChunked(store, name, token, {
-			attrs,
+			attrs: written,
 			chunkMaxLength,
 			prefix: driver.prefix
 		});
+		return true;
 	};
-	transport.drop = ({ attrs }) => {
+	transport.assertFits = (token) => {
+		countChunks(token, {
+			chunkMaxLength,
+			prefix: driver.prefix
+		});
+	};
+	transport.drop = () => {
+		if (!transport.writable()) return false;
 		removeChunked(store, name, { attrs });
+		return true;
 	};
 	return transport;
 }
-function assertTokenSource(transport, options) {
+function assertSessionTokenSource(transport, options) {
 	if (!transport.read) throw invalidConfigError(`${options.prefix} Session has no token source, enable "cookie" or "sessionHeader".`);
 }
-function assertWritable(transport, options) {
+function assertSessionWritable(transport, options) {
 	const { operation, prefix } = options;
 	if (operation === "update" && transport.readonly) throw readOnlyEventError(`${prefix} Cannot update session on read-only event.`);
 	if (!transport.writable()) throw readOnlyEventError(`${prefix} Cannot update/clear session: the response was already sent.`);
@@ -732,29 +787,29 @@ function headerToken(value) {
 	return words.length === 1 && first ? first : void 0;
 }
 function presentedHeader(driver, event, options) {
-	const { config, name } = options;
-	if (!readsHeader(config)) return void 0;
-	const header = sessionHeaderName(name, config.sessionHeader);
+	const { name, sessionHeader } = options;
+	if (!readsHeader(options)) return void 0;
+	const header = sessionHeaderName(name, sessionHeader);
 	const value = driver.header(event, header);
 	if (typeof value !== "string") return void 0;
 	const token = headerToken(value);
 	if (token) return { token };
 	return {
 		token: void 0,
-		malformed: invalidTokenError(`${driver.prefix} Invalid session token: the "${header}" header holds neither a token nor "Bearer <token>".`)
+		malformed: { header }
 	};
 }
-function headerTransport(config, header) {
+function headerTransport(options, header) {
 	return {
 		source: "header",
-		read: readsHeader(config) ? () => header?.token : void 0,
+		read: readsHeader(options) ? () => header?.token : void 0,
 		malformed: header?.malformed,
 		readonly: false,
 		writable: () => true
 	};
 }
-function readsHeader(config) {
-	return config.sessionHeader !== void 0 && config.sessionHeader !== false;
+function readsHeader(options) {
+	return options.sessionHeader !== void 0 && options.sessionHeader !== false;
 }
 function cookieToken(jar, name) {
 	const written = jar.written ? readChunked({ read: (key) => jar.written?.(key) }, name) : void 0;
@@ -772,15 +827,48 @@ function responseStore(jar) {
 const kSessionNames = Symbol("unjwt_session_names");
 const kHeldTokens = Symbol("unjwt_session_held_tokens");
 function assertSessionConfig(config, options) {
-	const { name, prefix } = options;
+	const { name, prefix, defaultCookie = DEFAULT_SESSION_COOKIE } = options;
 	assertSessionName(name, { prefix });
 	assertSessionHeader(config.sessionHeader, { prefix });
 	if (config.cookie !== false) assertCookiePrefix(name, {
-		...options.defaultCookie,
+		...defaultCookie,
 		...config.cookie
 	}, { prefix });
 	assertRolling(config, { prefix });
 }
+function sessionTransportOptions(config, options) {
+	const { name, defaultCookie = DEFAULT_SESSION_COOKIE } = options;
+	const { sessionHeader } = config;
+	if (config.cookie === false) return {
+		name,
+		sessionHeader,
+		cookie: false
+	};
+	const { chunkMaxLength, ...configured } = config.cookie || {};
+	return {
+		name,
+		sessionHeader,
+		cookie: {
+			attrs: {
+				...defaultCookie,
+				...configured
+			},
+			chunkMaxLength
+		}
+	};
+}
+function claimSessionName(state, options) {
+	const { name, family, prefix } = options;
+	const holder = state;
+	const registry = holder[kSessionNames] ||= /* @__PURE__ */ new Map();
+	const held = registry.get(name);
+	if (held === void 0) {
+		registry.set(name, family);
+		return;
+	}
+	if (held === family) return;
+	throw invalidConfigError(`${prefix} Session name "${name}" is already used by a ${held.toUpperCase()} session on this request.`);
+}
 function bindSession(event, options) {
 	const { config, name, driver, codec, keys, actions } = options;
 	const record = driver.state(event);
@@ -801,21 +889,18 @@ function bindSession(event, options) {
 		args: { event },
 		store: recordSlotStore(record, slot),
 		held: heldTokenSlot(record, slot),
-		transport: resolveTransport(driver, event, {
-			config,
-			name
-		})
+		transport: resolveSessionTransport(driver, event, sessionTransportOptions(config, { name }))
 	};
 }
 function sessionToken(binding) {
 	const { transport } = binding;
-	assertTokenSource(transport, { prefix: binding.driver.prefix });
+	assertSessionTokenSource(transport, { prefix: binding.driver.prefix });
 	const session = storedSession(binding.store);
 	return session ? session.token : transport.read();
 }
 function transportToken(binding) {
 	const { transport } = binding;
-	assertTokenSource(transport, { prefix: binding.driver.prefix });
+	assertSessionTokenSource(transport, { prefix: binding.driver.prefix });
 	const held = binding.held.get();
 	return held ? held.token : transport.read();
 }
@@ -827,38 +912,6 @@ function recordSlotStore(record, slot) {
 		}
 	};
 }
-function sessionCookie(binding, options = {}) {
-	const { chunkMaxLength, ...configured } = binding.config.cookie || {};
-	const attrs = {
-		...binding.codec.defaultCookie,
-		...configured
-	};
-	if (options.expiresAt !== void 0) {
-		attrs.expires = new Date(options.expiresAt);
-		attrs.maxAge = void 0;
-	}
-	return {
-		attrs,
-		chunkMaxLength
-	};
-}
-function dropSessionCookie(binding) {
-	const { transport } = binding;
-	if (!transport.drop || !transport.writable()) return;
-	transport.drop(sessionCookie(binding));
-}
-function claimSessionName(record, options) {
-	const { name, family, prefix } = options;
-	const holder = record;
-	const registry = holder[kSessionNames] ||= /* @__PURE__ */ new Map();
-	const held = registry.get(name);
-	if (held === void 0) {
-		registry.set(name, family);
-		return;
-	}
-	if (held === family) return;
-	throw invalidConfigError(`${prefix} Session name "${name}" is already used by a ${held.toUpperCase()} session on this request.`);
-}
 function heldTokenSlot(record, slot) {
 	const holder = record;
 	const held = holder[kHeldTokens] ||= /* @__PURE__ */ new Map();
@@ -873,12 +926,12 @@ async function loadSession(binding) {
 	const { config, codec, keys, store, args, transport } = binding;
 	await keys.assertKeys();
 	const open = keys.opener(args);
-	assertTokenSource(transport, { prefix: binding.driver.prefix });
+	assertSessionTokenSource(transport, { prefix: binding.driver.prefix });
 	const existing = storedSession(store);
 	if (existing) {
 		const session = existing[kSessionPending] ? await existing[kSessionPending] : existing;
-		if (session.token !== void 0 && session.expiresAt !== void 0 && session.expiresAt < codec.now(config)) {
-			dropSessionCookie(binding);
+		if (session.token !== void 0 && session.expiresAt !== void 0 && session.expiresAt <= codec.now(config)) {
+			transport.drop?.();
 			const error = expiredSessionError({
 				id: session.id,
 				createdAt: session.createdAt,
@@ -903,8 +956,12 @@ async function loadSession(binding) {
 	const session = emptySession(binding);
 	store.set(session);
 	if (transport.malformed) {
-		session.error = transport.malformed;
-		await fireError(binding, transport.malformed);
+		const error = malformedHeaderError(transport.malformed.header, { prefix: binding.driver.prefix });
+		session.error = error;
+		await fireError(binding, {
+			session,
+			error
+		});
 		return session;
 	}
 	const token = transport.read();
@@ -927,7 +984,7 @@ async function loadSession(binding) {
 		if (isJWTError(failure.error)) session.error = failure.error;
 		if (isJWTError(failure.error, "ERR_JWT_EXPIRED")) {
 			const { jti, iat, exp } = failure.error.cause;
-			dropSessionCookie(binding);
+			transport.drop?.();
 			await fireExpire(binding, {
 				session: {
 					id: jti,
@@ -938,44 +995,67 @@ async function loadSession(binding) {
 				error: failure.error
 			});
 		} else {
-			if (isJWTError(failure.error, "ERR_SESSION_TOKEN_INVALID")) dropSessionCookie(binding);
-			await fireError(binding, failure.error);
+			if (isJWTError(failure.error, "ERR_SESSION_TOKEN_INVALID")) transport.drop?.();
+			await fireError(binding, {
+				session,
+				error: failure.error
+			});
 		}
 		return session;
 	}
+	const due = isRollDue(binding, session);
+	let skipped = false;
+	const roll = {
+		due,
+		skip: () => {
+			skipped = true;
+		}
+	};
 	try {
-		await fireRead(binding, session);
+		await fireRead(binding, {
+			session,
+			roll
+		});
+		if (due && !skipped) await rollSession(binding, {
+			session,
+			token
+		});
 	} catch (error_) {
 		store.set(emptySession(binding));
 		throw error_;
 	}
-	await rollSession(binding, session);
 	return session;
 }
-async function fireRead(binding, session) {
-	if (session.id === void 0 || session.token === void 0) return;
+async function fireRead(binding, read) {
+	if (read.session.id === void 0 || read.session.token === void 0) return;
 	await binding.config.hooks?.onRead?.({
 		session: binding.actions.manager(binding),
 		...binding.args,
+		roll: read.roll,
 		config: binding.config
 	});
 }
-async function rollSession(binding, session) {
-	const { config, codec, transport, store } = binding;
+function isRollDue(binding, session) {
+	const { config, codec, transport } = binding;
 	const { rolling } = config;
-	if (rolling === void 0 || transport.source !== "cookie" || store.get() !== session) return;
-	if (session.token === void 0 || session.expiresAt === void 0) return;
-	if (rolling !== true) {
-		if (codec.now(config) - session.createdAt < computeDurationInSeconds(rolling) * 1e3) return;
-	}
-	if (transport.readonly || !transport.writable()) return;
+	if (rolling === void 0 || transport.source !== "cookie") return false;
+	if (session.expiresAt === void 0) return false;
+	const age = codec.now(config) - session.createdAt;
+	if (rolling !== true && age < computeDurationInSeconds(rolling) * 1e3) return false;
+	return !transport.readonly && transport.writable();
+}
+async function rollSession(binding, read) {
+	if (binding.store.get() !== read.session || read.session.token !== read.token) return;
+	if (!binding.transport.writable()) return;
 	await binding.actions.roll(binding);
 }
-async function fireError(binding, error) {
+async function fireError(binding, failure) {
 	await binding.config.hooks?.onError?.({
-		session: binding.actions.manager(binding),
+		session: snapshotSession(failure.session),
+		oldSession: void 0,
+		trigger: "read",
 		...binding.args,
-		error,
+		error: failure.error,
 		config: binding.config
 	});
 }
@@ -992,63 +1072,83 @@ async function fireExpire(binding, expired) {
 }
 async function issueSession(binding, update, options, trigger = "update") {
 	const { config, keys, driver, store, args, transport } = binding;
-	assertWritable(transport, {
+	assertSessionWritable(transport, {
 		operation: "update",
 		prefix: driver.prefix
 	});
 	const session = storedSession(store) || await loadSession(binding);
-	const oldSession = snapshotSession(session);
-	const resolved = typeof update === "function" ? update(session.data) : update;
-	if (resolved) Object.assign(session.data, sanitizeSessionUpdate(resolved, { prefix: driver.prefix }));
+	const restorePoint = snapshotSession(session);
+	const { changes, createdAt, id, expiresAt } = restoringOnThrow(session, restorePoint, () => {
+		const resolved = typeof update === "function" ? update(session.data) : update;
+		const instant = sessionInstant(binding);
+		return {
+			changes: resolved && sanitizeSessionUpdate(resolved, { prefix: driver.prefix }),
+			createdAt: instant,
+			id: mintSessionId(config),
+			expiresAt: resolveExpiresAt(instant, { maxAge: options?.maxAge ?? config.maxAge })
+		};
+	});
+	if (changes) Object.assign(session.data, changes);
 	for (const claim of RESERVED_CLAIMS) delete session.data[claim];
-	const maxAge = options?.maxAge ?? config.maxAge;
-	const createdAt = sessionInstant(binding);
-	const id = mintSessionId(config);
 	Object.assign(session, {
 		id,
 		createdAt,
-		expiresAt: resolveExpiresAt(createdAt, { maxAge })
+		expiresAt
 	});
-	let issued;
-	try {
-		await keys.assertKeys();
-		const token = await keys.issue(session);
-		transport.write?.(token, sessionCookie(binding, { expiresAt: session.expiresAt }));
-		binding.held.set(token);
-		issued = Object.assign(session, {
-			id,
-			token,
+	const reportFailure = async (error, failed) => {
+		const failedSession = {
+			...session,
+			token: failed.token,
 			error: void 0
-		});
-	} catch (error_) {
-		Object.assign(session, {
-			id: oldSession.id,
-			createdAt: oldSession.createdAt,
-			expiresAt: oldSession.expiresAt,
-			data: oldSession.data
-		});
-		session.token = oldSession.token;
+		};
+		restoreSession(session, restorePoint);
 		await config.hooks?.onError?.({
-			session: binding.actions.manager(binding),
+			session: snapshotSession(failedSession),
+			oldSession: snapshotSession(restorePoint),
+			trigger,
+			...args,
+			error,
+			config
+		});
+		throw error;
+	};
+	const token = await keys.assertKeys().then(() => keys.issue(session)).then((issuedToken) => {
+		transport.assertFits?.(issuedToken);
+		return issuedToken;
+	}).catch((error) => reportFailure(error, { token: void 0 }));
+	const issued = Object.assign(session, {
+		id,
+		token,
+		error: void 0
+	});
+	try {
+		await config.hooks?.onUpdate?.({
+			session: snapshotSession(issued),
+			oldSession: snapshotSession(restorePoint),
+			trigger,
 			...args,
-			error: error_,
 			config
 		});
+	} catch (error_) {
+		restoreSession(session, restorePoint);
 		throw error_;
 	}
-	await config.hooks?.onUpdate?.({
-		session: binding.actions.manager(binding),
-		oldSession,
-		trigger,
-		...args,
-		config
-	});
+	try {
+		assertSessionWritable(transport, {
+			operation: "update",
+			prefix: driver.prefix
+		});
+		transport.write?.(token, { expiresAt: issued.expiresAt });
+		binding.held.set(token);
+	} catch (error_) {
+		return reportFailure(error_, { token });
+	}
 	return issued;
 }
 async function dropSession(binding) {
 	const { config, driver, store, args, transport } = binding;
-	assertTokenSource(transport, { prefix: driver.prefix });
-	assertWritable(transport, {
+	assertSessionTokenSource(transport, { prefix: driver.prefix });
+	assertSessionWritable(transport, {
 		operation: "clear",
 		prefix: driver.prefix
 	});
@@ -1057,7 +1157,7 @@ async function dropSession(binding) {
 	const oldSession = session && (session.id !== void 0 || session.token !== void 0 || session.error !== void 0) ? snapshotSession(session) : void 0;
 	store.set(emptySession(binding));
 	binding.held.set(void 0);
-	transport.drop?.(sessionCookie(binding));
+	transport.drop?.();
 	await config.hooks?.onClear?.({
 		oldSession,
 		...args,
@@ -1108,19 +1208,31 @@ function sessionActions() {
 		}
 	};
 }
-function snapshotSession(session) {
-	return {
-		...session,
-		data: safeJsonParse(JSON.stringify(session.data))
-	};
+function restoringOnThrow(session, oldSession, run) {
+	try {
+		return run();
+	} catch (error) {
+		restoreSession(session, oldSession);
+		throw error;
+	}
+}
+function restoreSession(session, oldSession) {
+	Object.assign(session, {
+		id: oldSession.id,
+		createdAt: oldSession.createdAt,
+		expiresAt: oldSession.expiresAt,
+		data: oldSession.data,
+		token: oldSession.token,
+		error: oldSession.error
+	});
 }
-function defineSession(config, options) {
+function defineSession(configured, options) {
 	const { driver, codec } = options;
+	const config = frozenCopy(configured);
 	const name = config.name || codec.defaultName;
 	assertSessionConfig(config, {
 		name,
-		prefix: driver.prefix,
-		defaultCookie: codec.defaultCookie
+		prefix: driver.prefix
 	});
 	const keys = codec.keys(config);
 	const actions = sessionActions();
@@ -1163,15 +1275,15 @@ function defineSession(config, options) {
 }
 function webCookieJar(request, response) {
 	let cookies;
-	const jar = { read: (name) => (cookies ||= requestCookies(request))[name] };
+	const jar = { read: (name) => (cookies ||= parseCookie(request.get("cookie") ?? ""))[name] };
 	if (response) {
 		const { headers, errHeaders } = response;
 		jar.written = (name) => setCookieValues(headers.getSetCookie())[name];
 		jar.write = (name, value, attrs) => {
 			setCookie(headers, {
+				...attrs,
 				name,
-				value,
-				...attrs
+				value
 			});
 			if (errHeaders) mirrorSetCookie(name, {
 				from: headers,
@@ -1181,19 +1293,24 @@ function webCookieJar(request, response) {
 	}
 	return jar;
 }
-function requestCookies(request) {
-	const header = request.get("cookie");
-	return header ? parse(header) : Object.create(null);
+function parseCookie(header) {
+	return parse(header);
 }
-function setCookie(headers, cookie) {
-	const line = serialize({
+function serializeCookie(name, value, attrs) {
+	return serialize({
 		path: "/",
-		...cookie
+		...attrs,
+		name,
+		value
 	});
+}
+function setCookie(headers, cookie) {
+	const { name, value, ...attrs } = cookie;
+	const line = serializeCookie(name, value, attrs);
 	const key = cookieKey(cookie);
 	const kept = headers.getSetCookie().filter((existing) => {
 		const parsed = parseSetCookie(existing);
-		return parsed ? cookieKey(parsed) !== key : setCookieName(existing) !== cookie.name;
+		return parsed ? cookieKey(parsed) !== key : setCookieName(existing) !== name;
 	});
 	headers.delete("set-cookie");
 	for (const existing of kept) headers.append("set-cookie", existing);
@@ -1208,33 +1325,36 @@ function cookieKey(cookie) {
 		cookie.partitioned ? "1" : "0"
 	].join(";");
 }
-const PREFIX = "[unjwt/session]";
 const requestStates = /* @__PURE__ */ new WeakMap();
-const webSessionDriver = {
-	prefix: PREFIX,
-	state: (event) => {
-		if (isHanded(event)) return sessionsOf(event);
-		if (event.context) return contextState(event.context);
-		return sessionsOf(event.req ? webRequest(event.req) : event);
-	},
-	header: (event, name) => isHanded(event) ? void 0 : requestHeaders(event).get(name),
-	cookies: (event) => isHanded(event) ? { read: () => void 0 } : webCookieJar(requestHeaders(event), event.res),
-	handed: (event) => isHanded(event) ? { token: event.token } : void 0
-};
-function isHanded(event) {
+function webSessionDriver(options) {
+	const prefix = options?.prefix ?? "[unjwt/session]";
+	return {
+		prefix,
+		state: (event) => {
+			if (isHanded(event, prefix)) return sessionsOf(event);
+			if (event.context) return contextState(event.context);
+			return sessionsOf(event.req ? webRequest(event.req, prefix) : event);
+		},
+		header: (event, name) => isHanded(event, prefix) ? void 0 : requestHeaders(event, prefix).get(name),
+		cookies: (event) => isHanded(event, prefix) ? { read: () => void 0 } : webCookieJar(requestHeaders(event, prefix), event.res),
+		handed: (event) => isHanded(event, prefix) ? { token: event.token } : void 0
+	};
+}
+const defaultWebSessionDriver = /* @__PURE__ */ webSessionDriver();
+function isHanded(event, prefix) {
 	if ("req" in event || "headers" in event) return false;
 	if ("token" in event) return true;
-	throw invalidConfigError(`${PREFIX} use() got neither a request event nor a token.`);
+	throw invalidSessionError(`${prefix} use() got neither a request event nor a token.`);
 }
-function requestHeaders(event) {
-	if (event.req) return webRequest(event.req).headers;
+function requestHeaders(event, prefix) {
+	if (event.req) return webRequest(event.req, prefix).headers;
 	if (event.headers) return event.headers;
-	throw invalidConfigError(`${PREFIX} use() got a request event with neither "req" nor "headers".`);
+	throw invalidSessionError(`${prefix} use() got a request event with neither "req" nor "headers".`);
 }
-function webRequest(req) {
+function webRequest(req, prefix) {
 	const headers = req.headers;
 	if (typeof headers === "object" && headers !== null && "get" in headers) return req;
-	throw invalidConfigError(`${PREFIX} use() got an event whose "req" is not a web Request.`);
+	throw invalidSessionError(`${prefix} use() got an event whose "req" is not a web Request.`);
 }
 function contextState(context) {
 	const existing = context.unjwt;
@@ -1251,7 +1371,7 @@ function sessionsOf(request) {
 	return created;
 }
 function defineJWSSession(config, options) {
-	const driver = options?.driver ?? webSessionDriver;
+	const driver = options?.driver ?? defaultWebSessionDriver;
 	return defineSession(config, {
 		driver,
 		codec: createJWSCodec({
@@ -1357,19 +1477,12 @@ function encryptionBits(enc) {
 	const bits = Number(enc.slice(1, 4));
 	return enc.includes("CBC") ? bits * 2 : bits;
 }
-const JWE_DEFAULT_COOKIE = {
-	path: "/",
-	secure: true,
-	httpOnly: true,
-	sameSite: "lax"
-};
 function createJWECodec(options) {
 	const { prefix, defaultName } = options;
 	return createSessionCodec({
 		family: "jwe",
 		prefix,
 		defaultName,
-		defaultCookie: JWE_DEFAULT_COOKIE,
 		issueOptions: (config) => config.jwe?.encryptOptions,
 		openOptions: (config) => config.jwe?.decryptOptions,
 		resolveKeys: (config) => resolveSessionKeys(config.key, {
@@ -1400,7 +1513,7 @@ function sessionMaxIterations(config) {
 	return typeof alg === "string" && alg.startsWith("PBES2") ? config.jwe?.encryptOptions?.p2c ?? 6e5 : void 0;
 }
 function defineJWESession(config, options) {
-	const driver = options?.driver ?? webSessionDriver;
+	const driver = options?.driver ?? defaultWebSessionDriver;
 	return defineSession(config, {
 		driver,
 		codec: createJWECodec({
@@ -1412,4 +1525,4 @@ function defineJWESession(config, options) {
 function defineSessionDriver(driver) {
 	return driver;
 }
-export { defineJWESession, defineJWSSession, defineSessionDriver, deriveJWKFromPassword, exportPEM, generateJWK, importPEM, thumbprint, toPublicJWK };
+export { DEFAULT_SESSION_COOKIE, assertSessionConfig, assertSessionHeader, assertSessionTokenSource, assertSessionWritable, claimSessionName, defineJWESession, defineJWSSession, defineSessionDriver, deriveJWKFromPassword, exportPEM, frozenCopy, generateJWK, importPEM, parseCookie, resolveSessionTransport, serializeCookie, sessionTransportOptions, thumbprint, toPublicJWK, webCookieJar, webSessionDriver };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unjwt",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "A collection of JWT utilities based on the Web Crypto API.",
   "keywords": [
     "auth",
@@ -121,6 +121,7 @@
     "build": "obuild",
     "dev": "pnpm --dir playgrounds/h3 dev",
     "docs": "pnpm --filter unjwt-docs dev",
+    "docs:automd": "automd --dir docs",
     "dev:nuxt": "pnpm --dir playgrounds/nuxt-4 dev",
     "dev:nitro": "pnpm --dir playgrounds/nitro dev",
     "dev:prepare": "obuild --stub && pnpm --dir playgrounds/nuxt-4 prepare && pnpm simple-git-hooks",