unjwt 0.8.2 → 0.8.4

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

@@ -39,7 +39,7 @@ interface SessionBaseConfig<MaxAge extends ExpiresIn | undefined = ExpiresIn | u
    *   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;
+   * A read that cannot write (a read-only event, 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.
@@ -124,63 +124,59 @@ export type OpenedSessionState<T extends SessionRecord, MaxAge extends ExpiresIn
   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> {
+export interface SessionDefinition<T extends SessionRecord = SessionClaims, MaxAge extends ExpiresIn | undefined = ExpiresIn | undefined, TEvent = 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>>;
+  use: (event: TEvent) => Promise<SessionManager<T, MaxAge>>;
   /** The token the request carries (this response's own write first), unopened. */
-  token: (context: TContext) => string | undefined;
+  token: (event: TEvent) => 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;
+interface SessionRequestBase {
   /** 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`. */
+  /** Per-request state shared with the framework, where `sessions` is kept; without it state is keyed on `req`, else on this object. */
   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 {
+/** A request event: by its `Request`, or by its `Headers` (a `Request` itself, a WebSocket upgrade's request). */
+export type SessionRequestEvent = SessionRequestBase & ({
+  readonly req: Request;
+  readonly headers?: Headers;
+} | {
   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>;
-}
+  readonly req?: Request;
+});
 /** A token handed in directly; sending a re-issued one is the caller's job. */
-export interface SessionToken {
+export interface SessionHandedToken {
   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;
+/** What the Web session driver takes: a request event, or a token in hand. */
+export type WebSessionEvent = SessionRequestEvent | SessionHandedToken;
 /** 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). */
+  /** Absent when this event cannot take a `Set-Cookie` (a request without a response). */
   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> {
+export interface SessionDriver<TEvent> {
   /** 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;
+  state(event: TEvent): Record<string, unknown>;
+  header(event: TEvent, name: string): string | null | undefined;
+  cookies(event: TEvent): 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): {
+  writable?(event: TEvent): boolean;
+  /** A token the event carries directly, when it does: no cookie or header is consulted. */
+  handed?(event: TEvent): {
     token: string | undefined;
   } | undefined;
 }

package/dist/_chunks/_codec-jws.mjs

@@ -1,6 +1,6 @@
 import { sanitizeObjectCopy } from "./libs/unsecure.mjs";
 import { JWTError, computeDurationInSeconds, expiredClaimMessage, isCryptoKey, isJWK, isJWKSet, isJWTError, isPlainObject, isPrivateJWK, isPublicJWK, isSymmetricJWK } from "./_jwt-internal.mjs";
-import { importKey, quoteTokenValue } from "./jwk.mjs";
+import { importKey, quoteTokenValue } from "./_import-key.mjs";
 import { sign, verify } from "./jws.mjs";
 import { decrypt, encrypt } from "./jwe.mjs";
 const RESERVED_CLAIMS = [
@@ -46,8 +46,8 @@ function rethrowAsInvalidToken(error, options) {
 const TOKEN = /^[!#$%&'*+\-.^_`|~\w]+$/;
 const CHUNK_SUFFIX = /\.\d+$/;
 function assertSessionName(name, options) {
-	if (!isToken(name)) throw invalidConfigError(`${options.prefix} Session "name" must be a cookie name (RFC 6265 §4.1.1): letters, digits and !#$%&'*+-.^_\`|~ only. Got ${quoteTokenValue(name)}.`);
-	if (CHUNK_SUFFIX.test(name)) throw invalidConfigError(`${options.prefix} Session "name" cannot end in a dot and digits: ${quoteTokenValue(name)} is the cookie holding a chunk of the session named ${quoteTokenValue(name.replace(CHUNK_SUFFIX, ""))}.`);
+	if (!isToken(name)) throw invalidConfigError(`${options.prefix} Session "name" must be a valid cookie name (got ${quoteTokenValue(name)}).`);
+	if (CHUNK_SUFFIX.test(name)) throw invalidConfigError(`${options.prefix} Session "name" ${quoteTokenValue(name)} cannot end in a dot and digits.`);
 }
 function isToken(value) {
 	return typeof value === "string" && TOKEN.test(value);
@@ -57,7 +57,7 @@ function assertCookiePrefix(name, attrs, options) {
 	const host = lower.startsWith("__host-");
 	if (!host && !lower.startsWith("__secure-")) return;
 	const rule = host ? "\"__Host-\" cookie must be Secure, with Path=/ and no Domain" : "\"__Secure-\" cookie must be Secure";
-	if (attrs.secure === false || host && (attrs.domain !== void 0 || attrs.path !== void 0 && attrs.path !== "/")) throw invalidConfigError(`${options.prefix} Session ${quoteTokenValue(name)}: a ${rule} (RFC 6265bis §4.1.3).`);
+	if (attrs.secure === false || host && (attrs.domain !== void 0 || attrs.path !== void 0 && attrs.path !== "/")) throw invalidConfigError(`${options.prefix} Session ${quoteTokenValue(name)}: a ${rule}.`);
 }
 function assertRolling(config, options) {
 	const { rolling } = config;
@@ -65,10 +65,10 @@ function assertRolling(config, options) {
 	if (config.maxAge === void 0) throw invalidConfigError(`${options.prefix} "rolling" needs a "maxAge" to extend.`);
 	if (rolling === true) return;
 	if (!isExpiresIn(rolling)) throw new JWTError(`${options.prefix} "rolling" must be true or a duration.`, "ERR_INVALID_OPTION");
-	if (computeDurationInSeconds(rolling) >= computeDurationInSeconds(config.maxAge)) throw invalidConfigError(`${options.prefix} "rolling" must be shorter than "maxAge": the session would expire before it rolls.`);
+	if (computeDurationInSeconds(rolling) >= computeDurationInSeconds(config.maxAge)) throw invalidConfigError(`${options.prefix} "rolling" must be shorter than "maxAge".`);
 }
 function assertKeyMaterial(key, options) {
-	if (typeof key === "string") throw invalidKeyError(`${options.prefix} Session "key" must be a JWK or a CryptoKey, not a password string. Derive one once with deriveJWKFromPassword() and pass the result.`);
+	if (typeof key === "string") throw invalidKeyError(`${options.prefix} Session "key" cannot be a string, use deriveJWKFromPassword().`);
 	if (!key) throw invalidKeyError(`${options.prefix} Session "key" is required.`);
 }
 async function assertImportableKey(key, options) {
@@ -109,7 +109,7 @@ function sessionRequiredClaims(configured, options) {
 	return [...required];
 }
 function sanitizeSessionUpdate(update, options) {
-	if (!isPlainObject(update)) throw new JWTError(`${options.prefix} Session data must be a plain object, got ${Array.isArray(update) ? "an array" : typeof update}.`, "ERR_INVALID_OPTION");
+	if (!isPlainObject(update)) throw new JWTError(`${options.prefix} Session data must be a plain object.`, "ERR_INVALID_OPTION");
 	const sanitized = Object.create(null);
 	for (const key of Object.keys(update)) {
 		if (FORBIDDEN_KEYS.includes(key)) throw new JWTError(`${options.prefix} Session data cannot carry the key "${key}".`, "ERR_INVALID_OPTION");
@@ -205,7 +205,7 @@ function assertKeyPair(pair, options) {
 	if (!options.isPublic(pair.publicKey)) throw invalidKeyError(`${prefix} Invalid ${family} key: "publicKey" must be ${options.publicHalf}.`, pair);
 }
 function assertPinnedCryptoKey(key, options) {
-	if (isCryptoKey(key) && !options.pinned) throw invalidConfigError(`${options.prefix} A CryptoKey session key carries no algorithm: set ${options.hint}.`);
+	if (isCryptoKey(key) && !options.pinned) throw invalidConfigError(`${options.prefix} A CryptoKey session key carries no algorithm, set ${options.hint}.`);
 }
 function sessionPayload(state) {
 	const iat = Math.floor(state.createdAt / 1e3);
@@ -219,7 +219,7 @@ function sessionPayload(state) {
 }
 function assertNotFromTheFuture(payload, options) {
 	const tolerance = options.clockTolerance === void 0 ? 0 : computeDurationInSeconds(options.clockTolerance);
-	if (payload.iat > Math.floor(options.now / 1e3) + tolerance) throw invalidTokenError(`${options.prefix} Invalid session token: issued in the future (iat: ${(/* @__PURE__ */ new Date(payload.iat * 1e3)).toISOString()}).`);
+	if (payload.iat > Math.floor(options.now / 1e3) + tolerance) throw invalidTokenError(`${options.prefix} Invalid session token: "iat" is in the future (${(/* @__PURE__ */ new Date(payload.iat * 1e3)).toISOString()}).`);
 }
 function openedSession(payload) {
 	const data = Object.create(null);
@@ -294,7 +294,7 @@ function getEncryptKey(config, prefix) {
 		assertJWEKeyPair(key, prefix);
 		resolved = key.publicKey;
 	}
-	if (!resolved) throw invalidKeyError(`${prefix} Invalid JWE key. It must be a JWK or a CryptoKey.`, key);
+	if (!resolved) throw invalidKeyError(`${prefix} Invalid JWE key, expected a JWK or a CryptoKey.`, key);
 	assertPinnedAlgEnc(resolved, config, prefix);
 	return resolved;
 }
@@ -307,7 +307,7 @@ function getDecryptKey(config, prefix) {
 		assertJWEKeyPair(key, prefix);
 		resolved = key.privateKey;
 	}
-	if (!resolved) throw invalidKeyError(`${prefix} Invalid JWE key. It must be a JWK, a private JWK, or a CryptoKey.`, key);
+	if (!resolved) throw invalidKeyError(`${prefix} Invalid JWE key, expected a JWK, a private JWK or a CryptoKey.`, key);
 	assertPinnedAlgEnc(resolved, config, prefix);
 	return resolved;
 }
@@ -409,21 +409,21 @@ function decodeValue(value) {
 		return value;
 	}
 }
-function resolveTransport(driver, context, options) {
-	const handed = driver.handed?.(context);
+function resolveTransport(driver, event, options) {
+	const handed = driver.handed?.(event);
 	if (handed) return {
 		read: () => handed.token,
 		readonly: false,
 		writable: () => true
 	};
 	const { config, name } = options;
-	const header = headerReader(driver, context, options);
+	const header = headerReader(driver, event, options);
 	if (config.cookie === false) return {
 		read: header,
 		readonly: false,
 		writable: () => true
 	};
-	const jar = driver.cookies(context);
+	const jar = driver.cookies(event);
 	const store = responseStore(jar);
 	const transport = {
 		read: () => {
@@ -432,7 +432,7 @@ function resolveTransport(driver, context, options) {
 			return (written ?? readChunked(jar, name)) || header?.() || void 0;
 		},
 		readonly: !store,
-		writable: () => driver.writable?.(context) ?? true
+		writable: () => driver.writable?.(event) ?? true
 	};
 	if (!store) return transport;
 	transport.write = (token, { attrs, chunkMaxLength }) => {
@@ -448,7 +448,7 @@ function resolveTransport(driver, context, options) {
 	return transport;
 }
 function assertTokenSource(transport, options) {
-	if (!transport.read) throw invalidConfigError(`${options.prefix} Session has no token source: "cookie" and "sessionHeader" are both disabled.`);
+	if (!transport.read) throw invalidConfigError(`${options.prefix} Session has no token source, enable "cookie" or "sessionHeader".`);
 }
 function assertWritable(transport, options) {
 	const { operation, prefix } = options;
@@ -458,7 +458,7 @@ function assertWritable(transport, options) {
 function assertSessionHeader(header, options) {
 	if (header === void 0 || typeof header === "boolean") return;
 	if (isToken(header)) return;
-	throw invalidConfigError(`${options.prefix} Session "sessionHeader" must be true, false or a header name: letters, digits and !#$%&'*+-.^_\`|~ only. Got ${quoteTokenValue(header)}.`);
+	throw invalidConfigError(`${options.prefix} Session "sessionHeader" must be true, false or a header name (got ${quoteTokenValue(header)}).`);
 }
 function sessionHeaderName(sessionName, configured) {
 	if (typeof configured === "string") return configured.toLowerCase();
@@ -471,11 +471,11 @@ function headerToken(value) {
 	if (/^bearer$/i.test(first)) return words.length === 2 ? second : void 0;
 	return words.length === 1 && first ? first : void 0;
 }
-function headerReader(driver, context, options) {
+function headerReader(driver, event, options) {
 	const { config, name } = options;
 	if (config.sessionHeader === false) return void 0;
 	const header = sessionHeaderName(name, config.sessionHeader);
-	return () => headerToken(driver.header(context, header));
+	return () => headerToken(driver.header(event, header));
 }
 function responseStore(jar) {
 	const write = jar.write?.bind(jar);
@@ -486,7 +486,7 @@ function responseStore(jar) {
 	};
 }
 const kSessionNames = Symbol("unjwt_session_names");
-function bindSession(context, config, options) {
+function bindSession(event, config, options) {
 	const { driver, codec, actions, hookArgs } = options;
 	const { prefix } = driver;
 	const name = config.name || codec.defaultName;
@@ -497,22 +497,22 @@ function bindSession(context, config, options) {
 		...config.cookie
 	}, { prefix });
 	assertRolling(config, { prefix });
-	const record = driver.state(context);
+	const record = driver.state(event);
 	claimSessionName(record, {
 		name,
 		family: codec.family,
 		prefix
 	});
 	return {
-		context,
+		event,
 		config,
 		driver,
 		codec,
 		actions,
 		name,
-		args: hookArgs(context),
+		args: hookArgs(event),
 		store: recordSlotStore(record, `${codec.family}:${name}`),
-		transport: resolveTransport(driver, context, {
+		transport: resolveTransport(driver, event, {
 			config,
 			name
 		})
@@ -561,7 +561,7 @@ function claimSessionName(record, options) {
 		return;
 	}
 	if (held === family) return;
-	throw invalidConfigError(`${prefix} Session name "${name}" is already used by a ${held.toUpperCase()} session on this request; a name is one cookie, so give this session a "name" of its own.`);
+	throw invalidConfigError(`${prefix} Session name "${name}" is already used by a ${held.toUpperCase()} session on this request.`);
 }
 const kSessionPending = Symbol("unjwt_session_pending");
 function sessionInstant(source) {
@@ -828,19 +828,19 @@ function snapshotSession(session) {
 function defineSession(config, options) {
 	const { driver, codec, hookArgs } = options;
 	const actions = sessionActions();
-	const bind = (context) => bindSession(context, config, {
+	const bind = (event) => bindSession(event, config, {
 		driver,
 		codec,
 		actions,
 		hookArgs
 	});
 	return {
-		use: async (context) => {
-			const binding = bind(context);
+		use: async (event) => {
+			const binding = bind(event);
 			await loadSession(binding);
 			return sessionManager(binding);
 		},
-		token: (context) => sessionToken(bind(context)),
+		token: (event) => sessionToken(bind(event)),
 		issue: async (data, issueOptions) => {
 			await codec.assertKeys(config);
 			const issue = codec.issuer(config);
@@ -914,7 +914,7 @@ function getSignKey(config, prefix) {
 		assertJWSKeyPair(key, prefix);
 		resolved = key.privateKey;
 	}
-	if (!resolved) throw invalidKeyError(`${prefix} Invalid JWS key. It must be a symmetric JWK, a private JWK, or a CryptoKey.`, key);
+	if (!resolved) throw invalidKeyError(`${prefix} Invalid JWS key, expected a symmetric JWK, a private JWK or a CryptoKey.`, key);
 	assertPinnedAlg(resolved, config, prefix);
 	return resolved;
 }
@@ -927,7 +927,7 @@ function getVerifyKey(config, prefix) {
 		assertJWSKeyPair(key, prefix);
 		resolved = Array.isArray(key.publicKey) ? { keys: key.publicKey } : key.publicKey;
 	}
-	if (!resolved) throw invalidKeyError(`${prefix} Invalid JWS key. It must be a symmetric JWK, a public JWK/set, or a CryptoKey.`, key);
+	if (!resolved) throw invalidKeyError(`${prefix} Invalid JWS key, expected a symmetric JWK, a public JWK/set or a CryptoKey.`, key);
 	assertPinnedAlg(resolved, config, prefix);
 	return resolved;
 }
@@ -936,7 +936,7 @@ function assertJWSKeyPair(key, prefix) {
 		prefix,
 		family: "JWS",
 		isPublic: (half) => isCryptoKey(half) || isPublicJWK(half) || isPublicKeyList(Array.isArray(half) ? half : isJWKSet(half) ? half.keys : void 0),
-		publicHalf: "a public JWK, a non-empty list or set of public JWKs, or a CryptoKey"
+		publicHalf: "a public JWK, a non-empty JWK set or a CryptoKey"
 	});
 }
 function isPublicKeyList(keys) {