unjwt 0.5.39 → 0.6.0

package/dist/{_chunks → core}/jwe.mjs

@@ -1,26 +1,25 @@
-import { t as __exportAll } from "./chunk.mjs";
-import { A as validateCriticalHeadersJWE, C as computeJwtTimeClaims, D as decodePayloadFromBytes, M as validateJwtClaims, O as getPlaintextBytes, a as base64UrlEncode, b as sanitizeObject, c as isCryptoKey, g as randomBytes, i as base64UrlDecode, l as isCryptoKeyPair, u as isJWK, v as textEncoder, x as applyTypCtyDefaults } from "./utils.mjs";
-import { d as unwrapKey, g as generateIV, h as encrypt$1, l as importKey, m as decrypt$1, p as encryptKey } from "./jwk.mjs";
+import { D as getPlaintextBytes, E as decodePayloadFromBytes, M as JWTError, N as isJWTError, S as computeJwtTimeClaims, a as base64UrlEncode, b as applyTypCtyDefaults, c as isCryptoKey, d as isJWKSet, g as randomBytes, i as base64UrlDecode, j as validateJwtClaims, k as validateCriticalHeadersJWE, l as isCryptoKeyPair, u as isJWK, v as textEncoder, y as sanitizeObject } from "../_chunks/utils.mjs";
+import { T as generateIV, b as decrypt$1, o as encryptKey, x as encrypt$1 } from "../_chunks/_crypto.mjs";
+import { getJWKsFromSet, importKey, unwrapKey } from "./jwk.mjs";
 //#region src/core/jwe.ts
-var jwe_exports = /* @__PURE__ */ __exportAll({
-	decrypt: () => decrypt,
-	encrypt: () => encrypt
-});
 async function encrypt(payload, key, options = {}) {
-	const { protectedHeader: additionalProtectedHeader, cek: providedCek, contentEncryptionIV: providedContentIV, keyManagementIV, p2s, p2c, ecdh } = options;
+	const { protectedHeader: userHeader, cek: providedCek, contentEncryptionIV: providedContentIV, keyManagementIV, p2s, p2c, ecdh } = options;
 	let { alg, enc } = options;
 	if (!alg) {
 		if (typeof key === "string" || key instanceof Uint8Array) alg = "PBES2-HS256+A128KW";
 		else if (isJWK(key)) alg = key.alg === "A128GCM" || key.alg === "A192GCM" || key.alg === "A256GCM" ? `${key.alg}KW` : key.alg;
 	}
 	if (!alg) throw new TypeError("JWE \"alg\" (Key Management Algorithm) must be provided in options or inferable from the key");
-	if (!enc) enc = isJWK(key) && "enc" in key ? key.enc : "A128GCM";
+	if (!enc) if (alg === "dir") {
+		enc = isJWK(key) && "enc" in key ? key.enc : void 0;
+		if (!enc) throw new TypeError("JWE \"enc\" must be provided when alg is \"dir\"");
+	} else enc = isJWK(key) && "enc" in key ? key.enc : "A128GCM";
 	const jweKeyManagementParams = {};
 	if (keyManagementIV) jweKeyManagementParams.iv = keyManagementIV;
 	if (p2s) jweKeyManagementParams.p2s = p2s;
 	else if (alg?.startsWith("PBES2")) jweKeyManagementParams.p2s = randomBytes(16);
 	if (p2c) jweKeyManagementParams.p2c = p2c;
-	else if (alg?.startsWith("PBES2")) jweKeyManagementParams.p2c = 2048;
+	else if (alg?.startsWith("PBES2")) jweKeyManagementParams.p2c = 6e5;
 	if (ecdh?.partyUInfo) jweKeyManagementParams.apu = ecdh.partyUInfo;
 	if (ecdh?.partyVInfo) jweKeyManagementParams.apv = ecdh.partyVInfo;
 	if (ecdh?.ephemeralKey) {
@@ -30,21 +29,14 @@ async function encrypt(payload, key, options = {}) {
 	}
 	const wrappingKeyMaterial = await importKey(key, alg);
 	const { cek: finalCek, encryptedKey: jweEncryptedKey, parameters: keyManagementHeaderParams } = await encryptKey(alg, enc, wrappingKeyMaterial, providedCek, jweKeyManagementParams);
-	const jweProtectedHeader = {
-		...additionalProtectedHeader,
-		...keyManagementHeaderParams,
-		alg,
-		enc
-	};
-	if (isJWK(key) && key.kid) jweProtectedHeader.kid = key.kid;
-	const protectedHeader = applyTypCtyDefaults(jweProtectedHeader, payload);
+	const protectedHeader = _buildJWEHeader(alg, enc, key, userHeader, keyManagementHeaderParams, payload);
 	const plaintextBytes = getPlaintextBytes(computeJwtTimeClaims(payload, protectedHeader.typ, options.expiresIn, options.currentDate) || payload);
 	const protectedHeaderEncoded = base64UrlEncode(JSON.stringify(protectedHeader));
 	const aadBytes = textEncoder.encode(protectedHeaderEncoded);
 	const contentIVBytes = providedContentIV ?? generateIV(enc);
 	const { ciphertext: contentCiphertext, tag: contentAuthTag, iv: actualContentIV } = await encrypt$1(enc, plaintextBytes, finalCek, contentIVBytes, aadBytes);
-	if (!actualContentIV) throw new Error("Content encryption IV was not generated or returned.");
-	if (!contentAuthTag) throw new Error("Content encryption auth tag was not generated or returned.");
+	if (!actualContentIV) throw new JWTError("Content encryption IV was not generated or returned.", "ERR_JWE_INVALID");
+	if (!contentAuthTag) throw new JWTError("Content encryption auth tag was not generated or returned.", "ERR_JWE_INVALID");
 	return [
 		protectedHeaderEncoded,
 		jweEncryptedKey ? base64UrlEncode(jweEncryptedKey) : "",
@@ -55,28 +47,28 @@ async function encrypt(payload, key, options = {}) {
 }
 async function decrypt(jwe, key, options = {}) {
 	const parts = jwe.split(".");
-	if (parts.length !== 5) throw new Error("Invalid JWE: Must contain five sections (RFC7516, section-3).");
+	if (parts.length !== 5) throw new JWTError("Invalid JWE: Must contain five sections (RFC7516, section-3).", "ERR_JWE_INVALID");
 	const [protectedHeaderEncoded, encryptedKeyEncoded, ivEncoded, ciphertextEncoded, authTagEncoded] = parts;
 	let protectedHeader;
 	try {
 		const protectedHeaderJson = base64UrlDecode(protectedHeaderEncoded);
 		protectedHeader = sanitizeObject(JSON.parse(protectedHeaderJson));
 	} catch {
-		throw new Error("Invalid JWE: Protected header could not be decoded.");
+		throw new JWTError("Invalid JWE: Protected header could not be decoded.", "ERR_JWE_INVALID");
 	}
-	if (!protectedHeader || typeof protectedHeader !== "object" || !protectedHeader.alg || !protectedHeader.enc) throw new Error("Invalid JWE: Protected header must be an object with \"alg\" and \"enc\" properties.");
+	if (!protectedHeader || typeof protectedHeader !== "object" || !protectedHeader.alg || !protectedHeader.enc) throw new JWTError("Invalid JWE: Protected header must be an object with \"alg\" and \"enc\" properties.", "ERR_JWE_INVALID");
 	const alg = protectedHeader.alg;
 	const enc = protectedHeader.enc;
-	if (options?.algorithms && !options.algorithms.includes(alg)) throw new Error(`Key management algorithm not allowed: ${alg}`);
-	if (options?.encryptionAlgorithms && !options.encryptionAlgorithms.includes(enc)) throw new Error(`Content encryption algorithm not allowed: ${enc}`);
-	const unwrappingKey = await importKey(typeof key === "function" ? await key(protectedHeader, jwe) : key, alg);
+	if (options?.algorithms && !options.algorithms.includes(alg)) throw new JWTError(`Key management algorithm not allowed: ${alg}`, "ERR_JWE_ALG_NOT_ALLOWED");
+	if (options?.encryptionAlgorithms && !options.encryptionAlgorithms.includes(enc)) throw new JWTError(`Content encryption algorithm not allowed: ${enc}`, "ERR_JWE_ALG_NOT_ALLOWED");
+	const rawKeyMaterial = typeof key === "function" ? await key(protectedHeader, jwe) : key;
 	const encryptedKeyBytes = base64UrlDecode(encryptedKeyEncoded, false);
 	const contentIVBytes = base64UrlDecode(ivEncoded, false);
 	const contentAuthTagBytes = base64UrlDecode(authTagEncoded, false);
 	const ciphertextBytes = base64UrlDecode(ciphertextEncoded, false);
 	const unwrapKeyOpts = {
 		enc,
-		returnAs: enc.includes("GCM"),
+		format: enc.includes("GCM") ? "cryptokey" : "raw",
 		keyUsage: options?.keyUsage || ["decrypt"]
 	};
 	if (protectedHeader.iv) unwrapKeyOpts.iv = protectedHeader.iv;
@@ -88,11 +80,34 @@ async function decrypt(jwe, key, options = {}) {
 	if (protectedHeader.apv) unwrapKeyOpts.apv = protectedHeader.apv;
 	if (options?.unwrappedKeyAlgorithm) unwrapKeyOpts.unwrappedKeyAlgorithm = options.unwrappedKeyAlgorithm;
 	if (options?.extractable) unwrapKeyOpts.extractable = options.extractable;
-	const cek = await unwrapKey(alg, encryptedKeyBytes, unwrappingKey, unwrapKeyOpts);
 	const aadBytes = textEncoder.encode(protectedHeaderEncoded);
-	const payload = decodePayloadFromBytes(await decrypt$1(enc, cek, ciphertextBytes, contentIVBytes, contentAuthTagBytes, aadBytes), protectedHeader, options?.forceUint8Array);
-	if (protectedHeader.crit || options?.critical?.length || options?.requiredHeaders?.length) validateCriticalHeadersJWE(protectedHeader, [...options?.critical || [], ...options?.requiredHeaders || []]);
-	if (payload && typeof payload === "object" && options.validateJWT !== false && (options.validateJWT === true || protectedHeader.typ?.toLowerCase().includes("jwt")) && !options.forceUint8Array && !(payload instanceof Uint8Array)) validateJwtClaims(payload, options);
+	let cek;
+	let plaintextBytes;
+	if (isJWKSet(rawKeyMaterial)) {
+		const candidates = getJWKsFromSet(rawKeyMaterial, _buildJWESetFilter(protectedHeader));
+		if (candidates.length === 0) throw new JWTError(`No key found in JWK Set${protectedHeader.kid ? ` with kid "${protectedHeader.kid}"` : ""}.`, "ERR_JWK_KEY_NOT_FOUND");
+		let decrypted = false;
+		for (const candidate of candidates) try {
+			const candidateCek = await unwrapKey(alg, encryptedKeyBytes, await importKey(candidate, alg), unwrapKeyOpts);
+			plaintextBytes = await decrypt$1(enc, candidateCek, ciphertextBytes, contentIVBytes, contentAuthTagBytes, aadBytes);
+			cek = candidateCek;
+			decrypted = true;
+			break;
+		} catch {}
+		if (!decrypted) throw new JWTError("JWE decryption failed.", "ERR_JWE_DECRYPTION_FAILED");
+	} else {
+		const unwrappingKey = await importKey(rawKeyMaterial, alg);
+		try {
+			cek = await unwrapKey(alg, encryptedKeyBytes, unwrappingKey, unwrapKeyOpts);
+			plaintextBytes = await decrypt$1(enc, cek, ciphertextBytes, contentIVBytes, contentAuthTagBytes, aadBytes);
+		} catch (error_) {
+			if (error_ instanceof JWTError) throw error_;
+			throw new JWTError("JWE decryption failed.", "ERR_JWE_DECRYPTION_FAILED", error_);
+		}
+	}
+	const payload = decodePayloadFromBytes(plaintextBytes, protectedHeader, options?.forceUint8Array);
+	if (protectedHeader.crit || options?.recognizedHeaders?.length) validateCriticalHeadersJWE(protectedHeader, options?.recognizedHeaders);
+	if (payload && typeof payload === "object" && options.validateClaims !== false && (options.validateClaims === true || protectedHeader.typ?.toLowerCase().includes("jwt")) && !options.forceUint8Array && !(payload instanceof Uint8Array)) validateJwtClaims(payload, options);
 	const result = {
 		payload,
 		protectedHeader
@@ -128,5 +143,19 @@ function parseEphemeralKey(ephemeralKey) {
 		epkPrivateKey
 	};
 }
+function _buildJWESetFilter(header) {
+	const { kid, alg } = header;
+	return (k) => (!kid || k.kid === kid) && (!k.alg || k.alg === alg);
+}
+function _buildJWEHeader(alg, enc, key, userHeader, keyManagementParams, payload) {
+	const safeHeader = sanitizeObject(userHeader);
+	return applyTypCtyDefaults({
+		...isJWK(key) && key.kid ? { kid: key.kid } : {},
+		...safeHeader,
+		...keyManagementParams,
+		alg,
+		enc
+	}, payload);
+}
 //#endregion
-export { encrypt as n, jwe_exports as r, decrypt as t };
+export { JWTError, decrypt, encrypt, isJWTError };

package/dist/core/jwk.d.mts

@@ -0,0 +1,231 @@
+import { $ as JWK_OKP_SIGN, A as JWK, B as JWK_AES_GCM_KW, C as DeriveKeyOptions, D as GenerateKeyAlgorithm, E as GenerateJWKReturn, F as JWKPEMAlgorithm, G as JWK_ECDH_ES, H as JWK_Asymmetric, I as JWKParameters, J as JWK_EC_Public, K as JWK_ECDSA, L as JWKSet, M as JWKCacheAdapter, N as JWKLookupFunction, O as GenerateKeyOptions, P as JWKLookupFunctionHeader, Q as JWK_OKP_Public, R as JWK_AES_CBC_HMAC, S as ContentEncryptionAlgorithm, T as GenerateJWKOptions, U as JWK_Asymmetric_Algorithm, V as JWK_AES_KW, W as JWK_EC, X as JWK_OKP, Y as JWK_HMAC, Z as JWK_OKP_Private, at as JWK_RSA_ENC, b as JoseHeaderParameters, ct as JWK_RSA_Public, dt as JWK_Symmetric_Algorithm, et as JWK_PBES2, ft as JWK_oct, gt as WrapKeyResult, ht as WrapKeyOptions, it as JWK_RSA, j as JWKAlgorithm, k as GenerateKeyReturn, lt as JWK_RSA_SIGN, mt as UnwrapKeyOptions, nt as JWK_Private, ot as JWK_RSA_PSS, pt as KeyManagementAlgorithm, q as JWK_EC_Private, rt as JWK_Public, st as JWK_RSA_Private, tt as JWK_Pair, ut as JWK_Symmetric, w as DeriveKeyReturn, x as CompositeKey, z as JWK_AES_GCM } from "../_chunks/index.mjs";
+import { i as isJWTError, n as JWTErrorCauseMap, r as JWTErrorCode, t as JWTError } from "../_chunks/error.mjs";
+
+//#region src/core/jwk.d.ts
+/**
+* Generates a cryptographic key for the specified algorithm.
+*
+* @param alg The JWA algorithm identifier (e.g., "HS256", "RS256", "A128GCM").
+* @param options Configuration options for key generation.
+* @returns A Promise resolving to the generated key (CryptoKey, CryptoKeyPair, or Uint8Array) or its JWK representation.
+*/
+declare function generateKey<TAlg extends GenerateKeyAlgorithm, TOptions extends GenerateKeyOptions>(alg: TAlg, options?: TOptions): Promise<GenerateKeyReturn<TAlg, TOptions>>;
+/**
+* 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.
+*/
+declare function generateJWK<TAlg extends GenerateKeyAlgorithm>(alg: TAlg, jwkParams?: Omit<JWKParameters, "alg" | "kty" | "key_ops" | "ext">, options?: GenerateJWKOptions): Promise<GenerateJWKReturn<TAlg>>;
+/**
+* Derives a key 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 options Configuration options including salt and iterations.
+* @returns A Promise resolving to the derived key (CryptoKey) or its JWK_oct representation.
+*/
+declare function deriveKeyFromPassword<TAlg extends JWK_PBES2, TOptions extends DeriveKeyOptions>(password: string | Uint8Array<ArrayBuffer>, alg: TAlg, options: TOptions): Promise<DeriveKeyReturn<TOptions>>;
+/**
+* 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).
+*/
+declare function deriveJWKFromPassword(password: string | Uint8Array<ArrayBuffer>, alg: JWK_PBES2, options: Omit<DeriveKeyOptions, "toJWK">, jwkParams?: Omit<JWKParameters, "alg" | "kty" | "key_ops" | "ext">): Promise<JWK_oct>;
+/**
+* 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.
+*/
+declare class WeakMapJWKCache implements JWKCacheAdapter {
+  private readonly _map;
+  get(jwk: JWK, alg: string): CryptoKey | undefined;
+  set(jwk: JWK, alg: string, key: CryptoKey): void;
+}
+/**
+* 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),
+* });
+* ```
+*/
+declare function configureJWKCache(cache: JWKCacheAdapter | false): void;
+/**
+* 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.
+*/
+declare function clearJWKCache(): void;
+/**
+* Imports a key from various formats (CryptoKey, JWK, Uint8Array).
+*
+* - If `key` is a CryptoKey, it's returned directly.
+* - If `key` is a Uint8Array, it's returned directly.
+* - If `key` is a JWK_oct (symmetric key with 'k'), the raw key bytes are returned as Uint8Array.
+* - If `key` is any other JWK type (asymmetric), the `alg` parameter is required, and a CryptoKey is returned.
+*
+* @param key The key to import.
+* @param alg The algorithm hint, required when importing asymmetric JWKs.
+* @returns A Promise resolving to the imported key as CryptoKey or Uint8Array.
+*/
+declare function importKey(key: string): Promise<Uint8Array<ArrayBuffer>>;
+declare function importKey(key: Uint8Array<ArrayBuffer>): Promise<Uint8Array<ArrayBuffer>>;
+declare function importKey(key: CryptoKey): Promise<CryptoKey>;
+declare function importKey(key: JWK_oct): Promise<Uint8Array<ArrayBuffer>>;
+declare function importKey(key: JWK_oct, options: {
+  asCryptoKey: true; /** Algorithm to import the key as (e.g. `{ name: "AES-GCM", length: 256 }`). */
+  algorithm: Parameters<typeof crypto.subtle.importKey>[2]; /** Key usages for the resulting CryptoKey. */
+  usage: KeyUsage[]; /** Mark the key as extractable. Defaults to `false`. */
+  extractable?: boolean;
+}): Promise<CryptoKey>;
+declare function importKey(key: CryptoKey | JWK | Uint8Array<ArrayBuffer> | string, alg?: string): Promise<CryptoKey | Uint8Array<ArrayBuffer>>;
+/**
+* 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.
+*/
+declare function exportKey<T extends JWK>(key: CryptoKey, jwk?: Partial<JWK>): Promise<T>;
+/**
+* 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.).
+*/
+declare function wrapKey(alg: KeyManagementAlgorithm, keyToWrap: CryptoKey | Uint8Array<ArrayBuffer>, wrappingKey: CryptoKey | JWK | string | Uint8Array<ArrayBuffer>, options?: WrapKeyOptions): Promise<WrapKeyResult>;
+/**
+* Unwraps a Content Encryption Key (CEK) using the specified algorithm and unwrapping key.
+*
+* @param alg The JWA key management algorithm (e.g., "A128KW", "RSA-OAEP", "PBES2-HS256+A128KW").
+* @param wrappedKey The wrapped key (ciphertext) as Uint8Array.
+* @param unwrappingKey The key used to unwrap the CEK (CryptoKey, JWK, or password string/Uint8Array for PBES2).
+* @param options Additional options required by certain algorithms (e.g., iv, tag, p2s, p2c, epk).
+* @returns A Promise resolving to the unwrapped key (CEK) as a CryptoKey or Uint8Array.
+*/
+declare function unwrapKey(alg: KeyManagementAlgorithm, wrappedKey: Uint8Array<ArrayBuffer>, unwrappingKey: CryptoKey | JWK | string | Uint8Array<ArrayBuffer>, options: UnwrapKeyOptions & {
+  format: "raw";
+}): Promise<Uint8Array<ArrayBuffer>>;
+declare function unwrapKey(alg: KeyManagementAlgorithm, wrappedKey: Uint8Array<ArrayBuffer>, unwrappingKey: CryptoKey | JWK | string | Uint8Array<ArrayBuffer>, options?: UnwrapKeyOptions & {
+  format?: "cryptokey";
+}): Promise<CryptoKey>;
+declare function unwrapKey(alg: KeyManagementAlgorithm, wrappedKey: Uint8Array<ArrayBuffer>, unwrappingKey: CryptoKey | JWK | string | Uint8Array<ArrayBuffer>, options: UnwrapKeyOptions): Promise<CryptoKey | Uint8Array<ArrayBuffer>>;
+/**
+* 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.
+*/
+declare function importFromPEM<T extends JWK>(pem: string, pemType: "pkcs8" | "spki" | "x509", alg: JWKPEMAlgorithm, options?: {
+  /** Passed to `crypto.subtle.importKey`. Defaults to `false` for private keys, `true` otherwise. */extractable?: boolean; /** Additional JWK properties merged into the exported key (e.g. `kid`). */
+  jwkParams?: Omit<JWKParameters, "alg" | "kty" | "key_ops" | "ext">;
+}): Promise<T>;
+/**
+* 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.
+*/
+declare function exportToPEM(jwk: JWK, pemFormat: "pkcs8" | "spki", algForCryptoKeyImport?: JWKPEMAlgorithm): Promise<string>;
+/**
+* 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.
+*/
+declare function deriveSharedSecret(publicKey: CryptoKey | JWK_EC_Public, privateKey: CryptoKey | JWK_EC_Private, alg: JWK_ECDH_ES | ContentEncryptionAlgorithm, options?: {
+  /** Override the derived key length in bits. Defaults to the standard length for `alg`. */keyLength?: number; /** Agreement PartyUInfo (apu). */
+  partyUInfo?: Uint8Array<ArrayBuffer>; /** Agreement PartyVInfo (apv). */
+  partyVInfo?: Uint8Array<ArrayBuffer>;
+}): Promise<Uint8Array<ArrayBuffer>>;
+/**
+* @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.
+*/
+declare function getJWKFromSet(jwkSet: JWKSet, kidOrProtectedHeader: string | (JoseHeaderParameters & {
+  alg?: string;
+  kty?: string;
+})): JWK;
+/**
+* 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.
+*/
+declare function getJWKsFromSet(jwkSet: JWKSet, filter?: (jwk: JWK) => boolean): JWK[];
+//#endregion
+export { CompositeKey, ContentEncryptionAlgorithm, DeriveKeyOptions, DeriveKeyReturn, GenerateJWKOptions, GenerateJWKReturn, GenerateKeyAlgorithm, GenerateKeyOptions, GenerateKeyReturn, JWK, JWKAlgorithm, JWKCacheAdapter, JWKLookupFunction, JWKLookupFunctionHeader, JWKPEMAlgorithm, JWKParameters, JWKSet, JWK_AES_CBC_HMAC, JWK_AES_GCM, JWK_AES_GCM_KW, JWK_AES_KW, JWK_Asymmetric, JWK_Asymmetric_Algorithm, JWK_EC, JWK_ECDH_ES, JWK_ECDSA, JWK_EC_Private, JWK_EC_Public, JWK_HMAC, JWK_OKP, JWK_OKP_Private, JWK_OKP_Public, JWK_OKP_SIGN, JWK_PBES2, JWK_Pair, JWK_Private, JWK_Public, JWK_RSA, JWK_RSA_ENC, JWK_RSA_PSS, JWK_RSA_Private, JWK_RSA_Public, JWK_RSA_SIGN, JWK_Symmetric, JWK_Symmetric_Algorithm, JWK_oct, JWTError, type JWTErrorCauseMap, type JWTErrorCode, KeyManagementAlgorithm, UnwrapKeyOptions, WeakMapJWKCache, WrapKeyOptions, WrapKeyResult, clearJWKCache, configureJWKCache, deriveJWKFromPassword, deriveKeyFromPassword, deriveSharedSecret, exportKey, exportToPEM, generateJWK, generateKey, getJWKFromSet, getJWKsFromSet, importFromPEM, importKey, isJWTError, unwrapKey, wrapKey };