unjwt 0.7.3 → 0.8.0

package/README.md

@@ -12,10 +12,10 @@ 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. JWKS fetching, lookup, and rotation.
-- **Framework adapters** — cookie-based JWT sessions for [H3 v1](https://unjwt.s94.dev/adapters) (Nuxt v4 / Nitro v2) and [H3 v2](https://unjwt.s94.dev/adapters) (Nuxt v5 / Nitro v3).
+- **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).
 - **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`, `rou3`).
+- **Zero runtime dependencies** for core; optional peer deps for adapters (`h3`, `cookie-es`, `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)
-- [H3 session adapters →](https://unjwt.s94.dev/adapters)
+- [Session adapters →](https://unjwt.s94.dev/adapters)
 - [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

@@ -0,0 +1,170 @@
+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;
+}
+/** Session data shape; `any` values let an `interface` (no index signature) satisfy it. */
+export type SessionRecord = Record<string, any>;
+export interface SessionClaims extends Required<Pick<JWTClaims, "jti" | "iat">>, StrictOmit<JWTClaims, "jti" | "iat"> {}
+/** Session data without the adapter-owned `jti`, `iat`, `exp` and `nbf`. */
+export type SessionData<T extends SessionRecord = SessionClaims> = StrictOmit<T, "jti" | "iat" | "exp" | "nbf">;
+/** Why `onUpdate` fired: an `update()` call, or `rolling` reissuing a session that was read. */
+export type SessionUpdateTrigger = "update" | "rolling";
+export type SessionUpdate<T extends SessionRecord = SessionClaims> = Partial<SessionData<T>> | ((oldData: SessionData<T>) => Partial<SessionData<T>> | undefined);
+export interface SessionManager<T extends SessionRecord = SessionClaims, ConfigMaxAge extends ExpiresIn | undefined = ExpiresIn | undefined> {
+  readonly id: string | undefined;
+  readonly createdAt: number;
+  /** Expiry in ms — always a number when the session has a `maxAge`. */
+  readonly expiresAt: ConfigMaxAge extends ExpiresIn ? number : number | undefined;
+  readonly data: SessionData<T>;
+  readonly token: string | undefined;
+  /**
+   * Issues a new token after merging `update`; `options.maxAge` overrides this token's lifetime.
+   * Later reads see the data's JSON round trip. Rolls back if issuing or the cookie write fails;
+   * a throwing `onUpdate` rejects but keeps the new session.
+   */
+  update: (update?: SessionUpdate<T>, options?: SessionIssueOptions) => Promise<SessionManager<T, ConfigMaxAge>>;
+  clear: () => Promise<SessionManager<T, ConfigMaxAge>>;
+}
+/** The config members every session shares, whether it signs or seals its token. */
+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`. */
+  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;
+  /** Session ID (`jti`) generator. Default `crypto.randomUUID`. */
+  generateId?: () => string;
+}
+/**
+ * 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> {
+  /** Fires once per request, when the session is read from its token. */
+  onRead?: (args: TCarrier & {
+    session: TManager & {
+      id: string;
+      token: string;
+    };
+    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 & {
+    session: TManager & {
+      id: string;
+      token: string;
+    };
+    /** Deep-copied snapshot of the session before the update. */
+    oldSession: TSession;
+    trigger: SessionUpdateTrigger;
+    config: TConfig;
+  }) => void | Promise<void>;
+  /** Fires when the session is cleared. */
+  onClear?: (args: TCarrier & {
+    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 & {
+    session: {
+      id: string | undefined;
+      createdAt: number | undefined;
+      expiresAt: number | undefined;
+      token: string;
+    };
+    error: Error;
+    config: TConfig;
+  }) => void | Promise<void>;
+  /** Fires on read-path failures other than expiry, and on write-path issue failures. */
+  onError?: (args: TCarrier & {
+    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;
+/** 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. */
+  id: string | undefined;
+  /** In ms; mirrors the JWT `iat` claim (seconds). */
+  createdAt: number;
+  /** In ms; mirrors the JWT `exp` claim (seconds). */
+  expiresAt: MaxAge extends ExpiresIn ? number : number | undefined;
+  data: SessionData<T>;
+  token: string | undefined;
+  [kSessionPending]?: Promise<SessionState<T, MaxAge>>;
+}
+/** HS* `oct` JWK, `CryptoKey` (requires pinned `alg`), or a pair: private signs, public JWK/list/set verifies. */
+type JWSSessionKey = CryptoKey | JWK_oct<JWK_HMAC> | {
+  privateKey: JWSAsymmetricPrivateJWK | CryptoKey;
+  publicKey: JWSAsymmetricPublicJWK | JWSAsymmetricPublicJWK[] | JWKSet | CryptoKey;
+};
+/** JWS verify overrides, minus the options the adapter owns. */
+export type SessionVerifyOptions = StrictOmit<JWSVerifyOptions, "algorithms" | "typ" | "maxTokenAge" | "validateClaims" | "forceUint8Array" | "payload">;
+/** JWS sign options, minus those setting `exp`/`nbf` (the adapter mints `exp` from `maxAge`). */
+export type SessionSignOptions = StrictOmit<JWSSignOptions, "expiresIn" | "expiresAt" | "notBeforeIn" | "notBeforeAt">;
+/** JWS sign/verify overrides a session accepts. */
+interface JWSSessionOptions {
+  signOptions?: SessionSignOptions;
+  verifyOptions?: SessionVerifyOptions;
+}
+/** The config of a JWS-backed (signed, not encrypted) session, minus its hooks. */
+export interface JWSSessionConfig<MaxAge extends ExpiresIn | undefined = ExpiresIn | undefined, TCookie extends object = object> extends SessionBaseConfig<MaxAge> {
+  /** Key used for signing — see {@link JWSSessionKey}. */
+  key: JWSSessionKey;
+  /** `false` to disable. Defaults: `path="/"`, `secure`, `sameSite: "lax"`, `httpOnly: false` (payload is client-readable). */
+  cookie?: false | (TCookie & {
+    chunkMaxLength?: number;
+  });
+  /** Pinned `signOptions.alg` restricts verification; `protectedHeader.typ` defaults to `"session+jwt"` (RFC 8725 §3.11). */
+  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> {
+  /** Resolve the verification key(s) for the incoming token from its protected header (e.g. by `kid`). */
+  onVerifyKeyLookup?: (args: TCarrier & {
+    header: JWKLookupFunctionHeader;
+    config: TConfig;
+  }) => JWKSet | JWSVerifyJWK | Promise<JWKSet | JWSVerifyJWK>;
+}
+/** Symmetric JWK, `CryptoKey` (requires pinned `alg` and `enc`), or a pair: public seals, private unseals. */
+type JWESessionKey = CryptoKey | JWEEncryptJWK | {
+  privateKey: JWEAsymmetricPrivateJWK | CryptoKey;
+  publicKey?: JWEAsymmetricPublicJWK | CryptoKey;
+};
+/** JWE decrypt overrides, minus the options the adapter owns. */
+export type SessionDecryptOptions = StrictOmit<JWEDecryptOptions, "algorithms" | "encryptionAlgorithms" | "typ" | "maxTokenAge" | "validateClaims" | "forceUint8Array" | "payload">;
+/** JWE encrypt options, minus those setting `exp`/`nbf` (the adapter mints `exp` from `maxAge`). */
+export type SessionEncryptOptions = StrictOmit<JWEEncryptOptions, "expiresIn" | "expiresAt" | "notBeforeIn" | "notBeforeAt">;
+/** JWE encrypt/decrypt overrides a session accepts. */
+interface JWESessionOptions {
+  encryptOptions?: SessionEncryptOptions;
+  decryptOptions?: SessionDecryptOptions;
+}
+/** The config of a JWE-backed (encrypted) session, minus its hooks. */
+export interface JWESessionConfig<MaxAge extends ExpiresIn | undefined = ExpiresIn | undefined, TCookie extends object = object> extends SessionBaseConfig<MaxAge> {
+  /** Key used for sealing — see {@link JWESessionKey}. */
+  key: JWESessionKey;
+  /** `false` to disable. Defaults: `path="/"`, `secure`, `sameSite: "lax"`, `httpOnly: true`. */
+  cookie?: false | (TCookie & {
+    chunkMaxLength?: number;
+  });
+  /** Pinned `encryptOptions.alg`/`enc` restrict unsealing; `protectedHeader.typ` defaults to `"session+jwt"` (RFC 8725 §3.11). */
+  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> {
+  /** Resolve the decryption key for the incoming token from its protected header (e.g. by `kid`). */
+  onUnsealKeyLookup?: (args: TCarrier & {
+    header: JWEHeaderParameters;
+    config: TConfig;
+  }) => JWEDecryptJWK | Promise<JWEDecryptJWK>;
+}
+export {};