unjwt 0.5.39 → 0.6.0

package/dist/core/jwk.mjs

@@ -0,0 +1,686 @@
+import { M as JWTError, N as isJWTError, a as base64UrlEncode, c as isCryptoKey, d as isJWKSet, g as randomBytes, i as base64UrlDecode, l as isCryptoKeyPair, u as isJWK, v as textEncoder, y as sanitizeObject } from "../_chunks/utils.mjs";
+import { C as gcmkwEncrypt, S as gcmkwDecrypt, _ as aesKwUnwrap, a as toSPKI, c as deriveKey, d as deriveECDHESKey, f as isECDHKeyAllowed, g as keyToJWK, h as jwkTokey, i as toPKCS8, l as pbes2Unwrap, m as encryptRSAES, n as fromSPKI, p as decryptRSAES, r as fromX509, s as normalizeKey, t as fromPKCS8, u as pbes2Wrap, v as aesKwWrap, y as bitLengthCEK } from "../_chunks/_crypto.mjs";
+//#region src/core/jwk.ts
+async function generateKey(alg, options = {}) {
+	const exportToJWK = options.toJWK !== void 0 && options.toJWK !== false;
+	const defaultExtractable = options.extractable !== false;
+	if (alg === "A128CBC-HS256" || alg === "A192CBC-HS384" || alg === "A256CBC-HS512") {
+		const keyBytes = randomBytes(bitLengthCEK(alg) >> 3);
+		if (exportToJWK) return keyToJWK(keyBytes);
+		return keyBytes;
+	}
+	const { algorithm, keyUsages } = getGenerateKeyParams(alg, options);
+	const key = await crypto.subtle.generateKey(algorithm, defaultExtractable, keyUsages);
+	if (exportToJWK) if (key instanceof CryptoKey) return exportKey(key, { alg });
+	else {
+		const [publicKey, privateKey] = await Promise.all([exportKey(key.publicKey, { alg }), exportKey(key.privateKey, { alg })]);
+		return {
+			privateKey,
+			publicKey
+		};
+	}
+	return key;
+}
+/**
+* Generates a Json Web Key (JWK) for the specified algorithm.
+*
+* @param alg The JWA algorithm identifier (e.g., "HS256", "RS256", "A128GCM").
+* @param jwkParams Optional partial JWK to merge with the generated key, allowing overrides.
+* @param options Configuration options for key generation.
+* @returns A Promise resolving to the generated JWK or JWK pair representation.
+*/
+async function generateJWK(alg, jwkParams, options = {}) {
+	const extraParams = {
+		kid: typeof jwkParams?.kid === "string" ? jwkParams.kid : crypto.randomUUID(),
+		...jwkParams
+	};
+	const result = await generateKey(alg, {
+		...options,
+		toJWK: true
+	});
+	if (result && typeof result === "object" && "privateKey" in result && "publicKey" in result) {
+		const pair = result;
+		return {
+			privateKey: {
+				...extraParams,
+				...pair.privateKey
+			},
+			publicKey: {
+				...extraParams,
+				...pair.publicKey
+			}
+		};
+	}
+	return {
+		...extraParams,
+		...result
+	};
+}
+async function deriveKeyFromPassword(password, alg, options) {
+	const { salt, iterations, extractable, keyUsage } = options;
+	const exportToJWK = options.toJWK !== void 0 && options.toJWK !== false;
+	if (!(salt instanceof Uint8Array) || salt.length < 8) throw new Error("PBES2 Salt Input (salt) must be 8 or more octets");
+	if (typeof iterations !== "number" || iterations < 1) throw new Error("PBES2 Iteration Count (iterations) must be a positive integer");
+	const derivedBytes = await deriveKey(salt, alg, iterations, typeof password === "string" ? textEncoder.encode(password) : password);
+	const wrappingAlg = alg.slice(-6);
+	const finalUsages = keyUsage ?? ["wrapKey", "unwrapKey"];
+	const finalExtractable = exportToJWK ? true : extractable === true;
+	const derivedKey = await crypto.subtle.importKey("raw", derivedBytes, { name: "AES-KW" }, finalExtractable, finalUsages);
+	if (exportToJWK) return {
+		...await keyToJWK(derivedKey),
+		alg: wrappingAlg,
+		kty: "oct"
+	};
+	return derivedKey;
+}
+/**
+* Derives a Json Web Key (JWK) from a password using PBKDF2 as specified by PBES2 algorithms.
+*
+* @param password The password to derive the key from (string or Uint8Array).
+* @param alg The PBES2 algorithm identifier (e.g., "PBES2-HS256+A128KW").
+* @param jwkParams Optional partial JWK to merge with the generated key, allowing overrides.
+* @param options Configuration options including salt and iterations.
+* @returns A Promise resolving to the derived JWK (JWK_oct).
+*/
+async function deriveJWKFromPassword(password, alg, options, jwkParams) {
+	const result = await deriveKeyFromPassword(password, alg, {
+		...options,
+		toJWK: true
+	});
+	return jwkParams ? {
+		...jwkParams,
+		...result
+	} : result;
+}
+/**
+* Default JWK import cache backed by a WeakMap.
+*
+* The outer WeakMap is keyed by the JWK object reference — a cache hit only
+* occurs when the exact same object variable is passed to {@link importKey}.
+* Reconstructing a structurally identical JWK (e.g. `{ ...jwk }`) will miss
+* the cache.
+*
+* The inner `Record<string, CryptoKey>` uses a plain object rather than `Map`
+* because typical entries have 1–2 algorithm strings per key. V8 applies
+* hidden-class optimisation to small plain objects, making property access
+* faster than `Map.get()` at this cardinality.
+*/
+var WeakMapJWKCache = class {
+	_map = /* @__PURE__ */ new WeakMap();
+	get(jwk, alg) {
+		return this._map.get(jwk)?.[alg];
+	}
+	set(jwk, alg, key) {
+		let entry = this._map.get(jwk);
+		if (!entry) this._map.set(jwk, { [alg]: key });
+		else entry[alg] = key;
+	}
+};
+let _activeCache = new WeakMapJWKCache();
+/**
+* Replace or disable the JWK import cache used by {@link importKey}.
+*
+* Pass a custom {@link JWKCacheAdapter} to use your own cache strategy
+* (LRU, Redis-backed wrapper, test spy, etc.). Pass `false` to disable
+* caching entirely.
+*
+* @example Disable caching:
+* ```ts
+* configureJWKCache(false);
+* ```
+* @example Use a custom kid-keyed cache:
+* ```ts
+* const map = new Map<string, CryptoKey>();
+* configureJWKCache({
+*   get: (jwk, alg) => map.get(`${jwk.kid}:${alg}`),
+*   set: (jwk, alg, key) => map.set(`${jwk.kid}:${alg}`, key),
+* });
+* ```
+*/
+function configureJWKCache(cache) {
+	_activeCache = cache;
+}
+/**
+* Reset the JWK import cache to a fresh {@link WeakMapJWKCache}.
+* Useful in test environments to clear all cached CryptoKey references
+* between test runs without disabling the cache entirely.
+*/
+function clearJWKCache() {
+	_activeCache = new WeakMapJWKCache();
+}
+async function importKey(key, algOrOptions) {
+	const alg = typeof algOrOptions === "string" ? algOrOptions : void 0;
+	if (typeof key === "string") key = textEncoder.encode(key);
+	if (key instanceof Uint8Array) return key;
+	if (isCryptoKey(key)) return key;
+	if (isJWK(key)) if ("k" in key && typeof key.k === "string") {
+		const rawBytes = base64UrlDecode(key.k, false);
+		if (typeof algOrOptions === "object" && algOrOptions.asCryptoKey) {
+			const { algorithm, usage, extractable = false } = algOrOptions;
+			return crypto.subtle.importKey("raw", rawBytes, algorithm, extractable, usage);
+		}
+		return rawBytes;
+	} else {
+		if (!key.alg && !alg) throw new TypeError("Algorithm must be provided when importing non-oct JWK");
+		const effectiveAlg = key.alg || alg;
+		if (_activeCache) {
+			const cached = _activeCache.get(key, effectiveAlg);
+			if (cached) return cached;
+		}
+		const cryptoKey = await jwkTokey(key.alg ? key : {
+			...key,
+			alg
+		});
+		if (_activeCache) _activeCache.set(key, effectiveAlg, cryptoKey);
+		return cryptoKey;
+	}
+	throw new JWTError("Invalid key type provided to importKey", "ERR_JWK_INVALID");
+}
+/**
+* Exports a CryptoKey to a JWK (JSON Web Key) format.
+*
+* @param key The CryptoKey to export.
+* @param jwk Optional partial JWK to merge with the exported key, allowing overrides.
+* @returns A Promise resolving to the exported JWK.
+*/
+async function exportKey(key, jwk) {
+	const exportedJwk = await keyToJWK(key);
+	if (jwk) return {
+		...sanitizeObject(jwk),
+		...exportedJwk
+	};
+	return exportedJwk;
+}
+async function resolveWrappingKey(alg, key) {
+	if (alg.startsWith("PBES2") && (typeof key === "string" || key instanceof Uint8Array)) return typeof key === "string" ? textEncoder.encode(key) : key;
+	if (typeof key === "string") throw new TypeError(`Key must be CryptoKey, JWK, or Uint8Array for ${alg}`);
+	return importKey(key, alg);
+}
+/**
+* Wraps a Content Encryption Key (CEK) using the specified algorithm and wrapping key.
+*
+* @param alg The JWA key management algorithm (e.g., "A128KW", "RSA-OAEP", "PBES2-HS256+A128KW").
+* @param keyToWrap The key to be wrapped (CEK), typically a symmetric key as Uint8Array or CryptoKey.
+* @param wrappingKey The key used to wrap the CEK (CryptoKey, JWK, or password string/Uint8Array for PBES2).
+* @param options Additional options required by certain algorithms (e.g., p2s, p2c for PBES2).
+* @returns A Promise resolving to an object containing the wrapped key and any necessary parameters (iv, tag, epk, etc.).
+*/
+async function wrapKey(alg, keyToWrap, wrappingKey, options = {}) {
+	const cekBytes = keyToWrap instanceof Uint8Array ? keyToWrap : new Uint8Array(await crypto.subtle.exportKey("raw", keyToWrap));
+	const importedWrappingKey = await resolveWrappingKey(alg, wrappingKey);
+	switch (alg) {
+		case "dir": return { encryptedKey: new Uint8Array(0) };
+		case "A128KW":
+		case "A192KW":
+		case "A256KW": return { encryptedKey: await aesKwWrap(alg, importedWrappingKey, cekBytes) };
+		case "PBES2-HS256+A128KW":
+		case "PBES2-HS384+A192KW":
+		case "PBES2-HS512+A256KW": {
+			const { p2s, p2c } = options;
+			if (!p2s || typeof p2c !== "number") throw new Error("PBES2 requires 'p2s' (salt) and 'p2c' (count) options");
+			return pbes2Wrap(alg, importedWrappingKey, cekBytes, p2c, p2s);
+		}
+		case "A128GCMKW":
+		case "A192GCMKW":
+		case "A256GCMKW": {
+			const { encryptedKey, iv, tag } = await gcmkwEncrypt(alg, importedWrappingKey, cekBytes, options.iv);
+			return {
+				encryptedKey,
+				iv,
+				tag
+			};
+		}
+		case "RSA-OAEP":
+		case "RSA-OAEP-256":
+		case "RSA-OAEP-384":
+		case "RSA-OAEP-512": return { encryptedKey: await encryptRSAES(alg, importedWrappingKey, cekBytes) };
+		case "ECDH-ES":
+		case "ECDH-ES+A128KW":
+		case "ECDH-ES+A192KW":
+		case "ECDH-ES+A256KW": {
+			if (!(importedWrappingKey instanceof CryptoKey)) throw new TypeError("ECDH-ES requires the wrapping key to be a CryptoKey (recipient's public key)");
+			if (!isECDHKeyAllowed(importedWrappingKey)) throw new JWTError("ECDH with the provided key is not allowed or not supported", "ERR_JWK_INVALID");
+			const apu = options.ecdh?.partyUInfo ?? new Uint8Array(0);
+			const apv = options.ecdh?.partyVInfo ?? new Uint8Array(0);
+			const { ephemeralPrivateKey, epkJwk } = await resolveECDHEphemeralPair(importedWrappingKey, options.ecdh?.ephemeralKey);
+			const infoAlg = alg === "ECDH-ES" ? (() => {
+				if (!options.ecdh?.enc) throw new JWTError("ECDH-ES direct key agreement requires options.ecdh.enc (the target content encryption algorithm)", "ERR_JWK_INVALID");
+				return options.ecdh.enc;
+			})() : alg;
+			const sharedSecret = await deriveECDHESKey(importedWrappingKey, ephemeralPrivateKey, infoAlg, alg === "ECDH-ES" ? bitLengthCEK(infoAlg) : Number.parseInt(alg.slice(-5, -2), 10), apu, apv);
+			const wrapResult = {
+				encryptedKey: new Uint8Array(0),
+				epk: epkJwk
+			};
+			if (apu.length > 0) wrapResult.apu = base64UrlEncode(apu);
+			if (apv.length > 0) wrapResult.apv = base64UrlEncode(apv);
+			if (alg === "ECDH-ES") return wrapResult;
+			wrapResult.encryptedKey = await aesKwWrap(alg.slice(-6), sharedSecret, cekBytes);
+			return wrapResult;
+		}
+		default: throw new Error(`Unsupported key wrapping algorithm: ${alg}`);
+	}
+}
+async function unwrapKey(alg, wrappedKey, unwrappingKey, options = {}) {
+	const returnRaw = options.format === "raw";
+	const defaultExtractable = options.extractable !== false;
+	const importedUnwrappingKey = isCryptoKey(unwrappingKey) ? unwrappingKey : await resolveWrappingKey(alg, unwrappingKey);
+	let unwrappedCekBytes;
+	switch (alg) {
+		case "dir":
+			if (importedUnwrappingKey instanceof Uint8Array) unwrappedCekBytes = importedUnwrappingKey;
+			else {
+				if (!returnRaw) return importedUnwrappingKey;
+				unwrappedCekBytes = new Uint8Array(await crypto.subtle.exportKey("raw", importedUnwrappingKey));
+			}
+			break;
+		case "A128KW":
+		case "A192KW":
+		case "A256KW":
+			unwrappedCekBytes = await aesKwUnwrap(alg, importedUnwrappingKey, wrappedKey);
+			break;
+		case "PBES2-HS256+A128KW":
+		case "PBES2-HS384+A192KW":
+		case "PBES2-HS512+A256KW": {
+			const { p2s, p2c } = options;
+			if (!p2s || typeof p2c !== "number") throw new Error("PBES2 requires 'p2s' (salt) and 'p2c' (count) options");
+			unwrappedCekBytes = await pbes2Unwrap(alg, importedUnwrappingKey, wrappedKey, p2c, typeof p2s === "string" ? base64UrlDecode(p2s, false) : p2s);
+			break;
+		}
+		case "A128GCMKW":
+		case "A192GCMKW":
+		case "A256GCMKW":
+			if (!options.iv || !options.tag) throw new Error("AES-GCMKW requires 'iv' and 'tag' options for unwrapping");
+			unwrappedCekBytes = await gcmkwDecrypt(alg, importedUnwrappingKey, wrappedKey, typeof options.iv === "string" ? base64UrlDecode(options.iv, false) : options.iv, typeof options.tag === "string" ? base64UrlDecode(options.tag, false) : options.tag);
+			break;
+		case "RSA-OAEP":
+		case "RSA-OAEP-256":
+		case "RSA-OAEP-384":
+		case "RSA-OAEP-512": {
+			if (!(importedUnwrappingKey instanceof CryptoKey)) throw new TypeError("RSA-OAEP requires the unwrapping key to be provided as a CryptoKey");
+			unwrappedCekBytes = await decryptRSAES(alg, importedUnwrappingKey, wrappedKey);
+			if (returnRaw) break;
+			const inferredAlgorithm = options.unwrappedKeyAlgorithm || inferAesImportAlgorithm(options.enc, unwrappedCekBytes.length);
+			if (!inferredAlgorithm) throw new Error("Unable to infer algorithm for RSA-OAEP unwrapped key. Provide \"unwrappedKeyAlgorithm\" in options.");
+			const keyUsages = options.keyUsage || ["encrypt", "decrypt"];
+			return await crypto.subtle.importKey("raw", unwrappedCekBytes, inferredAlgorithm, defaultExtractable, keyUsages);
+		}
+		case "ECDH-ES":
+		case "ECDH-ES+A128KW":
+		case "ECDH-ES+A192KW":
+		case "ECDH-ES+A256KW": {
+			if (!options.epk) throw new Error("ECDH-ES requires 'epk' (Ephemeral Public Key) option");
+			if (!(importedUnwrappingKey instanceof CryptoKey)) throw new TypeError("ECDH-ES requires the unwrapping key to be a CryptoKey");
+			if (!isECDHKeyAllowed(importedUnwrappingKey)) throw new Error("ECDH with the provided key is not allowed or not supported");
+			const epkCandidate = options.epk instanceof CryptoKey ? options.epk : await normalizeKey(options.epk, alg);
+			if (!(epkCandidate instanceof CryptoKey)) throw new TypeError("Failed to normalize ECDH ephemeral public key");
+			const apuBytes = typeof options.apu === "string" ? base64UrlDecode(options.apu, false) : options.apu ?? new Uint8Array(0);
+			const apvBytes = typeof options.apv === "string" ? base64UrlDecode(options.apv, false) : options.apv ?? new Uint8Array(0);
+			const infoAlg = alg === "ECDH-ES" ? options.enc : alg;
+			if (!infoAlg) throw new Error("ECDH-ES requires content encryption algorithm ('enc') to derive the shared secret");
+			const sharedSecret = await deriveECDHESKey(epkCandidate, importedUnwrappingKey, infoAlg, alg === "ECDH-ES" ? bitLengthCEK(infoAlg) : Number.parseInt(alg.slice(-5, -2), 10), apuBytes, apvBytes);
+			if (alg === "ECDH-ES") unwrappedCekBytes = sharedSecret;
+			else {
+				const kwAlg = alg.slice(-6);
+				if (!(wrappedKey instanceof Uint8Array) || wrappedKey.length === 0) throw new Error("ECDH-ES key agreement with key wrapping requires an encrypted key");
+				unwrappedCekBytes = await aesKwUnwrap(kwAlg, sharedSecret, wrappedKey);
+			}
+			break;
+		}
+		default: throw new Error(`Unsupported key unwrapping algorithm: ${alg}`);
+	}
+	if (returnRaw) return unwrappedCekBytes;
+	return await crypto.subtle.importKey("raw", unwrappedCekBytes, options.unwrappedKeyAlgorithm || { name: "AES-GCM" }, defaultExtractable, options.keyUsage || ["encrypt", "decrypt"]);
+}
+/**
+* Imports a key from a PEM-encoded string and converts it to a JWK.
+*
+* @param pem The PEM-encoded string.
+* @param pemType The type of PEM encoding ('pkcs8' for private keys, 'spki' for public keys, 'x509' for certificates).
+* @param alg The JWA algorithm identifier. This is crucial for `crypto.subtle.importKey`
+*            to understand the key's intended algorithm and for setting the 'alg' field in the resulting JWK.
+* @param importOptions Options for the PEM import process (e.g., extractable for the CryptoKey).
+* @param jwkExtras Additional properties to merge into the resulting JWK.
+* @returns A Promise resolving to the imported key as a JWK.
+*/
+async function importFromPEM(pem, pemType, alg, options) {
+	const extractable = options?.extractable !== false;
+	let cryptoKey;
+	switch (pemType) {
+		case "pkcs8":
+			cryptoKey = await fromPKCS8(pem, alg, { extractable });
+			break;
+		case "spki":
+			cryptoKey = await fromSPKI(pem, alg, { extractable });
+			break;
+		case "x509":
+			cryptoKey = await fromX509(pem, alg, { extractable });
+			break;
+		default: throw new TypeError(`Unsupported PEM type: ${pemType}`);
+	}
+	return exportKey(cryptoKey, {
+		alg,
+		...options?.jwkParams
+	});
+}
+/**
+* Exports a JWK to a PEM-encoded string.
+*
+* @param jwk The JWK to export.
+* @param pemFormat The desired PEM format ('pkcs8' for private keys, 'spki' for public keys).
+* @param algForCryptoKeyImport If the JWK does not have an 'alg' property, this algorithm hint is
+*                              required to correctly convert it to a CryptoKey first.
+* @returns A Promise resolving to the PEM-encoded key string.
+*/
+async function exportToPEM(jwk, pemFormat, algForCryptoKeyImport) {
+	if (jwk.kty === "oct") throw new TypeError("Octet (symmetric) JWKs (kty: 'oct') cannot be exported to PKCS8 or SPKI PEM formats.");
+	const effectiveAlg = jwk.alg || algForCryptoKeyImport;
+	if (!effectiveAlg && (jwk.kty === "RSA" || jwk.kty === "EC" || jwk.kty === "OKP")) throw new TypeError("Algorithm (alg) must be provided in the JWK or as a parameter for converting this JWK type to a CryptoKey.");
+	const cryptoKeyCandidate = await importKey({
+		...jwk,
+		ext: true
+	}, effectiveAlg);
+	if (!isCryptoKey(cryptoKeyCandidate)) throw new Error("Failed to convert JWK to a CryptoKey instance suitable for PEM export.");
+	const cryptoKey = cryptoKeyCandidate;
+	switch (pemFormat) {
+		case "pkcs8":
+			if (cryptoKey.type !== "private") throw new TypeError(`Only 'private' type CryptoKeys can be exported to PKCS8 PEM format. Key type is '${cryptoKey.type}'.`);
+			return toPKCS8(cryptoKey);
+		case "spki":
+			if (cryptoKey.type !== "public") throw new TypeError(`Only 'public' type CryptoKeys can be exported to SPKI PEM format. Key type is '${cryptoKey.type}'.`);
+			return toSPKI(cryptoKey);
+		default: throw new TypeError(`Unsupported PEM format: ${pemFormat}`);
+	}
+}
+/**
+* Derives a shared secret using ECDH-ES key agreement (RFC 7518 §4.6).
+*
+* Performs an Elliptic Curve Diffie-Hellman Ephemeral-Static key derivation
+* followed by a Concat KDF (NIST SP 800-56A) to produce key material of the
+* requested length. The result can be used directly as a CEK (for `ECDH-ES`
+* direct key agreement) or as a KEK to wrap a separately generated CEK (for
+* `ECDH-ES+A*KW`).
+*
+* For multi-recipient JWE, call this once per recipient with their public key
+* and a fresh ephemeral private key, then wrap the shared CEK with the derived
+* material using {@link wrapKey}.
+*
+* @param publicKey The recipient's static public key (or the sender's
+*   ephemeral public key on the decryption side).
+* @param privateKey The sender's ephemeral private key (or the recipient's
+*   static private key on the decryption side).
+* @param alg The algorithm identifier used as the `AlgorithmID` in the
+*   concat KDF info structure. Pass a {@link JWK_ECDH_ES} variant
+*   (e.g. `"ECDH-ES+A128KW"`) or a {@link ContentEncryptionAlgorithm}
+*   (e.g. `"A256GCM"`) for direct key agreement.
+* @param options Optional overrides for key length and party info.
+*/
+async function deriveSharedSecret(publicKey, privateKey, alg, options) {
+	const pubCryptoKey = isCryptoKey(publicKey) ? publicKey : await importKey(publicKey, "ECDH-ES");
+	const privCryptoKey = isCryptoKey(privateKey) ? privateKey : await importKey(privateKey, "ECDH-ES");
+	let keyLength;
+	if (options?.keyLength !== void 0) keyLength = options.keyLength;
+	else if (alg === "ECDH-ES") throw new JWTError("deriveSharedSecret with alg \"ECDH-ES\" requires an explicit keyLength in options", "ERR_JWK_INVALID");
+	else if (alg.startsWith("ECDH-ES+")) keyLength = Number.parseInt(alg.slice(-5, -2), 10);
+	else keyLength = bitLengthCEK(alg);
+	return deriveECDHESKey(pubCryptoKey, privCryptoKey, alg, keyLength, options?.partyUInfo ?? new Uint8Array(0), options?.partyVInfo ?? new Uint8Array(0));
+}
+/**
+* @deprecated For set queries, use {@link getJWKsFromSet} which returns all
+* matching keys as an array. This function remains available for internal
+* single-key resolution by `kid` or JOSE header (used by `verify` and `decrypt`).
+*
+* Retrieves a JWK (JSON Web Key) from a JWKSet based on a key ID (kid) or
+* properties from a JOSE Header.
+*
+* @param jwkSet The JWKSet to search within.
+* @param kidOrProtectedHeader Either a string representing the 'kid' (Key ID)
+*        or an object representing the JOSE Protected Header. If an object is
+*        provided, it must contain a 'kid' property. It can optionally contain
+*        'alg' (Algorithm) and 'kty' (Key Type) to further refine the search.
+* @returns The matching JWK from the set.
+* @throws TypeError if `jwkSet` is invalid or `kidOrProtectedHeader` is not a
+*         string or a valid header object.
+* @throws Error if no key is found matching the provided criteria, or if the
+*         header object is missing the 'kid' property.
+*/
+function getJWKFromSet(jwkSet, kidOrProtectedHeader) {
+	if (!jwkSet || !isJWKSet(jwkSet)) throw new TypeError("Invalid JWK Set provided");
+	if (typeof kidOrProtectedHeader === "string") {
+		const kid = kidOrProtectedHeader;
+		const selectedKey = jwkSet.keys.find((k) => k.kid === kid);
+		if (!selectedKey) throw new JWTError(`No key found in JWK Set with kid "${kid}".`, "ERR_JWK_KEY_NOT_FOUND");
+		return selectedKey;
+	} else if (typeof kidOrProtectedHeader === "object") {
+		const { kid, alg, kty } = kidOrProtectedHeader;
+		if (!kid) {
+			if (jwkSet.keys.length === 1) return jwkSet.keys[0];
+			throw new JWTError("JWS Protected Header is missing 'kid' (Key ID) and the JWK Set contains multiple keys. Add a 'kid' parameter to the token header and to the matching JWK to enable automatic selection.", "ERR_JWK_KEY_NOT_FOUND");
+		}
+		const selectedKey = jwkSet.keys.find((k) => {
+			return k.kid === kid && (!alg || k.alg === alg) && (!kty || k.kty === kty);
+		});
+		if (!selectedKey) {
+			let errorMessage = `No key found in JWK Set with kid "${kid}"`;
+			if (alg) errorMessage += ` and alg "${alg}"`;
+			if (kty) errorMessage += ` and kty "${kty}"`;
+			errorMessage += ".";
+			throw new JWTError(errorMessage, "ERR_JWK_KEY_NOT_FOUND");
+		}
+		return selectedKey;
+	}
+	throw new TypeError("`kidOrProtectedHeader` must be a string (kid) or an object (JOSE Protected Header).");
+}
+/**
+* Returns all JWKs from a JWK Set, optionally narrowed by a predicate.
+*
+* Useful for multi-key verification retry, key rotation tooling, and
+* constructing multi-recipient JWE JSON Serialization structures.
+*
+* @param jwkSet The JWK Set to search.
+* @param filter Optional predicate `(jwk: JWK) => boolean`. Returns all keys when omitted.
+* @returns An array of matching JWKs.
+*/
+function getJWKsFromSet(jwkSet, filter) {
+	if (!jwkSet || !isJWKSet(jwkSet)) throw new TypeError("Invalid JWK Set provided");
+	if (!filter) return [...jwkSet.keys];
+	return jwkSet.keys.filter(filter);
+}
+function getGenerateKeyParams(alg, options) {
+	let algorithm;
+	let keyUsages;
+	const defaultKeyUsage = options?.keyUsage;
+	switch (alg) {
+		case "HS256":
+		case "HS384":
+		case "HS512":
+			algorithm = {
+				name: "HMAC",
+				hash: `SHA-${alg.slice(2)}`
+			};
+			keyUsages = defaultKeyUsage ?? ["sign", "verify"];
+			break;
+		case "RS256":
+		case "RS384":
+		case "RS512":
+			algorithm = {
+				name: "RSASSA-PKCS1-v1_5",
+				modulusLength: options?.modulusLength ?? 2048,
+				publicExponent: options?.publicExponent ?? new Uint8Array([
+					1,
+					0,
+					1
+				]),
+				hash: `SHA-${alg.slice(2)}`
+			};
+			keyUsages = defaultKeyUsage ?? ["sign", "verify"];
+			break;
+		case "PS256":
+		case "PS384":
+		case "PS512":
+			algorithm = {
+				name: "RSA-PSS",
+				modulusLength: options?.modulusLength ?? 2048,
+				publicExponent: options?.publicExponent ?? new Uint8Array([
+					1,
+					0,
+					1
+				]),
+				hash: `SHA-${alg.slice(2)}`
+			};
+			keyUsages = defaultKeyUsage ?? ["sign", "verify"];
+			break;
+		case "RSA-OAEP":
+		case "RSA-OAEP-256":
+		case "RSA-OAEP-384":
+		case "RSA-OAEP-512":
+			algorithm = {
+				name: "RSA-OAEP",
+				modulusLength: options?.modulusLength ?? 2048,
+				publicExponent: options?.publicExponent ?? new Uint8Array([
+					1,
+					0,
+					1
+				]),
+				hash: `SHA-${Number.parseInt(alg.slice(9), 10) || 1}`
+			};
+			keyUsages = defaultKeyUsage ?? [
+				"encrypt",
+				"decrypt",
+				"wrapKey",
+				"unwrapKey"
+			];
+			break;
+		case "A128KW":
+		case "A192KW":
+		case "A256KW":
+			algorithm = {
+				name: "AES-KW",
+				length: Number.parseInt(alg.slice(1, 4), 10)
+			};
+			keyUsages = defaultKeyUsage ?? ["wrapKey", "unwrapKey"];
+			break;
+		case "A128GCM":
+		case "A192GCM":
+		case "A256GCM":
+		case "A128GCMKW":
+		case "A192GCMKW":
+		case "A256GCMKW": {
+			const baseAlg = alg.replace("KW", "");
+			algorithm = {
+				name: "AES-GCM",
+				length: Number.parseInt(baseAlg.slice(1, 4), 10)
+			};
+			keyUsages = defaultKeyUsage ?? (alg.endsWith("KW") ? ["wrapKey", "unwrapKey"] : ["encrypt", "decrypt"]);
+			break;
+		}
+		case "ES256":
+		case "ES384":
+		case "ES512":
+			algorithm = {
+				name: "ECDSA",
+				namedCurve: `P-${alg.slice(2)}`
+			};
+			keyUsages = defaultKeyUsage ?? ["sign", "verify"];
+			break;
+		case "Ed25519":
+			keyUsages = defaultKeyUsage ?? ["sign", "verify"];
+			algorithm = { name: "Ed25519" };
+			break;
+		case "EdDSA": {
+			keyUsages = defaultKeyUsage ?? ["sign", "verify"];
+			const namedCurve = options?.namedCurve ?? "Ed25519";
+			switch (namedCurve) {
+				case "Ed25519":
+				case "Ed448":
+					algorithm = { name: namedCurve };
+					break;
+				default: throw new Error("Unsupported namedCurve provided. Supported values are: Ed25519 and Ed448");
+			}
+			break;
+		}
+		case "ECDH-ES":
+		case "ECDH-ES+A128KW":
+		case "ECDH-ES+A192KW":
+		case "ECDH-ES+A256KW": {
+			keyUsages = ["deriveBits"];
+			const namedCurve = options?.namedCurve ?? "P-256";
+			switch (namedCurve) {
+				case "P-256":
+				case "P-384":
+				case "P-521":
+					algorithm = {
+						name: "ECDH",
+						namedCurve
+					};
+					break;
+				case "X25519":
+					algorithm = { name: "X25519" };
+					break;
+				default: throw new Error("Unsupported namedCurve provided. Supported values are: P-256, P-384, P-521 and X25519");
+			}
+			break;
+		}
+		default: throw new Error(`Unsupported or invalid algorithm for key generation: ${alg}`);
+	}
+	return {
+		algorithm,
+		keyUsages
+	};
+}
+async function resolveECDHEphemeralPair(recipientPublicKey, ephemeralKeyInput) {
+	if (!ephemeralKeyInput) {
+		const generated = await crypto.subtle.generateKey(recipientPublicKey.algorithm, true, ["deriveBits"]);
+		const rawJwk = await keyToJWK(generated.publicKey);
+		return {
+			ephemeralPrivateKey: generated.privateKey,
+			epkJwk: stripPrivateJwkFields(rawJwk)
+		};
+	}
+	if (isCryptoKeyPair(ephemeralKeyInput)) {
+		const rawJwk = await keyToJWK(ephemeralKeyInput.publicKey);
+		return {
+			ephemeralPrivateKey: ephemeralKeyInput.privateKey,
+			epkJwk: stripPrivateJwkFields(rawJwk)
+		};
+	}
+	if (typeof ephemeralKeyInput === "object" && "publicKey" in ephemeralKeyInput && "privateKey" in ephemeralKeyInput) {
+		const { publicKey, privateKey } = ephemeralKeyInput;
+		return {
+			ephemeralPrivateKey: isCryptoKey(privateKey) ? privateKey : await importKey(privateKey, "ECDH-ES"),
+			epkJwk: isCryptoKey(publicKey) ? stripPrivateJwkFields(await keyToJWK(publicKey)) : stripPrivateJwkFields(publicKey)
+		};
+	}
+	if (isCryptoKey(ephemeralKeyInput)) {
+		if (ephemeralKeyInput.type !== "private") throw new TypeError("ECDH-ES ephemeral CryptoKey must be a private key");
+		return {
+			ephemeralPrivateKey: ephemeralKeyInput,
+			epkJwk: stripPrivateJwkFields(await keyToJWK(ephemeralKeyInput))
+		};
+	}
+	if (isJWK(ephemeralKeyInput) && "d" in ephemeralKeyInput) return {
+		ephemeralPrivateKey: await importKey(ephemeralKeyInput, "ECDH-ES"),
+		epkJwk: stripPrivateJwkFields(ephemeralKeyInput)
+	};
+	throw new TypeError("Unsupported ECDH-ES ephemeral key material");
+}
+function stripPrivateJwkFields(jwk) {
+	const { d: _d, ...pub } = jwk;
+	return pub;
+}
+function inferAesImportAlgorithm(enc, cekLengthBytes) {
+	const bitLength = cekLengthBytes << 3;
+	if (enc) {
+		if (enc.includes("GCM")) return {
+			name: "AES-GCM",
+			length: Number.parseInt(enc.slice(1, 4), 10)
+		};
+		if (enc.includes("CBC-HS")) return;
+	}
+	if (bitLength === 128 || bitLength === 192 || bitLength === 256) return {
+		name: "AES-GCM",
+		length: bitLength
+	};
+}
+//#endregion
+export { JWTError, WeakMapJWKCache, clearJWKCache, configureJWKCache, deriveJWKFromPassword, deriveKeyFromPassword, deriveSharedSecret, exportKey, exportToPEM, generateJWK, generateKey, getJWKFromSet, getJWKsFromSet, importFromPEM, importKey, isJWTError, unwrapKey, wrapKey };