unjwt 0.5.20 → 0.5.21

package/README.md

@@ -14,6 +14,21 @@ A collection of low-level JWT ([RFC 7519](https://datatracker.ietf.org/doc/html/
 - **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 (Nuxt, Nitro)](./src/adapters/h3.ts): `useJWSSession()`, `useJWESession()`
+
+## Table of Contents
+
+- [Usage](#usage)
+  - [Adapters](#adapters)
+  - [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)
+- [Development](#development)
+- [Credits](#credits)
+- [License](#license)
+
 ## Usage
 
 Install the package:
@@ -585,6 +600,46 @@ console.log(rsaPublicSpki);
 // -----END PUBLIC KEY-----
 ```
 
+### Adapters
+
+#### H3 (Nuxt, Nitro)
+
+The `h3` 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.
+
+```ts
+import { defineEventHandler } from "h3";
+import { useJWESession, useJWSSession, generateJWK } from "unjwt/adapters/h3";
+
+const keys = await generateJWK("RS256");
+
+export default defineEventHandler(async (event) => {
+  const privateSession = await useJWESession(event, {
+    name: "app-session",
+    secret: process.env.SESSION_SECRET!, // or symmetric or asymmetric keypair
+  });
+
+  await privateSession.update((data) => ({
+    visits: (data.visits ?? 0) + 1,
+  }));
+
+  const publicSession = await useJWSSession(event, {
+    name: "app-session-public",
+    key: keys, // you can directly pass symmetric or asymmetric keypairs
+    maxAge: 60 * 60, // seconds
+  });
+
+  return {
+    encryptedSession: privateSession.data,
+    signedSession: publicSession.data,
+  };
+});
+```
+
 ---
 
 ### Utility Functions

package/dist/h3.d.mts

@@ -0,0 +1,185 @@
+import { b as JWEEncryptOptions } from './shared/unjwt.9mL1vSFP.mjs';
+export { d as JWEDecryptOptions, e as JWEDecryptResult, J as JWEHeaderParameters, c as JWEKeyLookupFunction, a as JWEKeyManagementHeaderParameters } from './shared/unjwt.9mL1vSFP.mjs';
+import { X as JWTClaims, r as JWK_Symmetric, u as JWK_Private, t as JWK_Public, Z as JWTClaimValidationOptions, w as JWKSet } from './shared/unjwt.CtHrClHc.mjs';
+export { C as CompositeKey, f as ContentEncryptionAlgorithm, D as DeriveKeyOptions, e as DeriveKeyReturn, c as GenerateJWKOptions, d as GenerateJWKReturn, G as GenerateKeyAlgorithm, a as GenerateKeyOptions, b as GenerateKeyReturn, v as JWK, S as JWKAlgorithm, T as JWKPEMAlgorithm, J as JWKParameters, I as JWK_AES_CBC_HMAC, L as JWK_AES_GCM, H as JWK_AES_GCM_KW, F as JWK_AES_KW, s as JWK_Asymmetric, R as JWK_Asymmetric_Algorithm, j as JWK_EC, O as JWK_ECDH_ES, A as JWK_ECDSA, i as JWK_EC_Private, h as JWK_EC_Public, x as JWK_HMAC, p as JWK_OKP, o as JWK_OKP_Private, n as JWK_OKP_Public, P as JWK_OKP_SIGN, N as JWK_PBES2, m as JWK_RSA, B as JWK_RSA_ENC, z as JWK_RSA_PSS, l as JWK_RSA_Private, k as JWK_RSA_Public, y as JWK_RSA_SIGN, Q as JWK_Symmetric_Algorithm, q as JWK_oct, Y as JWT, V as JoseHeaderParameters, K as KeyManagementAlgorithm, U as UnwrapKeyOptions, W as WrapKeyOptions, g as WrapKeyResult } from './shared/unjwt.CtHrClHc.mjs';
+import { CookieSerializeOptions } from 'cookie-es';
+import { H3Event } from 'h3';
+import { c as JWSSignOptions } from './shared/unjwt.BsLgL0DQ.mjs';
+export { d as deriveJWKFromPassword, e as exportJWKToPEM, g as generateJWK, i as importJWKFromPEM } from './shared/unjwt.BjP_dGnX.mjs';
+
+/**
+ * This is a fork of h3 library's session utility functions.
+ * @source https://github.com/h3js/h3/blob/b4dce71c256911335f3402d09f30ffad120ad61a/test/session.test.ts
+ * @license MIT https://github.com/h3js/h3/blob/b4dce71c256911335f3402d09f30ffad120ad61a/LICENSE
+ */
+
+type SessionDataT$1 = Omit<JWTClaims, "jti" | "iat" | "exp">;
+type SessionData<T extends SessionDataT$1 = SessionDataT$1> = T;
+declare const kGetSessionPromise$1: unique symbol;
+interface SessionJWE<T extends SessionDataT$1 = SessionDataT$1> {
+    id: string;
+    createdAt: number;
+    expiresAt?: number;
+    data: SessionData<T>;
+    [kGetSessionPromise$1]?: Promise<SessionJWE<T>>;
+}
+interface SessionManager<T extends SessionDataT$1 = SessionDataT$1> {
+    readonly id: string | undefined;
+    readonly createdAt: number;
+    readonly expiresAt: number | undefined;
+    readonly data: SessionData<T>;
+    update: (update: SessionUpdate$1<T>) => Promise<SessionManager<T>>;
+    clear: () => Promise<SessionManager<T>>;
+}
+interface SessionJWEConfig {
+    /** Shared secret used, string for PBES2 or Json Web Key (JWK) */
+    secret: string | JWK_Symmetric | {
+        privateKey: JWK_Private | JWK_Symmetric;
+        publicKey?: JWK_Public;
+    };
+    /** Session lifetime in seconds (used to derive exp from iat) */
+    maxAge?: number;
+    /** Default is "h3" */
+    name?: string;
+    /** Default is secure, httpOnly, path="/" */
+    cookie?: false | CookieSerializeOptions;
+    /** Default is x-h3-session / x-{name}-session */
+    sessionHeader?: false | string;
+    /** Optional WebCrypto implementation override */
+    crypto?: Crypto;
+    /** Default is crypto.randomUUID */
+    generateId?: () => string;
+    /** JWE configuration overrides */
+    jwe?: {
+        encryptOptions?: Omit<JWEEncryptOptions, "expiresIn">;
+        decryptOptions?: JWTClaimValidationOptions;
+    };
+}
+type CompatEvent$1 = {
+    request: {
+        headers: Headers;
+    };
+    context: any;
+} | {
+    headers: Headers;
+    context: any;
+};
+type SessionUpdate$1<T extends SessionDataT$1 = SessionDataT$1> = Partial<SessionData<T>> | ((oldData: SessionData<T>) => Partial<SessionData<T>> | undefined);
+/**
+ * Create a session manager for the current request.
+ */
+declare function useJWESession<T extends SessionDataT$1 = SessionDataT$1>(event: H3Event | CompatEvent$1, config: SessionJWEConfig): Promise<SessionManager<T>>;
+/**
+ * Get (and lazily initialize) the session for the current request.
+ */
+declare function getJWESession<T extends SessionDataT$1 = SessionDataT$1>(event: H3Event | CompatEvent$1, config: SessionJWEConfig): Promise<SessionJWE<T>>;
+/**
+ * Update the session (optionally mutating the session data) and re-issue the JWE token.
+ */
+declare function updateJWESession<T extends SessionDataT$1 = SessionDataT$1>(event: H3Event, config: SessionJWEConfig, update?: SessionUpdate$1<T>): Promise<SessionJWE<T>>;
+/**
+ * Produce a JWE for the current session.
+ * Payload structure:
+ * {
+ *   jti: string;
+ *   iat: number; (seconds)
+ *   exp?: number; (seconds)
+ *   data: Record<string, any>;
+ * }
+ */
+declare function sealJWESession<T extends SessionDataT$1 = SessionDataT$1>(event: H3Event | CompatEvent$1, config: SessionJWEConfig): Promise<string>;
+/**
+ * Decrypt the JWE and return a Session-compatible object.
+ */
+declare function unsealJWESession(_event: H3Event | CompatEvent$1, config: SessionJWEConfig, sealed: string): Promise<Partial<SessionJWE>>;
+/**
+ * Clear the session (delete from context and drop cookie).
+ */
+declare function clearJWESession(event: H3Event, config: Partial<SessionJWEConfig>): Promise<void>;
+
+/**
+ * This is a fork of h3 library's session utility functions.
+ * @source https://github.com/h3js/h3/blob/b4dce71c256911335f3402d09f30ffad120ad61a/test/session.test.ts
+ * @license MIT https://github.com/h3js/h3/blob/b4dce71c256911335f3402d09f30ffad120ad61a/LICENSE
+ */
+
+type SessionDataT = Omit<JWTClaims, "jti" | "iat" | "exp">;
+declare const kGetSessionPromise: unique symbol;
+interface SessionJWS<T extends SessionDataT = SessionDataT> {
+    id: string;
+    createdAt: number;
+    expiresAt?: number;
+    data: SessionData<T>;
+    [kGetSessionPromise]?: Promise<SessionJWS<T>>;
+}
+interface SessionJWSConfig {
+    /**
+     * JWK (private for signing with RS/ES/PS, or symmetric oct) used for signing.
+     */
+    key: JWK_Symmetric | {
+        privateKey: JWK_Private;
+        publicKey: JWK_Public | JWK_Public[] | JWKSet;
+    };
+    /** Session lifetime in seconds (sets exp = iat + maxAge) */
+    maxAge?: number;
+    /** Default cookie / header name base */
+    name?: string;
+    /** Cookie options (false to disable cookies) */
+    cookie?: false | CookieSerializeOptions;
+    /** Custom header (false to disable header lookup) */
+    sessionHeader?: false | string;
+    /** Provide a custom WebCrypto (if needed for algorithm operations) */
+    crypto?: Crypto;
+    /** Custom ID generator (defaults to crypto.randomUUID) */
+    generateId?: () => string;
+    /** JWS customization */
+    jws?: {
+        signOptions?: Omit<JWSSignOptions, "expiresIn">;
+        verifyOptions?: JWTClaimValidationOptions;
+    };
+}
+type CompatEvent = {
+    request: {
+        headers: Headers;
+    };
+    context: any;
+} | {
+    headers: Headers;
+    context: any;
+};
+type SessionUpdate<T extends SessionDataT = SessionDataT> = Partial<SessionData<T>> | ((oldData: SessionData<T>) => Partial<SessionData<T>> | undefined);
+/**
+ * Create a session manager for the current request using JWS (signed only, not encrypted).
+ * NOTE: Contents are visible to clients (Base64URL-decoded JSON). Do not store secrets in session data.
+ */
+declare function useJWSSession<T extends SessionDataT = SessionDataT>(event: H3Event | CompatEvent, config: SessionJWSConfig): Promise<SessionManager<T>>;
+/**
+ * Retrieve (and lazily initialize) the session.
+ */
+declare function getJWSSession<T extends SessionDataT = SessionDataT>(event: H3Event | CompatEvent, config: SessionJWSConfig): Promise<SessionJWS<T>>;
+/**
+ * Update session data (if provided) and reissue JWS.
+ */
+declare function updateJWSSession<T extends SessionDataT = SessionDataT>(event: H3Event, config: SessionJWSConfig, update?: SessionUpdate<T>): Promise<SessionJWS<T>>;
+/**
+ * Sign current session as a compact JWS.
+ * Payload claims:
+ *  jti, iat, exp?, data, plus optional extraClaims (cannot override reserved)
+ */
+declare function signJWSSession<T extends SessionDataT = SessionDataT>(event: H3Event | CompatEvent, config: SessionJWSConfig): Promise<string>;
+/**
+ * Verify and parse a compact JWS into a Session structure.
+ * Performs:
+ *  - cryptographic signature verification
+ *  - (optional) standard claim checks if validateJWT true
+ *  - ensures jti & iat presence
+ *  - enforces maxAge if provided
+ */
+declare function verifyJWSSession(_event: H3Event | CompatEvent, config: SessionJWSConfig, token: string): Promise<Partial<SessionJWS>>;
+/**
+ * Destroy the session (context + cookie).
+ */
+declare function clearJWSSession(event: H3Event, config: Partial<SessionJWSConfig>): Promise<void>;
+
+export { JWEEncryptOptions, JWKSet, JWK_Private, JWK_Public, JWK_Symmetric, JWTClaimValidationOptions, JWTClaims, clearJWESession, clearJWSSession, getJWESession, getJWSSession, sealJWESession, signJWSSession, unsealJWESession, updateJWESession, updateJWSSession, useJWESession, useJWSSession, verifyJWSSession };
+export type { SessionData, SessionJWE, SessionJWEConfig, SessionJWS, SessionJWSConfig, SessionManager };