unjwt 0.8.5 → 0.9.1

package/dist/session/index.d.mts

@@ -1,44 +1,590 @@
-import { CookieJar, JWESessionConfig, JWESessionHooks, JWSSessionConfig, JWSSessionHooks, OpenedSessionState, SessionClaims, SessionData, SessionDecryptOptions, SessionDefinition, SessionDriver, SessionEncryptOptions, SessionHandedToken, SessionIssueOptions, SessionManager, SessionRecord, SessionRequestEvent, SessionSignOptions, SessionState, SessionUpdate, SessionUpdateTrigger, SessionVerifyOptions, WebSessionEvent } from "../_chunks/codec-jwe.mjs";
-import { CookieAttributes } from "../_chunks/cookie-attributes.mjs";
-import { CompositeKey, ContentEncryptionAlgorithm, DeriveJWKOptions, DeriveJWKReturn, DeriveKeyOptions, DeriveKeyReturn, Duration, ECDHEphemeralKeyInput, ExpiresIn, GenerateJWKOptions, GenerateJWKReturn, GenerateKeyAlgorithm, GenerateKeyOptions, GenerateKeyReturn, GeneratedJWKMap, GeneratedKeyMap, ImportedKey, ImportedKeyMap, ImportedPEMJWK, JOSEConsumerOptions, JOSELimits, JOSEPayload, JOSEPayloadMode, JOSEPayloadTypeMap, JWEAsymmetricPrivateJWK, JWEAsymmetricPublicJWK, JWEDecryptJWK, JWEDecryptOptions, JWEDecryptResult, JWEEncryptJWK, JWEEncryptOptions, JWEFlattenedSerialization, JWEGeneralRecipient, JWEGeneralSerialization, JWEHeaderParameters, JWEKeyLookup, JWEKeyManagementHeaderParameters, JWELibraryHeaderName, JWEMultiDecryptKey, JWEMultiDecryptOptions, JWEMultiDecryptResult, JWEMultiEncryptOptions, JWEMultiRecipient, JWEProtectedHeader, JWK, JWKAlgorithm, JWKCacheAdapter, JWKLookupFunction, JWKLookupFunctionHeader, JWKMetadata, JWKPEMAlgorithm, JWKParameters, JWKSet, JWK_AES_Algorithm, JWK_AES_CBC_HMAC, JWK_AES_GCM, JWK_AES_GCM_KW, JWK_AES_KW, JWK_Asymmetric, JWK_Asymmetric_Algorithm, JWK_EC, JWK_ECDH_ES, JWK_ECDSA, JWK_EC_Private, JWK_EC_Public, JWK_HMAC, JWK_OKP, JWK_OKP_Private, JWK_OKP_Public, JWK_OKP_SIGN, JWK_PBES2, JWK_Pair, JWK_Private, JWK_Public, JWK_RSA, JWK_RSA_ENC, JWK_RSA_PSS, JWK_RSA_Private, JWK_RSA_Public, JWK_RSA_SIGN, JWK_Symmetric, JWK_Symmetric_Algorithm, JWK_oct, JWSAlgorithm, JWSAsymmetricPrivateJWK, JWSAsymmetricPublicJWK, JWSFlattenedSerialization, JWSGeneralSerialization, JWSGeneralSignature, JWSHashedAlgorithm, JWSHeaderParameters, JWSKeyLookup, JWSMultiSignOptions, JWSMultiSigner, JWSMultiVerifyAllOptions, JWSMultiVerifyOptions, JWSMultiVerifyOutcome, JWSMultiVerifyResult, JWSProtectedHeader, JWSSignJWK, JWSSignOptions, JWSVerifyJWK, JWSVerifyOptions, JWSVerifyResult, JWT, JWTClaimValidationOptions, JWTClaims, JWTConfirmation, JWTTimeClaimOptions, JoseHeaderParameters, KeyManagementAlgorithm, KeyWrapAlgorithmOf, KeyWrappingAlgorithm, MaxTokenAge, NotBeforeIn, PEMType, PayloadOf, ToPublicJWKReturn, UnwrapKeyOptions, UnwrapKeyResult, UnwrappingKeyFor, WrapKeyOptions, WrapKeyResult, WrappingKeyFor } from "../_chunks/index.mjs";
-import { deriveJWKFromPassword, exportPEM, generateJWK, importPEM, toPublicJWK } from "../_chunks/index2.mjs";
+import { JWTError } from "../_chunks/error.mjs";
+import { CompositeKey, ContentEncryptionAlgorithm, DeriveJWKOptions, DeriveJWKReturn, DeriveKeyOptions, DeriveKeyReturn, Duration, ECDHEphemeralKeyInput, ExpiresIn, GenerateJWKOptions, GenerateJWKReturn, GenerateKeyAlgorithm, GenerateKeyOptions, GenerateKeyReturn, GeneratedJWKMap, GeneratedKeyMap, ImportedKey, ImportedKeyMap, ImportedPEMJWK, JOSEConsumerOptions, JOSELimits, JOSEPayload, JOSEPayloadMode, JOSEPayloadTypeMap, JWEAsymmetricPrivateJWK, JWEAsymmetricPublicJWK, JWEDecryptJWK, JWEDecryptOptions, JWEDecryptResult, JWEEncryptJWK, JWEEncryptOptions, JWEFlattenedSerialization, JWEGeneralRecipient, JWEGeneralSerialization, JWEHeaderParameters, JWEKeyLookup, JWEKeyManagementHeaderParameters, JWELibraryHeaderName, JWEMultiDecryptKey, JWEMultiDecryptOptions, JWEMultiDecryptResult, JWEMultiEncryptOptions, JWEMultiRecipient, JWEProtectedHeader, JWK, JWKAlgorithm, JWKCacheAdapter, JWKLookupFunction, JWKLookupFunctionHeader, JWKMetadata, JWKPEMAlgorithm, JWKParameters, JWKSet, JWK_AES_Algorithm, JWK_AES_CBC_HMAC, JWK_AES_GCM, JWK_AES_GCM_KW, JWK_AES_KW, JWK_Asymmetric, JWK_Asymmetric_Algorithm, JWK_EC, JWK_ECDH_ES, JWK_ECDSA, JWK_EC_Private, JWK_EC_Public, JWK_HMAC, JWK_OKP, JWK_OKP_Private, JWK_OKP_Public, JWK_OKP_SIGN, JWK_PBES2, JWK_Pair, JWK_Private, JWK_Public, JWK_RSA, JWK_RSA_ENC, JWK_RSA_PSS, JWK_RSA_Private, JWK_RSA_Public, JWK_RSA_SIGN, JWK_Symmetric, JWK_Symmetric_Algorithm, JWK_oct, JWSAlgorithm, JWSAsymmetricPrivateJWK, JWSAsymmetricPublicJWK, JWSFlattenedSerialization, JWSGeneralSerialization, JWSGeneralSignature, JWSHashedAlgorithm, JWSHeaderParameters, JWSKeyLookup, JWSMultiSignOptions, JWSMultiSigner, JWSMultiVerifyAllOptions, JWSMultiVerifyOptions, JWSMultiVerifyOutcome, JWSMultiVerifyResult, JWSProtectedHeader, JWSSignJWK, JWSSignOptions, JWSVerifyJWK, JWSVerifyOptions, JWSVerifyResult, JWT, JWTClaimValidationOptions, JWTClaims, JWTConfirmation, JWTTimeClaimOptions, JoseHeaderParameters, KeyManagementAlgorithm, KeyWrapAlgorithmOf, KeyWrappingAlgorithm, MaxTokenAge, NotBeforeIn, PEMType, PayloadOf, StrictOmit, ToPublicJWKReturn, UnwrapKeyOptions, UnwrapKeyResult, UnwrappingKeyFor, WrapKeyOptions, WrapKeyResult, WrappingKeyFor } from "../_chunks/index.mjs";
 import { thumbprint } from "../_chunks/index3.mjs";
-/** Session state for the current request, mirroring the claims of its JWS token. */
+import { deriveJWKFromPassword, exportPEM, generateJWK, importPEM, toPublicJWK } from "../_chunks/index4.mjs";
+/** The shape session data must match. Its `any` values let an `interface` without an index signature match it. */
+type SessionRecord = Record<string, any>;
+/** The default session data: JWT claims, with `jti` and `iat` always set. */
+interface SessionClaims extends Required<Pick<JWTClaims, "jti" | "iat">>, StrictOmit<JWTClaims, "jti" | "iat"> {}
+/** Session data without `jti`, `iat`, `exp` and `nbf`, which the session sets on every issue. */
+type SessionData<T extends SessionRecord = SessionClaims> = StrictOmit<T, "jti" | "iat" | "exp" | "nbf">;
+/**
+ * Where the session's token comes from on this request, decided before it is opened:
+ * - `"cookie"`: the session cookie, also when the session header holds the very token of that cookie.
+ * - `"header"`: the session header, when it holds any other token or the session has no cookie.
+ * - `"token"`: a token in hand (`{ token }`), or a token passed to `open()`.
+ */
+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`. */
+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> {
+  /** Session ID (`jti`), `undefined` until a token is read or issued. */
+  readonly id: string | undefined;
+  /** Issue time in ms, from `iat`. A session without a token holds the time it was created. */
+  readonly createdAt: number;
+  /** Expiry in ms: `exp`, or `iat + maxAge` when sooner. Always a number when the session has a `maxAge`. */
+  readonly expiresAt: ConfigMaxAge extends ExpiresIn ? number : number | undefined;
+  /** Session data, without `jti`, `iat`, `exp` and `nbf`. */
+  readonly data: SessionData<T>;
+  /**
+   * The session's token: the one behind its current state, read and opened on this request or issued by `update()`. `undefined` when there is none,
+   * when the read failed, and after `clear()`. The token the request carries, whatever its read made of it, is the definition's `token(event)`.
+   * On a `"cookie"` session, a token `update()` issues is also written to the cookie. On a `"header"` or `"token"` session it is here alone, and reaches the client only if you send it.
+   */
+  readonly token: string | undefined;
+  /**
+   * Where the token of this request comes from, which decides what `update()` and `clear()` reach. It holds for the whole request.
+   * - `"cookie"`: `update()` writes the new token to the cookie, and `clear()` expires it.
+   * - `"header"` or `"token"`: `update()` re-mints onto `token` and writes nothing, and `clear()` empties the session for this request alone. The client keeps the token it sent, valid until it expires.
+   */
+  readonly source: SessionSource;
+  /**
+   * The error the read of this request ended with, the same object its hook received. `undefined` when the request carries no token, when the read
+   * succeeded, and after `update()` or `clear()`. Later `use()` calls on the same request return it too.
+   * - `ERR_JWT_EXPIRED`: the token is expired, the error `onExpire` received.
+   * - `ERR_SESSION_TOKEN_INVALID`: the token failed its checks, the error `onError` received.
+   * - `ERR_SESSION_READ_FAILED`: the key lookup threw or returned a key that cannot be used, the error `onError` received.
+   *
+   * A request without a token is the definition's `token(event)` returning `undefined`. A read that succeeded sets `id`.
+   */
+  readonly error: JWTError | undefined;
+  /**
+   * 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.
+   * @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.
+   */
+  update: (update?: SessionUpdate<T>, options?: SessionIssueOptions) => Promise<SessionManager<T, ConfigMaxAge>>;
+  /**
+   * Empties the session for the rest of the request and runs `onClear`.
+   * A `"cookie"` session with a response expires its cookie. A `"header"` or `"token"` session writes nothing: the client keeps the token it sent, valid until it expires.
+   * @throws `ERR_SESSION_READONLY_EVENT` if a `"cookie"` session's response was already sent.
+   */
+  clear: () => Promise<SessionManager<T, ConfigMaxAge>>;
+}
+/** The config members every session shares, whether it signs or encrypts its token. */
+interface SessionBaseConfig<MaxAge extends ExpiresIn | undefined = ExpiresIn | undefined> {
+  /** Session lifetime: each token gets `exp = iat + maxAge` and its cookie expires then. An incoming token must have `exp` and ends at `exp` or `iat + maxAge`, whichever is sooner. @default undefined (never expires) */
+  maxAge?: MaxAge;
+  /**
+   * Reissues a session read from its cookie. Requires `maxAge`.
+   * - `true`: every read reissues.
+   * - a duration, shorter than `maxAge`: a read reissues once the token is at least that old. With `maxAge: "1h"` and
+   *   `rolling: "15m"`, reads in the first 15 minutes change nothing, and the first read after that issues a fresh hour.
+   *
+   * A read that cannot write the cookie (no response, or a response already sent) does not reissue. The next request, which sends the same token, does.
+   * A session read from the session header or from a token in hand never reissues: its token stays the one the client sent.
+   * @default undefined (the session expires at `iat + maxAge` however often it is read)
+   */
+  rolling?: true | ExpiresIn;
+  /** Cookie name, also the base of the default session header. A valid cookie name without a trailing `.<digits>`. `__Host-` and `__Secure-` names get their prefix rules checked. */
+  name?: string;
+  /**
+   * Request header to read a bare or `Bearer` token from: a header name, `true` for `x-<name>-session` (without a `__Host-` or `__Secure-` prefix), or `false` for none.
+   * A request that sends it is read from it alone and its cookie is left as it is, unless the header holds the very token of the request's session cookie: that request is a cookie session.
+   * A value that is not a token runs `onError`.
+   * With no header read and `cookie: false`, the session has no token source and reading it throws `ERR_SESSION_CONFIG_INVALID`. @default undefined (no header is read)
+   */
+  sessionHeader?: boolean | string;
+  /** 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. */
+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 & {
+    session: TManager & {
+      id: string;
+      token: string;
+    };
+    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. */
+  onUpdate?: (args: TArgs & {
+    session: TManager & {
+      id: string;
+      token: string;
+    };
+    /** The session before the update, its data deep-copied. */
+    oldSession: TSession;
+    trigger: SessionUpdateTrigger;
+    config: TConfig;
+  }) => void | Promise<void>;
+  /** Runs when `clear()` empties the session. `oldSession` is `undefined` when the session had no `id`, no token and no `error`. */
+  onClear?: (args: TArgs & {
+    oldSession: TSession | undefined;
+    config: TConfig;
+  }) => void | Promise<void>;
+  /** Runs when the incoming token is expired, with its decoded claims and the `ERR_JWT_EXPIRED` error. The session is empty after it. */
+  onExpire?: (args: TArgs & {
+    session: {
+      id: string | undefined;
+      createdAt: number | undefined;
+      expiresAt: number | undefined;
+      token: string;
+      /** Where the expired token came from. */
+      source: SessionSource;
+    };
+    error: JWTError;
+    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.
+   * - `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.
+   */
+  onError?: (args: TArgs & {
+    session: TManager;
+    error: any;
+    config: TConfig;
+  }) => void | Promise<void>;
+}
+/** Overrides for one `update()` or `issue()` call. */
+interface SessionIssueOptions {
+  /** Lifetime of this token, in place of the config's `maxAge`. A read under the config's `maxAge` still ends the session at `iat + maxAge`. */
+  maxAge?: ExpiresIn;
+}
+/** Session state for the current request, from the claims of its token. */
+interface SessionState<T extends SessionRecord, MaxAge extends ExpiresIn | undefined> {
+  /** Session ID (`jti`), `undefined` until a token is read or issued. */
+  id: string | undefined;
+  /** Issue time in ms, from the `iat` claim in seconds. */
+  createdAt: number;
+  /** Expiry in ms, from the `exp` claim in seconds, or `iat + maxAge` when sooner. */
+  expiresAt: MaxAge extends ExpiresIn ? number : number | undefined;
+  data: SessionData<T>;
+  token: string | undefined;
+  /** Where the token of this request comes from. */
+  source: SessionSource;
+  /** The error the read of this request ended with, `ERR_JWT_EXPIRED`, `ERR_SESSION_TOKEN_INVALID` or `ERR_SESSION_READ_FAILED`, the object its hook received. `undefined` when the request carries no token, when the read succeeded, and after `update()` or `clear()`. */
+  error: JWTError | undefined;
+}
+/** Session state that `open()` reads from a token: `id` and `createdAt` are always set, and `source` is `"token"`. */
+type OpenedSessionState<T extends SessionRecord, MaxAge extends ExpiresIn | undefined> = Pick<SessionState<T, MaxAge>, "id" | "createdAt" | "expiresAt" | "data" | "source"> & {
+  id: string;
+  createdAt: number;
+};
+/** One session, defined once from its config and used on any request. */
+interface SessionDefinition<T extends SessionRecord = SessionClaims, MaxAge extends ExpiresIn | undefined = ExpiresIn | undefined, TEvent = WebSessionEvent> {
+  /**
+   * 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.
+   */
+  use: (event: TEvent) => Promise<SessionManager<T, MaxAge>>;
+  /**
+   * Returns the transport's token, unopened: the one the request carries (a handed token, the session header when it is present and differs from
+   * the cookie, otherwise the cookie) whatever `use()` made of it, or the one `update()` issued on this request. `undefined` when the request
+   * carries none, and after `clear()`. A failed read leaves it as sent, so a caller can forward or log it and tell no token from one that could
+   * not be checked. The token behind the session's state, `undefined` once a read fails, is the manager's `token`.
+   */
+  token: (event: TEvent) => string | undefined;
+  /** Returns a token for `data` with a fresh `jti` and `iat`, and `exp` from `maxAge` (`options.maxAge` overrides it). Reads and writes no request. @throws `ERR_INVALID_OPTION` if `data` is not a plain object or holds `__proto__`, `constructor` or `prototype`. */
+  issue: (data?: Partial<SessionData<T>>, options?: SessionIssueOptions) => Promise<string>;
+  /**
+   * Opens a token into session state. Checks `typ`, the algorithms the keys serve, `jti`, `iat`, and `exp` when `maxAge` is set. The key lookup hook receives no event.
+   * @throws `ERR_JWT_EXPIRED` if the token is expired.
+   * @throws `ERR_SESSION_TOKEN_INVALID` if the token fails any other check.
+   * @throws `ERR_SESSION_READ_FAILED` if the key lookup hook throws or returns a key that cannot be used.
+   */
+  open: (token: string) => Promise<OpenedSessionState<T, MaxAge>>;
+}
+interface SessionRequestBase {
+  /** The response being prepared. Without it the session is read-only. Each cookie write is copied to `errHeaders` too: h3 and Nitro send only these for a thrown handler. */
+  readonly res?: {
+    readonly headers: Headers;
+    readonly errHeaders?: Headers;
+  };
+  /** 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. */
+type SessionRequestEvent = SessionRequestBase & ({
+  readonly req: Request;
+  readonly headers?: Headers;
+} | {
+  readonly headers: Headers;
+  readonly req?: Request;
+});
+/** A token passed in directly. `update()` issues onto `session.token`, and sending it is the caller's job. */
+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`. */
+type WebSessionEvent = SessionRequestEvent | SessionHandedToken;
+/**
+ * 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
+ * `oct` JWK without `alg`) requires a pinned `jws.signOptions.alg`, unless it is the half of a pair whose other half names one, which it
+ * then must carry. A pair's single `publicKey` that names an algorithm names the one `privateKey` signs with, and a list or JWK Set
+ * holds at least one key that serves it, beside keys of other algorithms. A JWK Set's first key signs and every key verifies, each checked as a lone key, the pin naming the first alone; a
+ * token of a key without `kid` may meet at most `jws.verifyOptions.limits.keyCandidates` keys, those whose `alg` serves it and those
+ * without `alg`. A lone asymmetric key throws `ERR_SESSION_KEY_INVALID`: it signs with one half and verifies with the other, so pass
+ * both as a pair.
+ */
+type JWSSessionKey = CryptoKey | JWK_oct<JWK_HMAC> | JWKSet<JWK_oct<JWK_HMAC>[]> | {
+  privateKey: JWSAsymmetricPrivateJWK | CryptoKey;
+  publicKey: JWSAsymmetricPublicJWK | JWSAsymmetricPublicJWK[] | JWKSet | CryptoKey;
+};
+interface ExpirableCookieAttributes {
+  expires?: Date;
+  maxAge?: number;
+}
+/** The cookies of one request and its response, as a framework exposes them. */
+interface CookieJar<A extends ExpirableCookieAttributes = ExpirableCookieAttributes> {
+  /** Returns the request's cookie `name`. */
+  read(name: string): string | undefined;
+  /** Returns the value this response already set for `name` (`""` once deleted). Implement it when the framework exposes response cookies. */
+  written?(name: string): string | undefined;
+  /** Sets a response cookie. Omit it when the event cannot send a `Set-Cookie` (a request without a response): a cookie session is then read-only. */
+  write?(name: string, value: string, attrs: A): void;
+}
+/** What a framework driver implements. The session reads its token and writes its cookie through these members. */
+interface SessionDriver<TEvent> {
+  /** Starts the message of every error the session throws. */
+  prefix: string;
+  /** Returns a record unique to the request, where session state and the name registry are stored. */
+  state(event: TEvent): Record<string, unknown>;
+  /** Returns a request header by lowercase name. */
+  header(event: TEvent, name: string): string | null | undefined;
+  /** Returns the cookie jar of the request and its response. */
+  cookies(event: TEvent): CookieJar;
+  /** Returns `false` once the response was sent (Node `headersSent`): `update()` and `clear()` then throw `ERR_SESSION_READONLY_EVENT`. Omitted, the response stays writable. */
+  writable?(event: TEvent): boolean;
+  /** Returns `{ token }` when the event holds the token itself. No cookie or header is read then, and the session's source is `"token"`. */
+  handed?(event: 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_CONFIG_INVALID` if the token needs more than 16 cookie chunks.
+   */
+  write?: (token: string, options?: {
+    expiresAt?: number;
+  }) => boolean;
+  /**
+   * 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`,
+ * `maxTokenAge`, `validateClaims` and `payload` itself.
+ */
+type SessionVerifyOptions = StrictOmit<JWSVerifyOptions, "typ" | "maxTokenAge" | "validateClaims" | "payload">;
+/** JWS sign options a session accepts. The session sets `exp` from `maxAge` and never sets `nbf`. */
+type SessionSignOptions = StrictOmit<JWSSignOptions, "expiresIn" | "expiresAt" | "notBeforeIn" | "notBeforeAt">;
+/** The JWS options of a session: `signOptions` for each issued token, `verifyOptions` for each incoming one. */
+interface JWSSessionOptions {
+  signOptions?: SessionSignOptions;
+  verifyOptions?: SessionVerifyOptions;
+}
+/** The config of a JWS session, without its hooks. */
+interface JWSSessionConfig<MaxAge extends ExpiresIn | undefined = ExpiresIn | undefined, TCookie extends object = object> extends SessionBaseConfig<MaxAge> {
+  /** The key, or JWK Set, that signs and verifies the token. See {@link JWSSessionKey}. */
+  key: JWSSessionKey;
+  /** Cookie attributes, or `false` for no cookie. `chunkMaxLength` is the size the token is split at (`4000` when unset). `httpOnly: false` lets page scripts read the signed payload. @default { path: "/", secure: true, httpOnly: true, sameSite: "lax" } */
+  cookie?: false | (TCookie & {
+    chunkMaxLength?: number;
+  });
+  /**
+   * `signOptions.alg` is what each token is signed with, and names the algorithm of a key without its own `alg`, both halves of a pair
+   * included when neither names one: a half without one takes the `alg` its other half names. Verification accepts every `alg` the keys
+   * serve: a JWK's own `alg` (or an EC or OKP JWK's curve), and for a key without one, the pin and each algorithm of
+   * `verifyOptions.algorithms` its material carries. An empty `verifyOptions.algorithms`, or one listing an algorithm no key serves,
+   * throws `ERR_SESSION_CONFIG_INVALID`, unless `onKeyLookup` is set for the latter.
+   * `signOptions.protectedHeader.typ` defaults to `"session+jwt"` (RFC 8725 §3.11).
+   */
+  jws?: JWSSessionOptions;
+}
+/** 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. */
-interface SessionHooksJWS<T extends SessionRecord = SessionClaims, MaxAge extends ExpiresIn | undefined = ExpiresIn | undefined, TEvent = WebSessionEvent> extends JWSSessionHooks<SessionJWS<T, MaxAge>, SessionManager<T, MaxAge>, {
+/** JWS session hooks. `onRead`, `onExpire` and `onError` are mutually exclusive per token. */
+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>> {}
-/** Configuration for a JWS-backed (signed, not encrypted) session. */
+}, SessionConfigJWS<T, MaxAge, TEvent>> {
+  /** Returns the key that verifies an incoming token. See {@link JWSSessionKeyLookup}. */
+  onKeyLookup?: JWSSessionKeyLookup<T, MaxAge, TEvent>;
+}
+/**
+ * Returns the key that verifies an incoming token, picked from its protected header, by `kid` when keys rotate: an HMAC or public JWK, a
+ * `CryptoKey` or a JWK Set, the shapes `key` takes for verification. Set, it replaces `key` for verification: the token's `alg` is still one
+ * `key` serves or `verifyOptions.algorithms` lists. A `CryptoKey` it returns names no algorithm of its own: as for a lone `CryptoKey` key,
+ * `verifyOptions.algorithms` or the pin names what it serves. A JWK Set offers the token its keys of the token's `kid` (all of them when it
+ * names none) that serve its `alg`, in order, and a token offered more than `verifyOptions.limits.keyCandidates` keys is refused. Nothing
+ * it returns is checked when the session is defined. `undefined` means no key for this token: the token fails with
+ * `ERR_SESSION_TOKEN_INVALID`, an `ERR_JWK_KEY_NOT_FOUND` as its `cause`, and its cookie is expired. Any throw, a `JWTError` or not, means
+ * the token could not be read: `ERR_SESSION_READ_FAILED`, the thrown error as its `cause`, and the cookie is kept. A key it returns that cannot
+ * be used for the token's `alg` is the same read failure, an `ERR_JWK_INVALID` as its `cause`. `open()` passes it no event.
+ */
+type JWSSessionKeyLookup<T extends SessionRecord = SessionClaims, MaxAge extends ExpiresIn | undefined = ExpiresIn | undefined, TEvent = WebSessionEvent> = (lookup: {
+  header: JWSHeaderParameters;
+  config: SessionConfigJWS<T, MaxAge, TEvent>;
+  event?: TEvent;
+}) => JWSVerifyJWK | CryptoKey | JWKSet | undefined | Promise<JWSVerifyJWK | CryptoKey | JWKSet | undefined>;
+/** Configuration of a JWS session, signed but not encrypted. */
 interface SessionConfigJWS<T extends SessionRecord = SessionClaims, MaxAge extends ExpiresIn | undefined = ExpiresIn | undefined, TEvent = WebSessionEvent> extends JWSSessionConfig<MaxAge, CookieAttributes> {
-  /** Cookie and session-header name. Default `"unjwt-jws"`; a `.<digits>` suffix throws `ERR_SESSION_CONFIG_INVALID`. */
+  /** Cookie name, also the base of the default session header `x-unjwt-jws-session`. A trailing `.<digits>` throws `ERR_SESSION_CONFIG_INVALID`. @default "__Host-unjwt-jws" */
   name?: string;
+  /** Lifecycle hooks and `onKeyLookup`. */
   hooks?: SessionHooksJWS<T, MaxAge, TEvent>;
 }
-/** Defines a JWS (signed, not encrypted) session once, its data readable by clients; `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.
+ * @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 (signed, not encrypted) session over a framework driver of your own. */
+/**
+ * Defines a JWS session over a framework driver of your own, passed as `{ driver }`.
+ * @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 = WebSessionEvent>(config: SessionConfigJWS<T, MaxAge, TEvent>, options: {
   driver: SessionDriver<TEvent>;
 }): SessionDefinition<T, MaxAge, TEvent>;
-/** Session state for the current request, mirroring the claims of its JWE token. */
+/** An `oct` JWK that JWE key management accepts. */
+type JWESessionOctJWK = Extract<JWEDecryptJWK, {
+  kty: "oct";
+}>;
+/**
+ * A symmetric key that encrypts and decrypts, an `oct` JWK or a secret `CryptoKey`, or a JWK Set of `oct` JWKs. A key without `alg` (a
+ * `CryptoKey`, an `oct` JWK without `alg`) requires a pinned `jwe.encryptOptions.alg` and `enc`. A JWK Set's first key encrypts and
+ * every key decrypts, each checked as a lone key, the pin naming the first alone; a token of a key without `kid` may meet at most
+ * `jwe.decryptOptions.limits.keyCandidates` keys, those whose `alg` serves it and those without `alg`. An asymmetric key throws `ERR_SESSION_KEY_INVALID`: its public half encrypts, so anyone holding that half
+ * could forge a session the server accepts. Use `defineJWSSession` for a key pair.
+ */
+type JWESessionKey = JWESessionOctJWK | CryptoKey | JWKSet<JWESessionOctJWK[]>;
+/**
+ * JWE decrypt options a session accepts. `algorithms` names the `alg` values a key without its own `alg` (a `CryptoKey`, an `oct` JWK
+ * without `alg`) decrypts, and with `onKeyLookup` set, may also name those only the keys it returns serve. The session sets `typ`,
+ * `maxTokenAge`, `validateClaims` and `payload` itself, and takes no `encryptionAlgorithms`: a key decrypts every `enc` it serves.
+ */
+type SessionDecryptOptions = StrictOmit<JWEDecryptOptions, "encryptionAlgorithms" | "typ" | "maxTokenAge" | "validateClaims" | "payload">;
+/** JWE encrypt options a session accepts. The session sets `exp` from `maxAge` and never sets `nbf`. */
+type SessionEncryptOptions = StrictOmit<JWEEncryptOptions, "expiresIn" | "expiresAt" | "notBeforeIn" | "notBeforeAt">;
+/** The JWE options of a session: `encryptOptions` for each issued token, `decryptOptions` for each incoming one. */
+interface JWESessionOptions {
+  encryptOptions?: SessionEncryptOptions;
+  decryptOptions?: SessionDecryptOptions;
+}
+/** The config of a JWE session, without its hooks. */
+interface JWESessionConfig<MaxAge extends ExpiresIn | undefined = ExpiresIn | undefined, TCookie extends object = object> extends SessionBaseConfig<MaxAge> {
+  /** The key, or JWK Set, that encrypts and decrypts the token. See {@link JWESessionKey}. */
+  key: JWESessionKey;
+  /** Cookie attributes, or `false` for no cookie. `chunkMaxLength` is the size the token is split at (`4000` when unset). @default { path: "/", secure: true, httpOnly: true, sameSite: "lax" } */
+  cookie?: false | (TCookie & {
+    chunkMaxLength?: number;
+  });
+  /**
+   * `encryptOptions.alg` and `enc` are what each token is encrypted with, and name the algorithm of a key without its own `alg`.
+   * Decryption accepts every `alg` the key serves: a JWK's own `alg`, and for a key without one, the pin and each algorithm of
+   * `decryptOptions.algorithms` its material carries. An empty `decryptOptions.algorithms`, or one listing an algorithm no key serves,
+   * throws `ERR_SESSION_CONFIG_INVALID`, unless `onKeyLookup` is set for the latter. A `dir` key decrypts its own `enc` alone, a wrapping
+   * key every `enc`. `encryptOptions.protectedHeader.typ` defaults to `"session+jwt"` (RFC 8725 §3.11). A PBES2 session accepts at most
+   * the `p2c` it issues with, unless `decryptOptions.maxIterations` is set.
+   */
+  jwe?: JWESessionOptions;
+}
+/** 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. */
-interface SessionHooksJWE<T extends SessionRecord = SessionClaims, MaxAge extends ExpiresIn | undefined = ExpiresIn | undefined, TEvent = WebSessionEvent> extends JWESessionHooks<SessionJWE<T, MaxAge>, SessionManager<T, MaxAge>, {
+/** JWE session hooks. `onRead`, `onExpire` and `onError` are mutually exclusive per token. */
+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>> {}
-/** Configuration for a JWE-backed (encrypted) session. */
+}, SessionConfigJWE<T, MaxAge, TEvent>> {
+  /** Returns the key that decrypts an incoming token. See {@link JWESessionKeyLookup}. */
+  onKeyLookup?: JWESessionKeyLookup<T, MaxAge, TEvent>;
+}
+/**
+ * Returns the key that decrypts an incoming token, picked from its protected header, by `kid` when keys rotate: an `oct` JWK, a
+ * `CryptoKey` or a JWK Set, the shapes `key` takes for decryption. Set, it replaces `key` for decryption: the token's `alg` is still one
+ * `key` serves or `decryptOptions.algorithms` lists. A `CryptoKey` it returns names no algorithm of its own: as for a lone `CryptoKey` key,
+ * `decryptOptions.algorithms` or the pin names what it serves. A JWK Set offers the token its keys of the token's `kid` (all of them when it
+ * names none) that serve its `alg`, in order, and a token offered more than `decryptOptions.limits.keyCandidates` keys is refused. Nothing
+ * it returns is checked when the session is defined. `undefined` means no key for this token: the token fails with
+ * `ERR_SESSION_TOKEN_INVALID`, an `ERR_JWK_KEY_NOT_FOUND` as its `cause`, and its cookie is expired. Any throw, a `JWTError` or not, means
+ * the token could not be read: `ERR_SESSION_READ_FAILED`, the thrown error as its `cause`, and the cookie is kept. A key it returns that cannot
+ * be used for the token's `alg` is the same read failure, an `ERR_JWK_INVALID` as its `cause`. `open()` passes it no event.
+ */
+type JWESessionKeyLookup<T extends SessionRecord = SessionClaims, MaxAge extends ExpiresIn | undefined = ExpiresIn | undefined, TEvent = WebSessionEvent> = (lookup: {
+  header: JWEHeaderParameters;
+  config: SessionConfigJWE<T, MaxAge, TEvent>;
+  event?: TEvent;
+}) => JWEDecryptJWK | CryptoKey | JWKSet | undefined | Promise<JWEDecryptJWK | CryptoKey | JWKSet | undefined>;
+/** Configuration of an encrypted JWE session. */
 interface SessionConfigJWE<T extends SessionRecord = SessionClaims, MaxAge extends ExpiresIn | undefined = ExpiresIn | undefined, TEvent = WebSessionEvent> extends JWESessionConfig<MaxAge, CookieAttributes> {
-  /** Cookie and session-header name. Default `"unjwt-jwe"`; a `.<digits>` suffix throws `ERR_SESSION_CONFIG_INVALID`. */
+  /** Cookie name, also the base of the default session header `x-unjwt-jwe-session`. A trailing `.<digits>` throws `ERR_SESSION_CONFIG_INVALID`. @default "__Host-unjwt-jwe" */
   name?: string;
+  /** Lifecycle hooks and `onKeyLookup`. */
   hooks?: SessionHooksJWE<T, MaxAge, TEvent>;
 }
-/** Defines a JWE (encrypted) session once; `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.
+ * @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 (encrypted) session over a framework driver of your own. */
+/**
+ * Defines a JWE session over a framework driver of your own, passed as `{ driver }`.
+ * @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 = WebSessionEvent>(config: SessionConfigJWE<T, MaxAge, TEvent>, options: {
   driver: SessionDriver<TEvent>;
 }): SessionDefinition<T, MaxAge, TEvent>;
-/** Types a session driver for a framework; pass it to `defineJWSSession` / `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 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 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 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 SessionClaims, type SessionConfigChecks, 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 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 };