unjwt 0.8.1 → 0.8.2

package/README.md

@@ -4,7 +4,7 @@
 [![npm downloads](https://npmx.dev/api/registry/badge/downloads/unjwt)](https://npmx.dev/package/unjwt)
 [![bundle size](https://npmx.dev/api/registry/badge/size/unjwt)](https://npmx.dev/package/unjwt)
 
-Low-level JWT toolkit built on the Web Crypto API. Sign, verify, encrypt, decrypt, and manage keys — JWS, JWE, and JWK in a single zero-dependency package.
+A collection of JWT utilities based on the Web Crypto API, in a single zero-dependency package.
 
 > **📖 Documentation — [unjwt.s94.dev](https://unjwt.s94.dev)**
 
@@ -13,9 +13,9 @@ Low-level JWT toolkit built on the Web Crypto API. Sign, verify, encrypt, decryp
 - **JWS** ([RFC 7515](https://datatracker.ietf.org/doc/html/rfc7515)) — HMAC, RSA, RSA-PSS, ECDSA, EdDSA. Compact + General/Flattened JSON Serialization (multi-signature).
 - **JWE** ([RFC 7516](https://datatracker.ietf.org/doc/html/rfc7516)) — `dir`, AES-KW, AES-GCM-KW, RSA-OAEP, PBES2, ECDH-ES. AES-GCM and AES-CBC-HMAC-SHA2 content encryption. Compact + General/Flattened JSON Serialization (multi-recipient).
 - **JWK** ([RFC 7517](https://datatracker.ietf.org/doc/html/rfc7517)) — generate, import, export, wrap, unwrap. `CryptoKey` ↔ JWK ↔ PEM conversion. ECDH-ES shared-secret derivation. JWK Set lookup and rotation over a set your application fetches.
-- **Framework adapters** — cookie-based JWT sessions for [H3 v1](https://unjwt.s94.dev/adapters) (Nuxt v4 / Nitro v2), [H3 v2](https://unjwt.s94.dev/adapters) (Nuxt v5 / Nitro v3) and [Elysia](https://unjwt.s94.dev/adapters/elysia).
+- **Sessions** — cookie-based JWT sessions through [`unjwt/session`](https://unjwt.s94.dev/frameworks/session) on [h3 v2](https://unjwt.s94.dev/frameworks/h3), [Nitro 3](https://unjwt.s94.dev/frameworks/nitro), [Nuxt 4.6+](https://unjwt.s94.dev/frameworks/nuxt), Workers, Bun, Deno and Hono, or on a token in hand; an [Elysia](https://unjwt.s94.dev/frameworks/elysia) plugin; a [driver](https://unjwt.s94.dev/frameworks/drivers) for any other framework.
 - **Runtime-agnostic** — Node 22+, Deno, Bun, Cloudflare Workers, browsers. Anywhere Web Crypto runs.
-- **Zero runtime dependencies** for core; optional peer deps for adapters (`h3`, `cookie-es`, `elysia`).
+- **Zero runtime dependencies** for core; optional peer deps for adapters (`h3`, `elysia`).
 
 ## Install
 
@@ -55,7 +55,7 @@ Full walkthroughs, recipes, and the complete API reference live at **[unjwt.s94.
 - [JWS — signing and verifying →](https://unjwt.s94.dev/jwt/jws)
 - [JWE — encrypting and decrypting →](https://unjwt.s94.dev/jwt/jwe)
 - [JWK — key management →](https://unjwt.s94.dev/jwk)
-- [Session adapters →](https://unjwt.s94.dev/adapters)
+- [Sessions on your framework →](https://unjwt.s94.dev/frameworks)
 - [Examples →](https://unjwt.s94.dev/examples) — authentication, JWKS endpoints, refresh tokens, end-to-end encryption, signed receipts.
 
 ## Development

package/dist/_chunks/_codec-jwe.d.mts

@@ -1,8 +1,7 @@
-import { ExpiresIn, JWEAsymmetricPrivateJWK, JWEAsymmetricPublicJWK, JWEDecryptJWK, JWEDecryptOptions, JWEEncryptJWK, JWEEncryptOptions, JWEHeaderParameters, JWKLookupFunctionHeader, JWKSet, JWK_HMAC, JWK_oct, JWSAsymmetricPrivateJWK, JWSAsymmetricPublicJWK, JWSSignOptions, JWSVerifyJWK, JWSVerifyOptions, JWTClaims, StrictOmit } from "./index.mjs";
-/** Per-issue overrides for a single `update()` call. */
-export interface SessionIssueOptions {
-  /** Lifetime for this issue only, overriding the config's `maxAge`. */
-  maxAge?: ExpiresIn;
+import { ExpiresIn, JWEAsymmetricPrivateJWK, JWEAsymmetricPublicJWK, JWEDecryptJWK, JWEDecryptOptions, JWEEncryptJWK, JWEEncryptOptions, JWEHeaderParameters, JWKSet, JWK_HMAC, JWK_oct, JWSAsymmetricPrivateJWK, JWSAsymmetricPublicJWK, JWSHeaderParameters, JWSSignOptions, JWSVerifyJWK, JWSVerifyOptions, JWTClaims, StrictOmit } from "./index.mjs";
+interface ExpirableCookieAttributes {
+  expires?: Date;
+  maxAge?: number;
 }
 /** Session data shape; `any` values let an `interface` (no index signature) satisfy it. */
 export type SessionRecord = Record<string, any>;
@@ -31,12 +30,28 @@ export interface SessionManager<T extends SessionRecord = SessionClaims, ConfigM
 interface SessionBaseConfig<MaxAge extends ExpiresIn | undefined = ExpiresIn | undefined> {
   /** Sets `exp = iat + maxAge`, requires `exp` on incoming tokens, drives cookie expiry; unset never expires. */
   maxAge?: MaxAge;
-  /** Reissues a session on read, so `exp` slides: `true` on every read, a duration once less than that remains. Needs `maxAge`. */
+  /**
+   * Reissue the session when it is read, needs `maxAge`.
+   *
+   * - `true`: every read reissues.
+   * - a duration: a read reissues once the token is at least that old, so an active session is
+   *   re-signed at most once per duration. With `maxAge: "1h"` and `rolling: "15m"`, reads in the
+   *   first 15 minutes change nothing; the first read after that issues a fresh hour. Must be
+   *   shorter than `maxAge`.
+   *
+   * A read that cannot write (a read-only context, a response already sent) does not reissue;
+   * the next request, carrying the same token, does.
+   *
+   * @default undefined — the session expires at `iat + maxAge` however often it is read.
+   */
   rolling?: true | ExpiresIn;
   /** Drives the cookie name and default header; prefer `__Host-`; a trailing `.<digits>` is refused. */
   name?: string;
-  /** Header carrying a bare or `Bearer` token, or `false`. Default `x-<name>-session` (cookie prefix stripped). */
-  sessionHeader?: false | string;
+  /**
+   * Header carrying a bare or `Bearer` token: a header name, `true` for `x-<name>-session` (cookie prefix stripped), or `false` for none.
+   * Left unset, a session with cookies still reads `x-<name>-session`, and so does one with `cookie: false`.
+   */
+  sessionHeader?: boolean | string;
   /** Session ID (`jti`) generator. Default `crypto.randomUUID`. */
   generateId?: () => string;
 }
@@ -44,9 +59,9 @@ interface SessionBaseConfig<MaxAge extends ExpiresIn | undefined = ExpiresIn | u
  * Lifecycle hooks; `onRead`, `onExpire` and `onError` are mutually exclusive per incoming token.
  * `session` is the live manager, so a hook can `update()` or `clear()` in place; `oldSession` is a snapshot.
  */
-interface SessionHooks<TSession, TManager, TCarrier extends Record<string, unknown>, TConfig> {
+interface SessionHooks<TSession, TManager, TArgs extends Record<string, unknown>, TConfig> {
   /** Fires once per request, when the session is read from its token. */
-  onRead?: (args: TCarrier & {
+  onRead?: (args: TArgs & {
     session: TManager & {
       id: string;
       token: string;
@@ -54,7 +69,7 @@ interface SessionHooks<TSession, TManager, TCarrier extends Record<string, unkno
     config: TConfig;
   }) => void | Promise<void>;
   /** Fires after a token is issued and its cookie written, by `update()` or by `rolling`; a throw rejects without rollback. */
-  onUpdate?: (args: TCarrier & {
+  onUpdate?: (args: TArgs & {
     session: TManager & {
       id: string;
       token: string;
@@ -65,12 +80,12 @@ interface SessionHooks<TSession, TManager, TCarrier extends Record<string, unkno
     config: TConfig;
   }) => void | Promise<void>;
   /** Fires when the session is cleared. */
-  onClear?: (args: TCarrier & {
+  onClear?: (args: TArgs & {
     oldSession: TSession | undefined;
     config: TConfig;
   }) => void | Promise<void>;
   /** Fires when the incoming token is expired. Receives the expired token's decoded claims. */
-  onExpire?: (args: TCarrier & {
+  onExpire?: (args: TArgs & {
     session: {
       id: string | undefined;
       createdAt: number | undefined;
@@ -81,14 +96,17 @@ interface SessionHooks<TSession, TManager, TCarrier extends Record<string, unkno
     config: TConfig;
   }) => void | Promise<void>;
   /** Fires on read-path failures other than expiry, and on write-path issue failures. */
-  onError?: (args: TCarrier & {
+  onError?: (args: TArgs & {
     session: TManager;
     error: any;
     config: TConfig;
   }) => void | Promise<void>;
 }
-/** In-flight read of a session, awaited by a second reader on the same request. */
-declare const kSessionPending: unique symbol;
+/** Per-issue overrides for a single `update()` call. */
+export interface SessionIssueOptions {
+  /** Lifetime for this issue only, overriding the config's `maxAge`. */
+  maxAge?: ExpiresIn;
+}
 /** In-request session state, mirroring the claims of the underlying token. */
 export interface SessionState<T extends SessionRecord, MaxAge extends ExpiresIn | undefined> {
   /** JWT `jti`; `undefined` until the session is persisted. */
@@ -99,7 +117,72 @@ export interface SessionState<T extends SessionRecord, MaxAge extends ExpiresIn
   expiresAt: MaxAge extends ExpiresIn ? number : number | undefined;
   data: SessionData<T>;
   token: string | undefined;
-  [kSessionPending]?: Promise<SessionState<T, MaxAge>>;
+}
+/** Session state read back from a token: always carries its `id` and `createdAt`. */
+export type OpenedSessionState<T extends SessionRecord, MaxAge extends ExpiresIn | undefined> = Pick<SessionState<T, MaxAge>, "id" | "createdAt" | "expiresAt" | "data"> & {
+  id: string;
+  createdAt: number;
+};
+/** One session, defined once from its config and used on any request. */
+export interface SessionDefinition<T extends SessionRecord = SessionClaims, MaxAge extends ExpiresIn | undefined = ExpiresIn | undefined, TContext = unknown> {
+  /** Reads the request's session once and returns its manager; later calls on the same request share that state. */
+  use: (context: TContext) => Promise<SessionManager<T, MaxAge>>;
+  /** The token the request carries (this response's own write first), unopened. */
+  token: (context: TContext) => string | undefined;
+  /** Mints a token for `data` with a fresh `jti` and `iat`, and `exp` from `maxAge` (`options.maxAge` overrides it); reads and writes nothing. */
+  issue: (data?: Partial<SessionData<T>>, options?: SessionIssueOptions) => Promise<string>;
+  /** Opens a token into session state, checking `typ`, pinned algorithms, `jti`/`iat` and `exp` when `maxAge` is set; the key-lookup hook receives no request. */
+  open: (token: string) => Promise<OpenedSessionState<T, MaxAge>>;
+}
+/** A web-standard request event: reads, and writes while `res` is there. */
+export interface SessionRequestEvent {
+  readonly req: Request;
+  /** The response being prepared; without it the session is read-only. */
+  readonly res?: {
+    readonly headers: Headers;
+  };
+  /** The framework's per-request state, where `sessions` is kept; without it state is keyed on `req`. */
+  readonly context?: Record<string, unknown>;
+}
+/** A request by its headers: a `Request` itself, a WebSocket upgrade's request, a peer's `request` with its `context`. */
+export interface SessionRequestHeaders {
+  readonly headers: Headers;
+  /** The response being prepared, such as the headers a WebSocket `upgrade` returns; without it the session is read-only. */
+  readonly res?: {
+    readonly headers: Headers;
+  };
+  /** Per-request state shared with the framework; without it state is keyed on this object. */
+  readonly context?: Record<string, unknown>;
+}
+/** A token handed in directly; sending a re-issued one is the caller's job. */
+export interface SessionToken {
+  token: string | undefined;
+}
+/** What `use()` takes: a request event, a request by its headers, or a token in hand. */
+export type SessionContext = SessionRequestEvent | SessionRequestHeaders | SessionToken;
+/** The cookies of one request and its response, as a framework exposes them. */
+export interface CookieJar<A extends ExpirableCookieAttributes = ExpirableCookieAttributes> {
+  /** The request's cookie. */
+  read(name: string): string | undefined;
+  /** The value this response already assigned to `name` (`""` once deleted), when the framework exposes it. */
+  written?(name: string): string | undefined;
+  /** Absent when this context cannot take a `Set-Cookie` (a headers-only event). */
+  write?(name: string, value: string, attrs: A): void;
+}
+/** The primitives a framework supplies; the session core builds the cookie and header transports over them. */
+export interface SessionDriver<TContext> {
+  /** Message prefix for every error the adapter emits. */
+  prefix: string;
+  /** The per-request record session state and the session-name registry live in. */
+  state(context: TContext): Record<string, unknown>;
+  header(context: TContext, name: string): string | null | undefined;
+  cookies(context: TContext): CookieJar;
+  /** Platform signal that the response can still change (Node `headersSent`); absent = trust the jar. */
+  writable?(context: TContext): boolean;
+  /** A token the context carries directly, when it does: no cookie or header is consulted. */
+  handed?(context: TContext): {
+    token: string | undefined;
+  } | undefined;
 }
 /** HS* `oct` JWK, `CryptoKey` (requires pinned `alg`), or a pair: private signs, public JWK/list/set verifies. */
 type JWSSessionKey = CryptoKey | JWK_oct<JWK_HMAC> | {
@@ -127,10 +210,10 @@ export interface JWSSessionConfig<MaxAge extends ExpiresIn | undefined = Expires
   jws?: JWSSessionOptions;
 }
 /** JWS session hooks, plus the verify key lookup. */
-export interface JWSSessionHooks<TSession, TManager, TCarrier extends Record<string, unknown>, TConfig> extends SessionHooks<TSession, TManager, TCarrier, TConfig> {
+export interface JWSSessionHooks<TSession, TManager, TArgs extends Record<string, unknown>, TConfig> extends SessionHooks<TSession, TManager, TArgs, TConfig> {
   /** Resolve the verification key(s) for the incoming token from its protected header (e.g. by `kid`). */
-  onVerifyKeyLookup?: (args: TCarrier & {
-    header: JWKLookupFunctionHeader;
+  onVerifyKeyLookup?: (args: Partial<TArgs> & {
+    header: JWSHeaderParameters;
     config: TConfig;
   }) => JWKSet | JWSVerifyJWK | Promise<JWKSet | JWSVerifyJWK>;
 }
@@ -160,9 +243,9 @@ export interface JWESessionConfig<MaxAge extends ExpiresIn | undefined = Expires
   jwe?: JWESessionOptions;
 }
 /** JWE session hooks, plus the unseal key lookup. */
-export interface JWESessionHooks<TSession, TManager, TCarrier extends Record<string, unknown>, TConfig> extends SessionHooks<TSession, TManager, TCarrier, TConfig> {
+export interface JWESessionHooks<TSession, TManager, TArgs extends Record<string, unknown>, TConfig> extends SessionHooks<TSession, TManager, TArgs, TConfig> {
   /** Resolve the decryption key for the incoming token from its protected header (e.g. by `kid`). */
-  onUnsealKeyLookup?: (args: TCarrier & {
+  onUnsealKeyLookup?: (args: Partial<TArgs> & {
     header: JWEHeaderParameters;
     config: TConfig;
   }) => JWEDecryptJWK | Promise<JWEDecryptJWK>;