unjwt 0.8.5 → 0.9.1

package/README.md

@@ -8,13 +8,14 @@ A collection of JWT utilities based on the Web Crypto API, in a single zero-depe
 
 ## Features
 
-- **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.
-- **DPoP** ([RFC 9449](https://www.rfc-editor.org/rfc/rfc9449)) — create and verify proofs through the optional [`unjwt/dpop`](https://unjwt.s94.dev/dpop) module. Your application owns HTTP and replay storage.
-- **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`, `elysia`).
+- **JWS** ([RFC 7515](https://www.rfc-editor.org/rfc/rfc7515)): HMAC, RSA, RSA-PSS, ECDSA, EdDSA. Compact and General/Flattened JSON serialization (several signatures over one payload).
+- **JWE** ([RFC 7516](https://www.rfc-editor.org/rfc/rfc7516)): `dir`, AES-KW, AES-GCM-KW, RSA-OAEP, PBES2, ECDH-ES, with AES-GCM and AES-CBC-HMAC-SHA2 content encryption. Compact and General/Flattened JSON serialization (several recipients for one ciphertext).
+- **JWK** ([RFC 7517](https://www.rfc-editor.org/rfc/rfc7517)): generate, import, export, wrap and unwrap keys; `CryptoKey`, JWK and PEM conversion; thumbprints as key IDs; JWK Set lookup and rotation.
+- **DPoP** ([RFC 9449](https://www.rfc-editor.org/rfc/rfc9449)): create and verify proofs with [`unjwt/dpop`](https://unjwt.s94.dev/dpop). Your application owns HTTP and replay storage.
+- **Sessions**: signed or encrypted cookie sessions with [`unjwt/session`](https://unjwt.s94.dev/sessions) over a Web `Request`, on [h3](https://unjwt.s94.dev/examples/h3), [Nitro](https://unjwt.s94.dev/examples/nitro), [Nuxt](https://unjwt.s94.dev/examples/nuxt), [Hono and Workers](https://unjwt.s94.dev/examples/hono), Bun and Deno, or on a token in hand; a [driver](https://unjwt.s94.dev/sessions/drivers) for any other framework.
+- **One typed error**: every failure is a `JWTError` with a `code` to branch on.
+- **Runtime-agnostic**: Node.js 22+, Bun, Deno, Cloudflare Workers and browsers, anywhere Web Crypto runs.
+- **Zero runtime dependencies**, no peer dependencies.
 
 ## Install
 
@@ -32,30 +33,42 @@ npx skills add sandros94/unjwt
 ## Quickstart
 
 ```ts
-// Sign and verify a JWT (JWS)
+// Sign with the private half, verify with the public one (JWS)
 import { sign, verify } from "unjwt/jws";
 import { generateJWK } from "unjwt/jwk";
 
-const key = await generateJWK("HS256");
-const token = await sign({ sub: "user_1" }, key, { expiresIn: "1h" });
-const { payload } = await verify(token, key);
-// { sub: "user_1", iat: ..., exp: ... }
+const { privateKey, publicKey } = await generateJWK("ES256");
+const token = await sign({ sub: "user_1a2b" }, privateKey, { expiresIn: "15m" });
+const { payload } = await verify(token, publicKey);
+// { sub: "user_1a2b", iat: …, exp: … }
 
-// Encrypt and decrypt (JWE)
+// Encrypt for a recipient's public key, decrypt with its private key (JWE)
 import { encrypt, decrypt } from "unjwt/jwe";
 
-const jwe = await encrypt({ secret: "data" }, "my-password");
-const { payload: p } = await decrypt(jwe, "my-password");
+const recipient = await generateJWK("ECDH-ES+A256KW");
+const jwe = await encrypt({ invoice: "inv_2026_0042" }, recipient.publicKey);
+const opened = await decrypt(jwe, recipient.privateKey);
+
+// Keep a session in a cookie on any Web Request
+import { defineJWESession } from "unjwt/session";
+
+const appSession = defineJWESession({ key: await generateJWK("A256GCM"), maxAge: "7D" });
+const headers = new Headers();
+const session = await appSession.use({ req: request, res: { headers } });
+await session.update({ user: "user_1a2b" }); // Set-Cookie lands on `headers`
 ```
 
-Full walkthroughs, recipes, and the complete API reference live at **[unjwt.s94.dev](https://unjwt.s94.dev)**:
+Walkthroughs, recipes and the full API live at **[unjwt.s94.dev](https://unjwt.s94.dev)**:
 
 - [Getting started →](https://unjwt.s94.dev/getting-started)
-- [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)
-- [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.
+- [Sign and verify (JWS) →](https://unjwt.s94.dev/jws)
+- [Encrypt and decrypt (JWE) →](https://unjwt.s94.dev/jwe)
+- [Keys (JWK) →](https://unjwt.s94.dev/jwk)
+- [Sessions →](https://unjwt.s94.dev/sessions)
+- [Safety: errors, claims and limits →](https://unjwt.s94.dev/safety)
+- [DPoP proofs →](https://unjwt.s94.dev/dpop)
+- [Recipes →](https://unjwt.s94.dev/examples): sessions on h3, Nitro, Nuxt, Hono and Workers, CDN imports, custom drivers.
+- [Migration guides →](https://unjwt.s94.dev/getting-started/migration)
 
 ## Development
 

package/dist/_chunks/algorithms.mjs

@@ -1,7 +1,8 @@
 import { safeJsonParse, sanitizeObjectCopy, textEncoder } from "./libs/unsecure.mjs";
 import { JWTError } from "../error.mjs";
-import { assertClaimValidationOptions, assertCritShape, assertCryptoKey, assertPlainObject, assertStringList, base64Parse, base64Stringify, base64UrlParse, base64UrlStringify, concatUint8Arrays, hasSymmetricSecret, isCryptoKey, isCryptoKeyPair, isJWK, isJWKSet, isPlainObject, isPublicJWK, quoteTokenValue, uint32be } from "./jwt.mjs";
-import { ECDSA_CURVES, aesBitsOf, checkKeyUsage, cryptoKeyCurve, digestUrl, hashBitsOf, inferJWSAllowedAlgorithms, innerKeyWrapAlg, isAlgorithm, isContentEncryptionAlgorithm, isECDHESAlgorithm, isPBES2Algorithm, isSameAlgorithm, jwkAlgServes, jwsHashOf, lengthOf, modulusLengthOf, namedCurveOf, pbes2HashOf, rsaOaepHashOf, shaBitsOf, unusableKey } from "./digest.mjs";
+import { assertClaimValidationOptions, assertCryptoKey, assertPlainObject, assertStringList, base64Parse, base64Stringify, base64UrlParse, base64UrlStringify, concatUint8Arrays, hasMisplacedSecret, isCryptoKey, isCryptoKeyPair, isJWK, isJWKSet, isPlainObject, isPublicJWK, uint32be } from "./jwt.mjs";
+import { assertCritShape, quoteTokenValue } from "./jwt2.mjs";
+import { ECDSA_CURVES, aesBitsOf, checkKeyUsage, cryptoKeyCurve, digestUrl, hashBitsOf, inferJWSAllowedAlgorithms, innerKeyWrapAlg, isAlgorithm, isContentEncryptionAlgorithm, isECDHESAlgorithm, isPBES2Algorithm, isSameAlgorithm, jwkAlgServes, jwkKtyServes, jwsHashOf, lengthOf, modulusLengthOf, namedCurveOf, pbes2HashOf, rsaOaepHashOf, shaBitsOf, unusableKey } from "./digest.mjs";
 function serializeProtectedHeader(header) {
 	try {
 		return JSON.stringify(header);
@@ -1242,6 +1243,7 @@ const DEFAULT_JOSE_LIMITS = /* @__PURE__ */ Object.freeze({
 	signatures: 16,
 	recipients: 16,
 	keyCandidates: 8,
+	keyAttempts: 16,
 	pbes2Iterations: 4 * DEFAULT_PBES2_ITERATIONS
 });
 function resolveLimit(limits, name) {
@@ -1258,6 +1260,23 @@ function assertCandidateLimit(count, limit) {
 	if (count <= limit) return;
 	throw new JWTError(`${count} candidate keys exceed the limit of ${limit}, narrow them with a "kid".`, "ERR_JWK_KEY_NOT_FOUND");
 }
+function createKeyAttemptBudget(limit) {
+	let remaining = limit;
+	let exhausted;
+	return {
+		get exhausted() {
+			return exhausted;
+		},
+		spend() {
+			if (remaining > 0) {
+				remaining--;
+				return;
+			}
+			exhausted ??= new JWTError(`Key attempt budget of ${limit} ("limits.keyAttempts") exhausted, narrow the keys with a "kid".`, "ERR_JWK_KEY_NOT_FOUND");
+			throw exhausted;
+		}
+	};
+}
 function assertJWKSetCandidates(candidates, options) {
 	if (candidates.length === 0) {
 		const { kid } = options;
@@ -1304,12 +1323,11 @@ const JWK_SET_KEY_OPS = /* @__PURE__ */ Object.freeze({
 function buildJWKSetFilter(header, options) {
 	const kid = header?.kid;
 	const alg = header?.alg;
-	const { op, allowSymmetric } = options;
+	const { op } = options;
 	const use = op;
 	const keyOps = JWK_SET_KEY_OPS[op];
 	return (k) => {
-		if (!isJWK(k)) return false;
-		if (!allowSymmetric && hasSymmetricSecret(k)) return false;
+		if (!isJWK(k) || hasMisplacedSecret(k)) return false;
 		if (kid && k.kid !== kid) return false;
 		if (k.alg && !(alg && jwkAlgServes({
 			kty: k.kty,
@@ -1381,7 +1399,10 @@ async function resolveKeyInput(key, options) {
 	const { header, token, what } = options;
 	let resolved;
 	try {
-		resolved = await key(header, token);
+		resolved = await key({
+			header,
+			token
+		});
 	} catch (error) {
 		throw asKeyLookupError(error, what);
 	}
@@ -1422,7 +1443,7 @@ async function importKey(key, algOrOptions) {
 		return key;
 	}
 	if (isJWK(key)) {
-		if (key.kty !== "oct" && Object.hasOwn(key, "k")) throw new JWTError(`JWK "k" is defined only for "oct" keys, not "${key.kty}".`, "ERR_JWK_INVALID");
+		if (hasMisplacedSecret(key)) throw new JWTError(`JWK "k" is defined only for "oct" keys, not "${key.kty}".`, "ERR_JWK_INVALID");
 		assertJWKAlgAuthority(key, alg);
 		if (key.kty === "oct" && typeof key.k === "string") {
 			const rawBytes = decodeSegment(key.k, {
@@ -1462,11 +1483,16 @@ async function importKey(key, algOrOptions) {
 	throw new JWTError("Invalid key type provided to importKey", "ERR_JWK_INVALID");
 }
 function assertJWKAlgAuthority(jwk, alg) {
-	if (!alg || !jwk.alg || jwkAlgServes({
-		kty: jwk.kty,
-		alg: jwk.alg
-	}, alg)) return;
-	throw new JWTError(`JWK "alg" is "${jwk.alg}" but the operation requires "${alg}".`, "ERR_JWK_INVALID");
+	if (!alg) return;
+	if (jwk.alg) {
+		if (jwkAlgServes({
+			kty: jwk.kty,
+			alg: jwk.alg
+		}, alg)) return;
+		throw new JWTError(`JWK "alg" is "${jwk.alg}" but the operation requires "${alg}".`, "ERR_JWK_INVALID");
+	}
+	if (jwkKtyServes(jwk.kty, alg)) return;
+	throw new JWTError(`JWK "kty" is "${jwk.kty}", which cannot serve "${alg}".`, "ERR_JWK_INVALID");
 }
 function assertIntentOnJWK(jwk, expect) {
 	if (expect === void 0 || jwk.kty === "oct") return;
@@ -1492,10 +1518,11 @@ const JWS_ALG_CTX = /* @__PURE__ */ Object.freeze({
 	op: "sig"
 });
 function checkAlgAllowed(alg, key, options) {
-	const { ctx, algorithms, allowSymmetric } = options;
+	const { ctx, algorithms } = options;
 	if (algorithms !== void 0) return algorithms.includes(alg) ? void 0 : notAllowed(alg, ctx);
 	if (isJWK(key) && typeof key.alg === "string" && (!ctx.octRoles || key.kty !== "oct")) return isSameAlgorithm(key.alg, alg) ? void 0 : notAllowed(alg, ctx);
-	const inferred = ctx.infer(key, { allowSymmetric });
+	if (key === void 0 || key === null) return new JWTError("A key is required.", "ERR_JWK_INVALID");
+	const inferred = ctx.infer(key);
 	if (!inferred) return new JWTError("Cannot infer allowed algorithms from this key, pass \"algorithms\".", ctx.errorCode);
 	return inferred.includes(alg) ? void 0 : notAllowed(alg, ctx);
 }
@@ -1503,12 +1530,9 @@ function notAllowed(alg, ctx) {
 	return new JWTError(`${ctx.label} not allowed: ${alg}`, ctx.errorCode);
 }
 function keyMatchesHeader(header, keyMaterial, options) {
-	const { ctx, allowSymmetric } = options;
+	const { ctx } = options;
 	if (isJWKSet(keyMaterial)) {
-		const candidates = keyMaterial.keys.filter(buildJWKSetFilter(header, {
-			op: ctx.op,
-			allowSymmetric
-		}));
+		const candidates = keyMaterial.keys.filter(buildJWKSetFilter(header, { op: ctx.op }));
 		return candidates.length === 0 || candidates.some((k) => keyServesHeaderAlg(header, k, ctx));
 	}
 	if (isJWK(keyMaterial)) return keyServesHeaderAlg(header, keyMaterial, ctx);
@@ -1538,4 +1562,4 @@ function keyServesHeaderAlg(header, key, ctx) {
 	const keyCurve = isCryptoKey(key) ? cryptoKeyCurve(key) : "crv" in key ? key.crv : void 0;
 	return !epkCurve || !keyCurve || epkCurve === keyCurve;
 }
-export { DEFAULT_JOSE_LIMITS, DEFAULT_PBES2_ITERATIONS, JWS_ALG_CTX, MAX_PARTY_INFO_BYTES, WeakMapJWKCache, aesKwUnwrap, aesKwWrap, asDecryptionError, asJWTError, asKeyLookupError, assertCompactToken, assertConsumerOptions, assertDirectKeyRole, assertECDHKeyAllowed, assertEntryLimit, assertJWEEncSupported, assertJWKSetCandidates, assertOctKeyLength, assertOptionEntry, assertPBES2Count, assertPBES2Iterations, assertPBES2Params, assertPBES2Salt, assertProducerConfirmation, assertProducerCrit, assertProducerKeyHeaders, assertProtectedOnlyOption, assertSerializationObject, bitLengthCEK, bitLengthIV, bitLengthTag, buildECDHAgreementParams, buildJWKSetFilter, checkAlgAllowed, checkAlgSupported, checkJWEEncSupported, checkProtectedTyp, checkSerializationEntry, clearJWKCache, configureJWKCache, copyJsonObject, decodeProtectedHeader, decodeSegment, decrypt, decryptRSAES, deriveECDHESKey, deriveKey, ecdhDerivedBits, ecdhesWrap, encrypt, encryptKey, encryptRSAES, fromPKCS8, fromSPKI, fromX509, gcmkwDecrypt, gcmkwEncrypt, generateCEK, generateIV, getJWKsFromSet, importKey, jwkTokey, keyMatchesHeader, keyToJWK, normalizeEpk, pbes2Unwrap, pbes2Wrap, resolveKeyInput, resolveLimit, resolvePasswordKey, serializeProtectedHeader, sign, stringKeyError, thumbprint, toPKCS8, toSPKI, verify };
+export { DEFAULT_JOSE_LIMITS, DEFAULT_PBES2_ITERATIONS, JWS_ALG_CTX, MAX_PARTY_INFO_BYTES, WeakMapJWKCache, aesKwUnwrap, aesKwWrap, asDecryptionError, asJWTError, asKeyLookupError, assertCompactToken, assertConsumerOptions, assertDirectKeyRole, assertECDHKeyAllowed, assertEntryLimit, assertJWEEncSupported, assertJWKSetCandidates, assertOctKeyLength, assertOptionEntry, assertPBES2Count, assertPBES2Iterations, assertPBES2Params, assertPBES2Salt, assertProducerConfirmation, assertProducerCrit, assertProducerKeyHeaders, assertProtectedOnlyOption, assertSerializationObject, bitLengthCEK, bitLengthIV, bitLengthTag, buildECDHAgreementParams, buildJWKSetFilter, checkAlgAllowed, checkAlgSupported, checkJWEEncSupported, checkProtectedTyp, checkSerializationEntry, clearJWKCache, configureJWKCache, copyJsonObject, createKeyAttemptBudget, decodeProtectedHeader, decodeSegment, decrypt, decryptRSAES, deriveECDHESKey, deriveKey, ecdhDerivedBits, ecdhesWrap, encrypt, encryptKey, encryptRSAES, fromPKCS8, fromSPKI, fromX509, gcmkwDecrypt, gcmkwEncrypt, generateCEK, generateIV, getJWKsFromSet, importKey, jwkTokey, keyMatchesHeader, keyToJWK, normalizeEpk, pbes2Unwrap, pbes2Wrap, resolveKeyInput, resolveLimit, resolvePasswordKey, serializeProtectedHeader, sign, stringKeyError, thumbprint, toPKCS8, toSPKI, verify };

package/dist/_chunks/digest.d.mts

@@ -1,8 +1,8 @@
-/** Hash functions the JOSE specs name for digests carried in tokens. */
+/** The hash functions the JOSE specs name for digests in token members. */
 export type DigestHash = "SHA-256" | "SHA-384" | "SHA-512";
 /**
- * The base64url digest of text or bytes, SHA-256 unless `hash` says otherwise: a DPoP `ath`
- * (RFC 9449 §4.2) over the access token, an `x5t#S256` over a certificate, the last step of a
- * JWK thumbprint. Text is digested as UTF-8.
+ * Returns the unpadded base64url digest of `data` under `hash`, `SHA-256` when omitted.
+ * A string is digested as its UTF-8 bytes.
+ * Examples: a DPoP `ath` (RFC 9449 §4.2), an `x5t#S256`, a JWK thumbprint.
  */
 export declare function digestUrl(data: string | Uint8Array<ArrayBuffer>, hash?: DigestHash): Promise<string>;

package/dist/_chunks/digest.mjs

@@ -1,6 +1,6 @@
 import { textEncoder } from "./libs/unsecure.mjs";
 import { JWTError } from "../error.mjs";
-import { base64UrlStringify, hasSymmetricSecret, isCryptoKey, isCryptoKeyPair, isJWK, isJWKSet } from "./jwt.mjs";
+import { base64UrlStringify, hasMisplacedSecret, isCryptoKey, isCryptoKeyPair, isJWK, isJWKSet } from "./jwt.mjs";
 const ECDSA_CURVES = /* @__PURE__ */ Object.freeze({
 	ES256: "P-256",
 	ES384: "P-384",
@@ -127,30 +127,29 @@ const ECDH_ES_ALGORITHM_SET = /* @__PURE__ */ new Set(ECDH_ES_ALGORITHMS);
 function isECDHESAlgorithm(alg) {
 	return ECDH_ES_ALGORITHM_SET.has(alg);
 }
-function inferJWSAllowedAlgorithms(key, options) {
+function inferJWSAllowedAlgorithms(key) {
 	if (!key || typeof key === "function") return void 0;
 	if (typeof key === "string" || key instanceof Uint8Array) return void 0;
 	if (typeof key !== "object") return void 0;
 	if (isCryptoKeyPair(key)) return inferJWSAllowedAlgorithms(key.publicKey);
-	if (isJWKSet(key)) return unionFromJWKSet(key.keys, jwsAlgsFromJWK, options);
+	if (isJWKSet(key)) return unionFromJWKSet(key.keys, jwsAlgsFromJWK);
 	if (isCryptoKey(key)) return jwsAlgsFromCryptoKey(key);
 	if (isJWK(key)) return jwsAlgsFromJWK(key);
 }
-function inferJWEAllowedAlgorithms(key, options) {
+function inferJWEAllowedAlgorithms(key) {
 	if (!key || typeof key === "function") return void 0;
 	if (typeof key === "string") return [...PBES2_ALGORITHMS];
 	if (key instanceof Uint8Array) return void 0;
 	if (typeof key !== "object") return void 0;
 	if (isCryptoKeyPair(key)) return inferJWEAllowedAlgorithms(key.privateKey);
-	if (isJWKSet(key)) return unionFromJWKSet(key.keys, jweAlgsFromJWK, options);
+	if (isJWKSet(key)) return unionFromJWKSet(key.keys, jweAlgsFromJWK);
 	if (isCryptoKey(key)) return jweAlgsFromCryptoKey(key);
 	if (isJWK(key)) return jweAlgsFromJWK(key);
 }
-function unionFromJWKSet(keys, mapper, options) {
+function unionFromJWKSet(keys, mapper) {
 	const algs = /* @__PURE__ */ new Set();
 	for (const k of keys) {
-		if (!isJWK(k)) continue;
-		if (!options?.allowSymmetric && hasSymmetricSecret(k)) continue;
+		if (!isJWK(k) || hasMisplacedSecret(k)) continue;
 		const mapped = mapper(k);
 		if (!mapped) continue;
 		for (const a of mapped) algs.add(a);
@@ -163,6 +162,15 @@ function isEd25519Signature(alg) {
 function isSameAlgorithm(a, b) {
 	return a === b || isEd25519Signature(a) && isEd25519Signature(b);
 }
+function jwkKtyServes(kty, alg) {
+	switch (kty) {
+		case "oct": return !/^(RS|PS|ES|Ed|EC)/.test(alg);
+		case "RSA": return /^(RS|PS)/.test(alg);
+		case "EC": return /^E(S|C)/.test(alg);
+		case "OKP": return /^E(d|C)/.test(alg);
+		default: return false;
+	}
+}
 function jwkAlgServes(jwk, alg) {
 	return isSameAlgorithm(jwk.alg, alg) || jwk.kty === "oct" && alg === "dir" && isContentEncryptionAlgorithm(jwk.alg);
 }
@@ -231,14 +239,14 @@ function jweAlgsFromCryptoKey(key) {
 	const length = lengthOf(key.algorithm);
 	switch (name) {
 		case "AES-KW":
-			if (length === 128) return ["A128KW", "dir"];
-			if (length === 192) return ["A192KW", "dir"];
-			if (length === 256) return ["A256KW", "dir"];
+			if (length === 128) return ["A128KW"];
+			if (length === 192) return ["A192KW"];
+			if (length === 256) return ["A256KW"];
 			return;
 		case "AES-GCM":
-			if (length === 128) return ["A128GCMKW", "dir"];
-			if (length === 192) return ["A192GCMKW", "dir"];
-			if (length === 256) return ["A256GCMKW", "dir"];
+			if (length === 128) return ["A128GCMKW"];
+			if (length === 192) return ["A192GCMKW"];
+			if (length === 256) return ["A256GCMKW"];
 			return;
 		case "RSA-OAEP":
 			if (hashName === "SHA-1") return ["RSA-OAEP"];
@@ -260,4 +268,4 @@ async function digestUrl(data, hash = "SHA-256") {
 	const bytes = typeof data === "string" ? textEncoder.encode(data) : data;
 	return base64UrlStringify(new Uint8Array(await crypto.subtle.digest(hash, bytes)));
 }
-export { ECDSA_CURVES, PBES2_ALGORITHMS, aesBitsOf, checkKeyUsage, cryptoKeyCurve, digestUrl, hashBitsOf, inferJWEAllowedAlgorithms, inferJWSAllowedAlgorithms, innerKeyWrapAlg, isAlgorithm, isContentEncryptionAlgorithm, isECDHESAlgorithm, isJWSAlgorithm, isKeyManagementAlgorithm, isPBES2Algorithm, isSameAlgorithm, jwkAlgServes, jwsHashOf, lengthOf, modulusLengthOf, namedCurveOf, pbes2HashOf, rsaOaepHashOf, shaBitsOf, unusableKey };
+export { ECDSA_CURVES, PBES2_ALGORITHMS, aesBitsOf, checkKeyUsage, cryptoKeyCurve, digestUrl, hashBitsOf, inferJWEAllowedAlgorithms, inferJWSAllowedAlgorithms, innerKeyWrapAlg, isAlgorithm, isContentEncryptionAlgorithm, isECDHESAlgorithm, isJWSAlgorithm, isKeyManagementAlgorithm, isPBES2Algorithm, isSameAlgorithm, jwkAlgServes, jwkKtyServes, jwsAlgsFromJWK, jwsHashOf, lengthOf, modulusLengthOf, namedCurveOf, pbes2HashOf, rsaOaepHashOf, shaBitsOf, unusableKey };

package/dist/_chunks/error.d.mts

@@ -1,34 +1,30 @@
 import { UnsecureError, UnsecureErrorCode } from "./libs/unsecure.mjs";
 /**
- * The closed union of error codes unjwt itself throws.
+ * Every error code unjwt throws, as a closed union.
  *
- * Code naming follows the JOSE spec hierarchy:
- *   ERR_JWT_*  — RFC 7519 JSON Web Token claim validation
- *   ERR_JWS_*  — RFC 7515 JSON Web Signature
- *   ERR_JWE_*  — RFC 7516 JSON Web Encryption
- *   ERR_JWK_*  — RFC 7517 JSON Web Key
- *   ERR_DPOP_* — RFC 9449 proof validation
- *   ERR_SESSION_* — the framework session adapters
+ * Prefixes follow the specs:
+ *   ERR_JWT_*: RFC 7519 claim validation
+ *   ERR_JWS_*: RFC 7515 signatures
+ *   ERR_JWE_*: RFC 7516 encryption
+ *   ERR_JWK_*: RFC 7517 keys
+ *   ERR_DPOP_*: RFC 9449 proofs
+ *   ERR_SESSION_*: sessions
  *
- * Use this type where a typo must not compile — {@link isJWTError} takes it,
- * so `isJWTError(err, "ERR_JWS_INVALD")` is a type error rather than a check
- * that silently never matches. Use {@link JWTErrorCode} for values that may
- * legitimately carry a code this version does not know about.
+ * {@link isJWTError} takes this type, so a misspelled code such as `"ERR_JWS_INVALD"` is a type error.
+ * Use {@link JWTErrorCode} for a value that may hold a code outside this union.
  */
-export type KnownJWTErrorCode = "ERR_JWT_EXPIRED" | "ERR_JWT_NBF" | "ERR_JWT_CLAIM_INVALID" | "ERR_JWT_CLAIM_MISSING" | "ERR_JWS_INVALID" | "ERR_JWS_INVALID_SERIALIZATION" | "ERR_JWS_SIGNATURE_INVALID" | "ERR_JWS_ALG_NOT_ALLOWED" | "ERR_JWS_ALG_MISSING" | "ERR_JWS_SIGNER_ALG_INFERENCE" | "ERR_JWS_NO_MATCHING_SIGNER" | "ERR_JWS_HEADER_PARAMS_NOT_DISJOINT" | "ERR_JWS_B64_INCONSISTENT" | "ERR_JWE_INVALID" | "ERR_JWE_INVALID_SERIALIZATION" | "ERR_JWE_DECRYPTION_FAILED" | "ERR_JWE_ALG_NOT_ALLOWED" | "ERR_JWE_ALG_MISSING" | "ERR_JWE_ALG_FORBIDDEN_IN_MULTI" | "ERR_JWE_ENC_MISSING" | "ERR_JWE_RECIPIENT_ALG_INFERENCE" | "ERR_JWE_NO_MATCHING_RECIPIENT" | "ERR_JWE_HEADER_PARAMS_NOT_DISJOINT" | "ERR_JWK_INVALID" | "ERR_JWK_KEY_NOT_FOUND" | "ERR_JWK_UNSUPPORTED" | "ERR_DPOP_INVALID" | "ERR_DPOP_CLAIM_INVALID" | "ERR_DPOP_NONCE_INVALID" | "ERR_DPOP_REPLAY" | "ERR_SESSION_TOKEN_INVALID" | "ERR_SESSION_READONLY_EVENT" | "ERR_SESSION_KEY_INVALID" | "ERR_SESSION_CONFIG_INVALID" | "ERR_INVALID_OPTION";
+export type KnownJWTErrorCode = "ERR_JWT_EXPIRED" | "ERR_JWT_NBF" | "ERR_JWT_CLAIM_INVALID" | "ERR_JWT_CLAIM_MISSING" | "ERR_JWS_INVALID" | "ERR_JWS_INVALID_SERIALIZATION" | "ERR_JWS_SIGNATURE_INVALID" | "ERR_JWS_ALG_NOT_ALLOWED" | "ERR_JWS_ALG_MISSING" | "ERR_JWS_SIGNER_ALG_INFERENCE" | "ERR_JWS_NO_MATCHING_SIGNER" | "ERR_JWS_HEADER_PARAMS_NOT_DISJOINT" | "ERR_JWS_B64_INCONSISTENT" | "ERR_JWE_INVALID" | "ERR_JWE_INVALID_SERIALIZATION" | "ERR_JWE_DECRYPTION_FAILED" | "ERR_JWE_ALG_NOT_ALLOWED" | "ERR_JWE_ALG_MISSING" | "ERR_JWE_ALG_FORBIDDEN_IN_MULTI" | "ERR_JWE_ENC_MISSING" | "ERR_JWE_RECIPIENT_ALG_INFERENCE" | "ERR_JWE_NO_MATCHING_RECIPIENT" | "ERR_JWE_HEADER_PARAMS_NOT_DISJOINT" | "ERR_JWK_INVALID" | "ERR_JWK_KEY_NOT_FOUND" | "ERR_JWK_UNSUPPORTED" | "ERR_DPOP_INVALID" | "ERR_DPOP_CLAIM_INVALID" | "ERR_DPOP_NONCE_INVALID" | "ERR_DPOP_REPLAY" | "ERR_SESSION_TOKEN_INVALID" | "ERR_SESSION_READ_FAILED" | "ERR_SESSION_READONLY_EVENT" | "ERR_SESSION_KEY_INVALID" | "ERR_SESSION_CONFIG_INVALID" | "ERR_INVALID_OPTION";
 /**
- * A {@link JWTError} `code`: every {@link KnownJWTErrorCode}, plus any other
- * string for forward compatibility — a newer unjwt (or a caller constructing
- * its own `JWTError`) may carry a code this version's union does not list.
+ * A {@link JWTError} `code`: any {@link KnownJWTErrorCode} or any other string.
+ * A `JWTError` built outside unjwt can hold a code outside the union.
  */
 export type JWTErrorCode = KnownJWTErrorCode | (string & {});
 /**
- * Maps known error codes to their structured `cause` shapes.
- * Only codes that carry decoded context beyond the message appear here.
- * Extend this interface when new structured causes are introduced.
+ * The structured `cause` of each code that has one.
+ * {@link isJWTError} narrows `cause` to this shape for the listed codes.
  */
 export interface JWTErrorCauseMap {
-  /** Decoded claims available at the point the lifetime check failed. */
+  /** The token's `jti` (when a string), `iat` and `exp` claims. */
   ERR_JWT_EXPIRED: {
     jti?: string;
     iat?: number;
@@ -36,13 +32,13 @@ export interface JWTErrorCauseMap {
   };
 }
 /**
- * Base error class for all unjwt errors. Every error thrown by the library is
- * an instance of `JWTError`, so a single `instanceof` check is sufficient to
- * distinguish library errors from other thrown values. Use the `code` property
- * (or the `isJWTError` type guard) to narrow to a specific error condition.
+ * The error class of the JWS, JWE, JWK, DPoP and session operations.
+ * `code` names the condition. Narrow on it with {@link isJWTError}.
+ *
+ * The `unjwt/utils` primitives throw {@link UnsecureError} instead.
  *
  * @example
- * import { JWTError, isJWTError } from "unjwt/jws";
+ * import { verify, isJWTError } from "unjwt/jws";
  *
  * try {
  *   await verify(token, key);
@@ -58,16 +54,11 @@ export declare class JWTError<TCode extends JWTErrorCode = JWTErrorCode> extends
   constructor(message: string, code: TCode, cause?: unknown);
 }
 /**
- * Type guard that narrows `error` to `JWTError`.
- *
- * When called with a code that is a key of `JWTErrorCauseMap`, the return
- * type is additionally narrowed to include the structured `cause` shape for
- * that code. When called with any other `KnownJWTErrorCode`, `code` is narrowed
- * but `cause` remains `unknown`. When called without a code, narrows only to
- * `JWTError`.
+ * Returns `true` when `error` is a {@link JWTError}, and with `code`, only when its `code` is that one.
  *
- * `code` is a {@link KnownJWTErrorCode}, so a misspelled code fails to
- * type-check instead of silently never matching.
+ * With a code listed in {@link JWTErrorCauseMap}, `cause` narrows to that shape.
+ * With any other code, `code` narrows and `cause` stays `unknown`.
+ * `code` is a {@link KnownJWTErrorCode}, so a misspelled code is a type error.
  *
  * @example
  * if (isJWTError(err, "ERR_JWT_EXPIRED")) {
@@ -80,17 +71,13 @@ export declare function isJWTError<T extends keyof JWTErrorCauseMap>(error: unkn
 export declare function isJWTError<T extends KnownJWTErrorCode>(error: unknown, code: T): error is JWTError<T>;
 export declare function isJWTError(error: unknown): error is JWTError;
 /**
- * Type guard that narrows `error` to the bundled {@link UnsecureError}, the
- * class thrown by unjwt's codec / JSON / random primitives and carried as the
- * `cause` of a {@link JWTError} when a wire segment or key field fails to
- * decode. Pass a `code` to narrow further.
+ * Returns `true` when `error` is the {@link UnsecureError} unjwt throws, and with `code`, only when its `code` is that one.
+ * Use it on the `cause` of a {@link JWTError} whose token segment or key field failed to decode.
  *
- * Check against this export rather than a `UnsecureError` imported from a
- * consumer-installed `unsecure`: unjwt bundles its own copy, so the two classes
- * are distinct and `instanceof` against the latter is always `false`.
+ * A separately installed copy of the class never matches.
  *
  * @example
- * import { isJWTError, isUnsecureError } from "unjwt/jws";
+ * import { verify, isJWTError, isUnsecureError } from "unjwt/jws";
  *
  * const error = await verify(token, key).catch((e) => e);
  * if (isJWTError(error, "ERR_JWS_INVALID") && isUnsecureError(error.cause, "MALFORMED")) {

package/dist/_chunks/export.mjs

@@ -61,9 +61,6 @@ async function exportJWK(key, jwkParams) {
 	}
 	return exportedJwk;
 }
-async function exportKey(key, jwkParams) {
-	return exportJWK(key, jwkParams);
-}
 function toPublicJWK(jwk) {
 	if (!isAsymmetricJWK(jwk)) throw new JWTError(isJWK(jwk) ? "An oct JWK has no public half." : "toPublicJWK expects an asymmetric JWK.", "ERR_JWK_INVALID");
 	const { d: _d, p: _p, q: _q, dp: _dp, dq: _dq, qi: _qi, oth: _oth, k: _k, key_ops, ...publicMembers } = copyJsonObject({ ...jwk }, {
@@ -94,4 +91,4 @@ function publicKeyOps(keyOps) {
 	}
 	return ops;
 }
-export { assertKidOption, assertNoReservedJWKParams, exportJWK, exportKey, requestedKeyOps, toPublicJWK, withGeneratedKid, withKeyOps };
+export { assertKidOption, assertNoReservedJWKParams, exportJWK, requestedKeyOps, toPublicJWK, withGeneratedKid, withKeyOps };