unjwt 0.5.38 → 0.5.39

package/README.md

@@ -10,654 +10,211 @@
 
 A collection of low-level JWT ([RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519)) utilities using the Web Crypto API. Supports:
 
-- **JWS (JSON Web Signature, [RFC 7515](https://datatracker.ietf.org/doc/html/rfc7515))**: sign and verify tokens using HMAC, RSA (RSASSA-PKCS1-v1_5 & RSA-PSS), and ECDSA algorithms.
-- **JWE (JSON Web Encryption, [RFC 7516](https://datatracker.ietf.org/doc/html/rfc7516))**: encrypt and decrypt data using various key management algorithms (AES Key Wrap, AES-GCM Key Wrap, RSA-OAEP, PBES2, ECDH-ES) and content encryption algorithms (AES-GCM, AES-CBC HMAC-SHA2).
-- **JWK (JSON Web Key, [RFC 7517](https://datatracker.ietf.org/doc/html/rfc7517))**: generate, import, export, wrap, and unwrap keys in JWK format or as `CryptoKey` objects.
-
-- **Adapters** for popular frameworks (PRs welcome for more!):
-  - [H3 v1 (Nuxt v4, Nitro v2)](./src/adapters/h3v1/): `useJWSSession()`, `useJWESession()`
-  - [H3 v2 (Nuxt v5, Nitro v3)](./src/adapters/h3v2/): `useJWSSession()`, `useJWESession()`
-
-## Table of Contents
-
-- [Usage](#usage)
-  - [JWS](#jws-json-web-signature-rfc-7515)
-  - [JWE](#jwe-json-web-encryption-rfc-7516)
-  - [JWK](#jwk-json-web-key-rfc-7517)
-  - [Utility Functions](#utility-functions)
-  - [Adapters](#adapters)
-    - [H3 v1 (Nuxt up to v4, Nitro up to v2)](#h3-v1-nuxt-v4-nitro-v2)
-    - [H3 v2 (Nuxt v5, Nitro v3)](#h3-v2-nuxt-v5-nitro-v3)
-- [Development](#development)
-- [Credits](#credits)
-- [License](#license)
+- **JWS** ([RFC 7515](https://datatracker.ietf.org/doc/html/rfc7515)) — sign and verify tokens using HMAC, RSA, RSA-PSS, ECDSA, and EdDSA algorithms
+- **JWE** ([RFC 7516](https://datatracker.ietf.org/doc/html/rfc7516)) — encrypt and decrypt data using AES Key Wrap, AES-GCM KW, RSA-OAEP, PBES2, and ECDH-ES key management with AES-GCM or AES-CBC+HMAC-SHA2 content encryption
+- **JWK** ([RFC 7517](https://datatracker.ietf.org/doc/html/rfc7517)) — generate, import, export, wrap, and unwrap keys (CryptoKey, JWK, PEM)
+- **Framework adapters** for cookie-based JWT sessions:
+  - [H3 v1](./skills/unjwt/references/adapters-h3.md) (Nuxt v4, Nitro v2)
+  - [H3 v2](./skills/unjwt/references/adapters-h3.md) (Nuxt v5, Nitro v3)
 
-## Usage
+Zero runtime dependencies for core. Optional peer deps for adapters (`h3`, `cookie-es`, `rou3`).
 
-Install the package:
+## Install
 
 ```sh
-# ✨ Auto-detect (supports npm, yarn, pnpm, deno and bun)
+# Auto-detect package manager (npm, yarn, pnpm, deno, bun)
 npx nypm install unjwt
 ```
 
-Import:
-
-**ESM** (Node.js, Bun, Deno)
-
-```js
-import { jws, jwe, jwk } from "unjwt";
-// JWS functions
-import { sign, verify } from "unjwt/jws";
-// JWE functions
-import { encrypt, decrypt } from "unjwt/jwe";
-// JWK functions
-import {
-  generateKey,
-  generateJWK,
-  importJWKFromPEM,
-  exportJWKToPEM,
-  deriveKeyFromPassword,
-  deriveJWKFromPassword,
-} from "unjwt/jwk";
-// Utility functions
-import {
-  isJWK,
-  isJWKSet,
-  isSymmetricJWK,
-  isAsymmetricJWK,
-  isPrivateJWK,
-  isPublicJWK,
-} from "unjwt/utils";
-```
-
-**CDN** (Deno, Bun and Browsers)
-
-```js
-import { jws, jwe, jwk } from "https://esm.sh/unjwt";
-// JWS functions
-import { sign, verify } from "https://esm.sh/unjwt/jws";
-// JWE functions
-import { encrypt, decrypt } from "https://esm.sh/unjwt/jwe";
-// JWK functions
-import {
-  generateKey,
-  generateJWK,
-  importJWKFromPEM,
-  exportJWKToPEM,
-  deriveKeyFromPassword,
-  deriveJWKFromPassword,
-} from "https://esm.sh/unjwt/jwk";
-// Utility functions
-import {
-  isJWK,
-  isJWKSet,
-  isSymmetricJWK,
-  isAsymmetricJWK,
-  isPrivateJWK,
-  isPublicJWK,
-} from "https://esm.sh/unjwt/utils";
-```
-
----
-
-### JWS (JSON Web Signature, [RFC 7515](https://datatracker.ietf.org/doc/html/rfc7515))
-
-Functions to sign and verify data according to the JWS specification.
-
-#### `sign(payload, key, options)`
-
-Creates a JWS token.
-
-- `payload`: The data to sign (`string`, `Uint8Array`, or a JSON-serializable `object`).
-- `key`: The signing key (`CryptoKey`, `JWK`, or `Uint8Array` for symmetric keys).
-- `options`:
-  - `alg`: (Required) The JWS algorithm (e.g., `"HS256"`, `"RS256"`, `"ES256"`, `"PS256"`).
-  - `protectedHeader`: An object for additional JWS Protected Header parameters (e.g., `kid`, `typ`, `cty`, `crit`, `b64`). If `payload` is an object and `typ` is not set, it defaults to `"JWT"`. The `b64` parameter ([RFC7797 section-3](https://datatracker.ietf.org/doc/html/rfc7797#section-3)) controls payload encoding (defaults to `true`, meaning Base64URL encoded).
-  - `expiresIn`: Sets an expiration time in seconds (e.g., `3600` for 1 hour). If `iat` is missing it will be set to the current time. If `exp` is missing it will be set to `iat + expiresIn`. This is only applied if `payload` is a JWT.
-  - `currentDate`: The current date for computing `expiresIn` option. Defaults to `new Date()`.
-
-Returns a `Promise<string>` resolving to the JWS token in Compact Serialization format.
-
-**Example (HS256 with string secret):**
-
-```ts
-import { sign } from "unjwt/jws";
-
-const payload = { message: "My important data" }; // Object payload
-const key = await generateKey("HS256", { toJWK: true }); // Generates a JWK_oct
-
-const token = await sign(payload, key);
-
-console.log(token);
-// eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
-```
-
-**Example (RS256 with CryptoKey):**
-
-```ts
-import { sign } from "unjwt/jws";
-import { generateKey } from "unjwt/jwk";
-
-const payload = { userId: 123, permissions: ["read"] };
-const { privateKey } = await generateKey("RS256"); // Generates a CryptoKeyPair
-
-const token = await sign(payload, privateKey, { alg: "RS256" });
-
-console.log(token);
-// eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
-```
-
-#### `verify(jws, key, options?)`
-
-Verifies a JWS token.
-
-- `jws`: The JWS token string.
-- `key`: The verification key (`CryptoKey`, `JWK`, `JWKSet`, `Uint8Array`, or a `KeyLookupFunction`).
-  A `KeyLookupFunction` has the signature `(header: JWSProtectedHeader, jws: string) => Promise<CryptoKey | JWK | JWKSet | Uint8Array> | CryptoKey | JWK | JWKSet | Uint8Array`.
-- `options` (optional):
-  - `algorithms`: An array of allowed JWS `alg` values. If not provided, the `alg` from the JWS header is used.
-  - `validateJWT`: Unless false, will parse payload as JWT and validate claims if applicable (typ includes "jwt", case insensitive). Default `undefined`.
-  - `critical`: An array of JWS header parameter names that the application understands and processes.
-
-Returns a `Promise<JWSVerifyResult<T>>` which is an object `{ payload: T, protectedHeader: JWSProtectedHeader }`.
-The `payload` type `T` can be `JWTClaims` (object), `string`, or `Uint8Array` depending on the JWS content and headers.
-
-**Example (HS256):**
-
-```ts
-import { verify } from "unjwt/jws";
-
-const token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."; // From HS256 sign example
-const secret = "supersecretkey";
-
-const { payload, protectedHeader } = await verify(token, secret);
-console.log(payload); // { message: "My important data" }
-console.log(protectedHeader); // { alg: "HS256", typ: "JWT" }
-```
-
-**Example (RS256 with key lookup):**
-
-```ts
-import { verify } from "unjwt/jws";
-import { generateKey } from "unjwt/jwk";
-
-const token = "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."; // From RS256 sign example
-
-// Example: using a key lookup function
-const { publicKey: rsaPublicKey } = await generateKey("RS256"); // For example purposes, assume publicKey is stored/fetched during lookup
-
-const keyLookup = async (header) => {
-  if (header.alg === "RS256" /* && header.kid === 'expected-kid' */) {
-    return rsaPublicKey;
-  }
-  throw new Error("Unsupported algorithm or key not found");
-};
-
-const { payload } = await verify(token, keyLookup, { algorithms: ["RS256"] });
-console.log(payload); // { userId: 123, permissions: ["read"] }
-```
-
----
-
-### JWE (JSON Web Encryption, [RFC 7516](https://datatracker.ietf.org/doc/html/rfc7516))
-
-Functions to encrypt and decrypt data according to the JWE specification.
-
-#### `encrypt(payload, key, options)`
-
-Encrypts data to produce a JWE token.
-
-- `payload`: The data to encrypt (`string`, `Uint8Array`, or a JSON-serializable `object`).
-- `key`: The Key Encryption Key (KEK) or password (`CryptoKey`, `JWK`, `string`, or `Uint8Array`).
-- `options`:
-  - `alg`: (Required) The JWE Key Management algorithm (e.g., `"A128KW"`, `"RSA-OAEP-256"`, `"PBES2-HS256+A128KW"`, `"ECDH-ES+A128KW"`), defaults depends on the key provided.
-  - `enc`: (Required) The JWE Content Encryption algorithm (e.g., `"A128GCM"`, `"A256CBC-HS512"`), defaults depends on the key provided.
-  - `protectedHeader`: An object for JWE Protected Header parameters (e.g., `kid`, `typ`, `cty`, `crit`, `apu`, `apv`, `p2s`, `p2c`). If `payload` is an object and `typ` is not set, it defaults to `"JWT"`.
-  - `cek`: (Optional) Provide your own Content Encryption Key (`CryptoKey` or `Uint8Array`).
-  - `contentEncryptionIV`: (Optional) Provide your own Initialization Vector for content encryption (`Uint8Array`).
-  - Other algorithm-specific options like `p2s`, `p2c` (for PBES2), `keyManagementIV`, `ecdhPartyUInfo`, `ecdhPartyVInfo`.
-
-Returns a `Promise<string>` resolving to the JWE token in Compact Serialization format.
-
-**Example (PBES2 password-based encryption):**
-
-```ts
-import { encrypt } from "unjwt/jwe";
-
-const plaintext = "Secret message for password protection";
-const password = "myVeryStrongPassword123!";
+## Usage
 
-// Fallback to PBES2-HS256+A128KW and A128GCM if no `alg` and `end` are provided
-const jweToken = await encrypt(plaintext, password);
-console.log(jweToken);
-// JWE token string...
-```
+### JWS — Sign & Verify
 
-**Example (A128KW with A128GCM):**
+> Full reference: [skills/unjwt/references/jws.md](./skills/unjwt/references/jws.md)
 
 ```ts
-import { encrypt } from "unjwt/jwe";
-import { generateKey } from "unjwt/jwk";
+import { sign, verify } from "unjwt/jws";
+import { generateJWK } from "unjwt/jwk";
 
-const payload = { data: "sensitive information" };
-const kek = await generateKey("A128KW"); // AES Key Wrap key
+// Generate a key (HMAC, RSA, ECDSA, EdDSA, etc.)
+const key = await generateJWK("HS256");
 
-const jweToken = await encrypt(payload, kek, {
-  alg: "A128KW",
-  enc: "A128GCM",
-  protectedHeader: { kid: "aes-key-1" },
-});
+// Sign a JWT
+const token = await sign(
+  { sub: "user123", role: "admin" },
+  key,
+  { expiresIn: "1h" }, // supports: number (seconds), "30s", "10m", "2h", "7D", "1Y"
+);
 
-console.log(jweToken);
-// eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4R0NNIiwia2lkIjoiYWVzLWtleS0xIn0...
+// Verify and extract payload
+const { payload, protectedHeader } = await verify(token, key);
+console.log(payload); // { sub: "user123", role: "admin", iat: ..., exp: ... }
 ```
 
-#### `decrypt(jwe, key, options?)`
-
-Decrypts a JWE token.
-
-- `jwe`: The JWE token string.
-- `key`: The Key Decryption Key (KDK) or password (`CryptoKey`, `JWK`, `string`, `Uint8Array`, or a `JWEKeyLookupFunction`).
-  A `JWEKeyLookupFunction` has the signature `(header: JWEHeaderParameters) => Promise<CryptoKey | JWK | string | Uint8Array> | CryptoKey | JWK | string | Uint8Array`.
-- `options` (optional):
-  - `algorithms`: Array of allowed JWE Key Management `alg` values.
-  - `validateJWT`: Unless false, will parse payload as JWT and validate claims if applicable (typ includes "jwt", case insensitive). Default `undefined`.
-  - `encryptionAlgorithms`: Array of allowed JWE Content Encryption `enc` values.
-  - `critical`: Array of JWE header parameter names that the application understands.
-  - `unwrappedKeyAlgorithm`: (For `unwrapKey` internally) Algorithm details for the CEK after unwrapping.
-  - `keyUsage`: (For `unwrapKey` internally) Intended usages for the unwrapped CEK.
-
-Returns a `Promise<JWEDecryptResult<T>>` which is an object `{ payload: T, protectedHeader: JWEHeaderParameters, cek: Uint8Array, aad: Uint8Array }`.
-The `payload` type `T` can be `JWTClaims` (object) or `string`.
-
-**Example (PBES2 password-based decryption):**
+**Asymmetric keys (RS256, ES256, PS256, Ed25519, etc.):**
 
 ```ts
-import { decrypt } from "unjwt/jwe";
-// const jweToken = ...; // From PBES2 encrypt example
-// const password = "myVeryStrongPassword123!";
-
-const { payload } = await decrypt(jweToken, password);
+const keys = await generateJWK("RS256");
+const token = await sign({ sub: "user123" }, keys.privateKey);
+const { payload } = await verify(token, keys.publicKey);
 ```
 
-**Example (A128KW with A128GCM):**
+**Key lookup function for dynamic key resolution:**
 
 ```ts
-import { decrypt } from "unjwt/jwe";
-// const jweToken = "eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4R0NNIiwia2lkIjoiYWVzLWtleS0xIn0...";
-// const kek = ...; // The same AES Key Wrap key used for encryption
-
-async function decryptData(jweToken: string, kek: CryptoKey) {
-  try {
-    const { payload, protectedHeader, cek } = await decrypt(jweToken, kek, {
-      algorithms: ["A128KW"],
-      encryptionAlgorithms: ["A128GCM"],
-    });
-    console.log("Decrypted Plaintext:", payload);
-    console.log("Protected Header:", protectedHeader);
-    // console.log("CEK (Content Encryption Key):", cek);
-  } catch (error) {
-    console.error("Decryption failed:", error);
-  }
-}
+const { payload } = await verify(
+  token,
+  async (header) => {
+    // Resolve key by kid, alg, or any header field
+    return await fetchPublicKeyByKid(header.kid);
+  },
+  { algorithms: ["RS256"] },
+);
 ```
 
----
-
-### JWK (JSON Web Key, [RFC 7517](https://datatracker.ietf.org/doc/html/rfc7517))
-
-Utilities for working with JSON Web Keys.
-
-#### `generateKey(alg, options?)`
-
-Generates a cryptographic key.
+### JWE — Encrypt & Decrypt
 
-- `alg`: The JWA algorithm identifier for the key to be generated (e.g., `"HS256"`, `"RS256"`, `"ES256"`, `"A128KW"`, `"A128GCM"`, `"A128CBC-HS256"`).
-- `options` (optional):
-  - `toJWK`: If `true`, returns the key(s) in JWK format. Otherwise, returns `CryptoKey`(s) or `Uint8Array` (for composite keys like AES-CBC-HS\*). Default `false`.
-  - `extractable`: Boolean, whether the generated `CryptoKey` can be exported. Default `true`.
-  - `keyUsage`: Array of `KeyUsage` strings. Defaults are algorithm-specific.
-  - `modulusLength`: For RSA keys (e.g., `2048`, `4096`). Default `2048`.
-  - `publicExponent`: For RSA keys. Default `new Uint8Array([0x01, 0x00, 0x01])`.
-
-Returns a `Promise` resolving to `CryptoKey`, `CryptoKeyPair`, `Uint8Array` (for composite keys), `JWK`, or `{ privateKey: JWK, publicKey: JWK }` depending on `alg` and `options.toJWK`.
-
-**Examples:**
+> Full reference: [skills/unjwt/references/jwe.md](./skills/unjwt/references/jwe.md)
 
 ```ts
-import { generateKey } from "unjwt/jwk";
-
-// Generate an HS256 CryptoKey
-const hmacKey = await generateKey("HS256");
-console.log(hmacKey); // CryptoKey
-
-// Generate an RS256 CryptoKeyPair
-const rsaKeyPair = await generateKey("RS256", { modulusLength: 2048 });
-console.log(rsaKeyPair.publicKey); // CryptoKey
-console.log(rsaKeyPair.privateKey); // CryptoKey
-
-// Generate an ES384 key pair as JWKs
-const ecJwks = await generateKey("ES384", { toJWK: true });
-console.log(ecJwks.publicKey); // JWK
-console.log(ecJwks.privateKey); // JWK
-
-// Generate a composite key for A128CBC-HS256 as Uint8Array
-const aesCbcHsKeyBytes = await generateKey("A128CBC-HS256");
-console.log(aesCbcHsKeyBytes); // Uint8Array (32 bytes: 16 for AES, 16 for HMAC)
+import { encrypt, decrypt } from "unjwt/jwe";
 
-// Generate an A256GCM key as a JWK
-const aesGcmJwk = await generateKey("A256GCM", { toJWK: true });
-console.log(aesGcmJwk); // JWK
+// Password-based encryption (simplest — uses PBES2)
+const token = await encrypt({ secret: "sensitive data" }, "my-password");
+const { payload } = await decrypt(token, "my-password");
 ```
 
-#### `deriveKeyFromPassword(password, alg, options)`
-
-Derives a key from a password using PBKDF2 for PBES2 algorithms.
-
-- `password`: The password (`string` or `Uint8Array`).
-- `alg`: The PBES2 algorithm (e.g., `"PBES2-HS256+A128KW"`).
-- `options`:
-  - `salt`: The salt (`Uint8Array`, at least 8 octets).
-  - `iterations`: The iteration count (positive integer).
-  - `toJWK`: If `true`, returns a `JWK_oct`. Otherwise, `CryptoKey`. Default `false`.
-  - `extractable`: Boolean for `CryptoKey`. Default `false` unless `toJWK` is true.
-  - `keyUsage`: For `CryptoKey`. Default `["wrapKey", "unwrapKey"]`.
-
-Returns a `Promise` resolving to `CryptoKey` or `JWK_oct`.
-
-**Example:**
+**With explicit key management:**
 
 ```ts
-import { deriveKeyFromPassword } from "unjwt/jwk";
-import { randomBytes, textEncoder } from "unjwt/utils";
+import { generateJWK } from "unjwt/jwk";
 
-const password = "mySecretPassword";
-const salt = randomBytes(16);
-const iterations = 4096;
+// AES Key Wrap
+const aesKey = await generateJWK("A256KW");
+const token = await encrypt({ data: "secret" }, aesKey);
 
-const derivedKey = await deriveKeyFromPassword(password, "PBES2-HS384+A192KW", {
-  salt,
-  iterations,
-});
-console.log(derivedKey); // CryptoKey for AES-KW (192-bit)
+// RSA-OAEP
+const rsaKeys = await generateJWK("RSA-OAEP-256");
+const token2 = await encrypt({ data: "secret" }, rsaKeys.publicKey);
+const { payload } = await decrypt(token2, rsaKeys.privateKey);
 
-const derivedJwk = await deriveKeyFromPassword(password, "PBES2-HS512+A256KW", {
-  salt,
-  iterations,
-  toJWK: true,
-});
-console.log(derivedJwk); // JWK_oct { kty: "oct", k: "...", alg: "A256KW" }
+// ECDH-ES
+const ecKeys = await generateJWK("ECDH-ES+A256KW");
+const token3 = await encrypt({ data: "secret" }, ecKeys.publicKey);
 ```
 
-#### `importKey(keyMaterial, alg?)`
-
-Imports a key from various formats. This is a flexible wrapper.
-
-- `keyMaterial`: The key to import. Can be:
-  - `CryptoKey`: Returned directly.
-  - `Uint8Array`: Returned directly (treated as raw symmetric key bytes).
-  - `string`: Encoded to `Uint8Array` and returned.
-  - `JWK_oct` (symmetric JWK with `k` property): The `k` value is Base64URL decoded and returned as `Uint8Array`.
-  - Other `JWK` types (asymmetric): Imported into a `CryptoKey`.
-- `alg` (optional): The JWA algorithm string. **Required** when importing asymmetric JWKs (e.g., RSA, EC) to provide context for `crypto.subtle.importKey`.
+### JWK — Key Management
 
-Returns a `Promise` resolving to `CryptoKey` or `Uint8Array`.
-
-**Examples:**
+> Full reference: [skills/unjwt/references/jwk.md](./skills/unjwt/references/jwk.md)
 
 ```ts
-import { importKey } from "unjwt/jwk";
-import { textEncoder, base64UrlDecode } from "unjwt/utils";
-
-// Import raw symmetric key bytes
-const rawBytes = textEncoder.encode("a-32-byte-long-secret-key-123"); // 32 bytes for AES-256 or HS256
-const symmetricKeyBytes = await importKey(rawBytes);
-console.log(symmetricKeyBytes); // Uint8Array
-
-// Import a symmetric JWK (kty: "oct")
-const octJwk = {
-  kty: "oct",
-  k: "AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr0", // Example key
-};
-const importedOctBytes = await importKey(octJwk); // Returns Uint8Array
-console.log(importedOctBytes); // Uint8Array (decoded from k)
-
-// Import an RSA Public Key JWK
-const rsaPublicJwk = {
-  kty: "RSA",
-  n: "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3ok92YEnjsADC4Ue87zwRzH2J-TCwlcQrY3E9gGZJZL2g_2_5QjLhL0gR0xYj04_N4M",
-  e: "AQAB",
-  alg: "RS256",
-  kid: "rsa-pub-1",
-};
-const rsaPublicKey = await importKey(rsaPublicJwk, "RS256"); // 'alg' is crucial here
-console.log(rsaPublicKey); // CryptoKey
-```
-
-#### `exportKey(key, jwk?)`
-
-Exports a `CryptoKey` to JWK format.
-
-- `key`: The `CryptoKey` to export (must be `extractable`).
-- `jwk` (optional): A partial `JWK` object to merge with the exported properties (e.g., to add `kid`, `use`, or override `alg`).
+import {
+  generateKey,
+  generateJWK,
+  importKey,
+  exportKey,
+  importJWKFromPEM,
+  exportJWKToPEM,
+  wrapKey,
+  unwrapKey,
+  deriveKeyFromPassword,
+} from "unjwt/jwk";
 
-Returns a `Promise<JWK>`.
+// Generate keys as CryptoKey or JWK
+const hmacKey = await generateKey("HS256"); // CryptoKey
+const rsaPair = await generateKey("RS256"); // CryptoKeyPair
+const ecJwk = await generateJWK("ES256", { kid: "k1" }); // { privateKey: JWK, publicKey: JWK }
 
-**Example:**
+// PEM conversion
+const jwk = await importJWKFromPEM(pemString, "spki", "RS256", undefined, { kid: "rsa-1" });
+const pem = await exportJWKToPEM(jwk, "spki");
 
-```ts
-import { generateKey, exportKey } from "unjwt/jwk";
-
-const { publicKey } = await generateKey("ES256"); // Generates an extractable CryptoKey
-
-const jwk = await exportKey(publicKey, { kid: "ec-key-001", use: "sig" });
-console.log(jwk);
-// {
-//   kty: 'EC',
-//   crv: 'P-256',
-//   x: '...',
-//   y: '...',
-//   ext: true,
-//   key_ops: [ 'verify' ], // or as per generation
-//   kid: 'ec-key-001',
-//   use: 'sig'
-// }
+// Key wrapping
+const cek = crypto.getRandomValues(new Uint8Array(32));
+const { encryptedKey } = await wrapKey("A256KW", cek, aesKey);
+const unwrapped = await unwrapKey("A256KW", encryptedKey, aesKey, { returnAs: false });
 ```
 
-#### `wrapKey(alg, keyToWrap, wrappingKey, options?)`
-
-Wraps a Content Encryption Key (CEK).
-
-- `alg`: The JWA key management algorithm (e.g., `"A128KW"`, `"RSA-OAEP"`).
-- `keyToWrap`: The CEK to wrap (`CryptoKey` or `Uint8Array`).
-- `wrappingKey`: The Key Encryption Key (KEK) (`CryptoKey`, `JWK`, or password `string`/`Uint8Array` for PBES2).
-- `options` (optional): Algorithm-specific options (e.g., `p2s`, `p2c` for PBES2; `iv` for AES-GCMKW).
-
-Returns a `Promise<WrapKeyResult>` containing `encryptedKey` and other parameters like `iv`, `tag`, `epk`, `p2s`, `p2c` as needed by the algorithm.
+### Utility Functions
 
-**Example (AES Key Wrap):**
+> Full reference: [skills/unjwt/references/utils.md](./skills/unjwt/references/utils.md)
 
 ```ts
-import { wrapKey, generateKey } from "unjwt/jwk";
-import { randomBytes } from "unjwt/utils";
-
-const cekToWrap = randomBytes(32); // e.g., a 256-bit AES key as Uint8Array
-const kek = await generateKey("A128KW"); // 128-bit AES Key Wrap key
+import {
+  base64UrlEncode,
+  base64UrlDecode,
+  randomBytes,
+  isJWK,
+  isJWKSet,
+  isSymmetricJWK,
+  isPrivateJWK,
+  isPublicJWK,
+  isCryptoKey,
+  textEncoder,
+  textDecoder,
+} from "unjwt/utils";
 
-const { encryptedKey } = await wrapKey("A128KW", cekToWrap, kek);
-console.log("Wrapped CEK:", encryptedKey); // Uint8Array
+const bytes = randomBytes(32);
+const encoded = base64UrlEncode(bytes);
+const decoded = base64UrlDecode(encoded, false); // Uint8Array
 ```
 
-#### `unwrapKey(alg, wrappedKey, unwrappingKey, options?)`
+### H3 Session Adapters
 
-Unwraps a Content Encryption Key (CEK).
+> Full reference: [skills/unjwt/references/adapters-h3.md](./skills/unjwt/references/adapters-h3.md)
 
-- `alg`: The JWA key management algorithm.
-- `wrappedKey`: The encrypted CEK (`Uint8Array`).
-- `unwrappingKey`: The Key Decryption Key (KDK).
-- `options` (optional):
-  - `returnAs`: If `false`, returns `Uint8Array`. If `true` (default) or undefined, returns `CryptoKey`.
-  - `unwrappedKeyAlgorithm`: `AlgorithmIdentifier` for the imported CEK if `returnAs` is `true`.
-  - `keyUsage`: `KeyUsage[]` for the imported CEK if `returnAs` is `true`.
-  - `extractable`: Boolean for the imported CEK.
-  - Other algorithm-specific options (e.g., `p2s`, `p2c`, `iv`, `tag`, `epk`).
+Cookie-based JWT session management for H3 applications. Sessions are stored as encrypted (JWE) or signed (JWS) tokens in chunked cookies.
 
-Returns a `Promise` resolving to the unwrapped CEK as `CryptoKey` or `Uint8Array`.
+> **Note:** Sessions are lazy — `session.id` is `undefined` until `session.update()` is called. This is intentional for OAuth/spec-compliant flows where sessions should only be created upon valid operations.
 
-**Example (AES Key Unwrap):**
+#### JWE Session (encrypted, recommended for sensitive data)
 
 ```ts
-import { unwrapKey, generateKey } from "unjwt/jwk";
-// const encryptedKey = ...; // From wrapKey example
-// const kdk = ...; // Same KEK used for wrapping
+import { useJWESession, generateJWK } from "unjwt/adapters/h3v2";
 
-async function unwrapMyKey(encryptedKey: Uint8Array, kdk: CryptoKey) {
-  const unwrappedCekBytes = await unwrapKey("A128KW", encryptedKey, kdk, {
-    returnAs: false, // Get raw bytes
+app.get("/profile", async (event) => {
+  const session = await useJWESession(event, {
+    key: process.env.SESSION_SECRET!, // password string, symmetric JWK, or asymmetric keypair
+    maxAge: "7D",
   });
-  console.log("Unwrapped CEK (bytes):", unwrappedCekBytes); // Uint8Array
-
-  const unwrappedCekCryptoKey = await unwrapKey("A128KW", encryptedKey, kdk, {
-    returnAs: true, // Get CryptoKey
-    unwrappedKeyAlgorithm: { name: "AES-GCM", length: 256 }, // Specify CEK's intended alg
-    keyUsage: ["encrypt", "decrypt"],
-  });
-  console.log("Unwrapped CEK (CryptoKey):", unwrappedCekCryptoKey); // CryptoKey
-}
-```
 
-#### `importJWKFromPEM(pem, pemType, alg, importOptions?, jwkExtras?)`
-
-Imports a key from a PEM-encoded string and converts it to a JWK.
-
-- `pem`: The PEM-encoded string (including `-----BEGIN ...-----` and `-----END ...-----` markers).
-- `pemType`: The type of PEM encoding:
-  - `"pkcs8"`: For private keys in PKCS#8 format.
-  - `"spki"`: For public keys in SPKI format.
-  - `"x509"`: For X.509 certificates (extracts the public key).
-- `alg`: The JWA algorithm identifier (e.g., `"RS256"`, `"ES256"`). This is crucial for `crypto.subtle.importKey` to understand the key's intended algorithm and for setting the `'alg'` field in the resulting JWK.
-- `importOptions` (optional): Options for the underlying `crypto.subtle.importKey` call:
-  - `extractable`: Boolean, whether the imported `CryptoKey` should be extractable. Defaults to `true`.
-  - `keyUsage`: Array of `KeyUsage` strings for the imported `CryptoKey`.
-- `jwkExtras` (optional): An object containing additional properties to merge into the resulting JWK (e.g., `"kid"`, `"use"`).
-
-Returns a `Promise<JWK>` resolving to the imported key as a JWK.
-
-**Example:**
-
-```ts
-import { importJWKFromPEM } from "unjwt/jwk";
-
-const rsaPublicJwk = await importJWKFromPEM(
-  provess.env.RSA_PEM_SPKI, // PEM string
-  "spki",
-  "RS256",
-  { extractable: false },
-  { kid: "my-rsa-key" }, // Additional properties to add to the JWK
-);
-console.log(rsaPublicJwk);
-// {
-//   kty: 'RSA',
-//   alg: 'RS256',
-//   kid: 'my-rsa-key',
-//   n: '...',
-//   e: 'AQAB',
-//   ext: false,
-//   key_ops: [ 'verify' ]
-// }
-```
-
-#### exportJWKToPEM(jwk, pemFormat, algForCryptoKeyImport?)
-
-Exports a JWK to a PEM-encoded string.
-
-- jwk: The JWK to export.
-- pemFormat: The desired PEM format:
-  - "pkcs8": For private keys in PKCS#8 format.
-  - "spki": For public keys in SPKI format.
-- algForCryptoKeyImport (optional): If the JWK does not have an 'alg' property, this algorithm hint is required to correctly convert it to a CryptoKey first. This is only needed if the JWK lacks an alg property.
-
-Returns a `Promise<string>` resolving to the PEM-encoded key string.
-
-Example:
+  if (!session.id) {
+    // No active session — create one
+    await session.update({ userId: "123", email: "user@example.com" });
+  }
 
-```ts
-import { exportJWKToPEM } from "unjwt/jwk";
-import { rsaJWK } from "./keys"; // Assuming you have JWKs in keys.ts
-
-const rsaPrivatePem = await exportJWKToPEM(rsaJWK.private, "pkcs8");
-console.log(rsaPrivatePem);
-// -----BEGIN PRIVATE KEY-----
-// MII...
-// -----END PRIVATE KEY-----
-
-const rsaPublicSpki = await exportJWKToPEM(
-  rsaJWK.public,
-  "spki",
-  "RS256", // this is required if `rsaJWK.public.alg` is undefined
-);
-console.log(rsaPublicSpki);
-// -----BEGIN PUBLIC KEY-----
-// MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQE...
-// -----END PUBLIC KEY-----
+  return { user: session.data };
+});
 ```
 
-### Adapters
-
-> [!WARNING]
-> While these adapters try to be compatible with h3's `useSession` API, the key difference is that new sessions are not automatically created when calling `useJWESession` or `useJWSSession`, marking their `id` as `undefined` until you explicitly call `session.update()`. This is to comply with various specs that do integrate JWT one (such as OAuth) where sessions are only created upon valid operations (like user authorization).
-
-#### H3 v1 (Nuxt v4, Nitro v2)
-
-The `h3v1` adapter bundles session helpers that store data inside signed or encrypted JWTs.
-
-- `useJWESession(event, config)` encrypts the session payload with the provided `secret` (password string or private/symmetric JWK). Use this when session data must remain confidential. (cookie's `httpOnly: true` by default)
-- `useJWSSession(event, config)` signs, but does not encrypt, the session payload with `config.key`. Use this when clients may read the session content but you still need tamper protection. (cookie's `httpOnly: false` by default)
-
-Both helpers expose the same API: read `session.id` / `session.data`, call `session.update()` to patch values, and `session.clear()` to invalidate the cookie. When setting `maxAge`, `exp` claim is automatically managed and validated. They also support a number of `hooks` in the config for custom logic (e.g. logging, refreshing, etc).
+#### JWS Session (signed, readable by client)
 
 ```ts
-import { defineEventHandler } from "h3";
-import { useJWESession, useJWSSession, generateJWK } from "unjwt/adapters/h3v1";
-
-const keys = await generateJWK("RS256"); // Make sure to persist these keys somewhere!
-
-export default defineEventHandler(async (event) => {
-  const privateSession = await useJWESession(event, {
-    name: "app-session",
-    secret: process.env.SESSION_SECRET!, // or symmetric or asymmetric keypair
-  });
+import { useJWSSession, generateJWK } from "unjwt/adapters/h3v2";
 
-  await privateSession.update((data) => ({
-    visits: (data.visits ?? 0) + 1,
-  }));
+const keys = await generateJWK("RS256"); // persist these!
 
-  const publicSession = await useJWSSession(event, {
-    name: "app-session-public",
-    key: keys, // you can directly pass symmetric or asymmetric keypairs
-    maxAge: 60 * 60, // seconds
+app.get("/preferences", async (event) => {
+  const session = await useJWSSession(event, {
+    key: keys,
+    maxAge: "24h",
   });
 
-  return {
-    encryptedSession: privateSession.data,
-    signedSession: publicSession.data,
-  };
+  return { theme: session.data.theme };
 });
 ```
 
-#### H3 v2 (Nuxt v5, Nitro v3)
+#### Session features
 
-The `h3v2` adapter bundles session helpers that store data inside signed or encrypted JWTs.
+- **Cookie chunking** — large tokens are automatically split across multiple cookies
+- **Header-based tokens** — read from `Authorization: Bearer <token>` or custom headers via `sessionHeader`
+- **Lifecycle hooks** — `onRead`, `onUpdate`, `onClear`, `onExpire`, `onError` for logging, refresh logic, etc.
+- **Key lookup hooks** — `onUnsealKeyLookup` (JWE) / `onVerifyKeyLookup` (JWS) for key rotation
+- **TypeScript generics** — strongly-typed session data via `useJWESession<MyData>(event, config)`
 
-- `useJWESession(event, config)` encrypts the session payload with the provided `secret` (password string or private/symmetric JWK). Use this when session data must remain confidential. (cookie's `httpOnly: true` by default)
-- `useJWSSession(event, config)` signs, but does not encrypt, the session payload with `config.key`. Use this when clients may read the session content but you still need tamper protection. (cookie's `httpOnly: false` by default)
-
-Both helpers expose the same API: read `session.id` / `session.data`, call `session.update()` to patch values, and `session.clear()` to invalidate the cookie. When setting `maxAge`, `exp` claim is automatically managed and validated. They also support a number of `hooks` in the config for custom logic (e.g. logging, refreshing, etc).
+#### Refresh token pattern
 
 ```ts
-import { H3, HTTPError, serve } from "h3v2";
-
 import {
   type SessionConfigJWE,
   type SessionConfigJWS,
@@ -668,112 +225,31 @@ import {
   generateJWK,
 } from "unjwt/adapters/h3v2";
 
-const atJwk = await generateJWK("RS256"); // Make sure to persist these keys somewhere!
+const atKeys = await generateJWK("RS256");
 
-const jweOptions = {
-  key: "refresh_token_secret",
+const refreshConfig = {
+  key: process.env.REFRESH_SECRET!,
   name: "refresh_token",
 } satisfies SessionConfigJWE;
 
-const jwsOptions = {
-  key: atJwk,
+const accessConfig = {
+  key: atKeys,
   name: "access_token",
-  maxAge: 15 * 60, // 15 minutes
+  maxAge: "15m",
   hooks: {
     async onExpire({ event, config }) {
-      const refreshSession = await getJWESession(event, jweOptions);
-      if (!refreshSession.data.sub) {
-        // no valid refresh session, nothing to do
-        return;
+      const refresh = await getJWESession(event, refreshConfig);
+      if (refresh.data.sub) {
+        await updateJWSSession(event, config, {
+          sub: refresh.data.sub,
+          scope: refresh.data.scope,
+        });
       }
-
-      console.log("Access token expired, refreshing...");
-
-      // refresh the access token
-      await updateJWSSession(event, config, {
-        sub: refreshSession.data.sub,
-        scope: refreshSession.data.scope,
-      });
     },
   },
 } satisfies SessionConfigJWS;
-
-const app = new H3();
-
-app.post("/login", async (event) => {
-  const refreshSession = await useJWESession(event, jweOptions);
-  const accessSession = await useJWSSession(event, jwsOptions);
-
-  if (accessSession.data.sub) {
-    // user already logged in, return existing info
-    return {
-      accessToken: {
-        id: accessSession.id,
-        createdAt: accessSession.createdAt,
-        expiresAt: accessSession.expiresAt,
-        data: accessSession.data,
-      },
-      refreshSession: {
-        id: refreshSession.id,
-        createdAt: refreshSession.createdAt,
-        expiresAt: refreshSession.expiresAt,
-        data: refreshSession.data,
-      },
-    };
-  }
-
-  const data = (await event.req.json()) as {
-    username?: string;
-    password?: string;
-  };
-
-  if (!data.username || !data.password) {
-    throw new HTTPError("Username and password are required", { status: 400 });
-  }
-
-  // validate user credentials here
-
-  const claims = {
-    sub: data.username,
-    scope: ["read:profile"],
-  };
-
-  await accessSession.update(claims);
-
-  await refreshSession.update(claims);
-
-  return {
-    accessToken: {
-      id: accessSession.id,
-      createdAt: accessSession.createdAt,
-      expiresAt: accessSession.expiresAt,
-      data: accessSession.data,
-    },
-    refreshSession: {
-      id: refreshSession.id,
-      createdAt: refreshSession.createdAt,
-      expiresAt: refreshSession.expiresAt,
-      data: refreshSession.data,
-    },
-  };
-});
-
-serve(app);
 ```
 
----
-
-### Utility Functions
-
-`unjwt/utils` exports several helpful functions:
-
-- `base64UrlEncode(data: Uint8Array | string): string`
-- `base64UrlDecode(str?: string, toString?: boolean): Uint8Array | string` (Decodes to string by default, or `Uint8Array` if `toString` is `false`)
-- `randomBytes(length: number): Uint8Array`
-- `textEncoder: TextEncoder`
-- `textDecoder: TextDecoder`
-- Type guards: `isJWK(key)`, `isCryptoKey(key)`, `isCryptoKeyPair(keyPair)`
-
 ## Development
 
 <details>
@@ -784,7 +260,7 @@ serve(app);
 - Install latest LTS version of [Node.js](https://nodejs.org/en/)
 - Enable [Corepack](https://github.com/nodejs/corepack) using `corepack enable`
 - Install dependencies using `pnpm install`
-- Run interactive tests using `pnpm dev`
+- Run tests using `pnpm test`
 
 </details>