unjwt 0.6.1 → 0.7.0

package/dist/core/jwe.mjs

@@ -1,161 +1,3 @@
-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
-async function encrypt(payload, key, 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) 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 = 6e5;
-	if (ecdh?.partyUInfo) jweKeyManagementParams.apu = ecdh.partyUInfo;
-	if (ecdh?.partyVInfo) jweKeyManagementParams.apv = ecdh.partyVInfo;
-	if (ecdh?.ephemeralKey) {
-		const { epk, epkPrivateKey } = parseEphemeralKey(ecdh.ephemeralKey);
-		jweKeyManagementParams.epk = epk;
-		jweKeyManagementParams.epkPrivateKey = epkPrivateKey;
-	}
-	const wrappingKeyMaterial = await importKey(key, alg);
-	const { cek: finalCek, encryptedKey: jweEncryptedKey, parameters: keyManagementHeaderParams } = await encryptKey(alg, enc, wrappingKeyMaterial, providedCek, jweKeyManagementParams);
-	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 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) : "",
-		base64UrlEncode(actualContentIV),
-		base64UrlEncode(contentCiphertext),
-		base64UrlEncode(contentAuthTag)
-	].join(".");
-}
-async function decrypt(jwe, key, options = {}) {
-	const parts = jwe.split(".");
-	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 JWTError("Invalid JWE: Protected header could not be decoded.", "ERR_JWE_INVALID");
-	}
-	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 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,
-		format: enc.includes("GCM") ? "cryptokey" : "raw",
-		keyUsage: options?.keyUsage || ["decrypt"]
-	};
-	if (protectedHeader.iv) unwrapKeyOpts.iv = protectedHeader.iv;
-	if (protectedHeader.tag) unwrapKeyOpts.tag = protectedHeader.tag;
-	if (protectedHeader.p2s) unwrapKeyOpts.p2s = protectedHeader.p2s;
-	if (protectedHeader.p2c) unwrapKeyOpts.p2c = protectedHeader.p2c;
-	if (protectedHeader.epk) unwrapKeyOpts.epk = protectedHeader.epk;
-	if (protectedHeader.apu) unwrapKeyOpts.apu = protectedHeader.apu;
-	if (protectedHeader.apv) unwrapKeyOpts.apv = protectedHeader.apv;
-	if (options?.unwrappedKeyAlgorithm) unwrapKeyOpts.unwrappedKeyAlgorithm = options.unwrappedKeyAlgorithm;
-	if (options?.extractable) unwrapKeyOpts.extractable = options.extractable;
-	const aadBytes = textEncoder.encode(protectedHeaderEncoded);
-	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
-	};
-	if (options.returnCek) {
-		result.cek = isCryptoKey(cek) ? new Uint8Array(await crypto.subtle.exportKey("raw", cek)) : cek;
-		result.aad = aadBytes;
-	}
-	return result;
-}
-function parseEphemeralKey(ephemeralKey) {
-	let epk;
-	let epkPrivateKey;
-	if (isCryptoKeyPair(ephemeralKey)) {
-		epk = ephemeralKey.publicKey;
-		epkPrivateKey = ephemeralKey.privateKey;
-	} else if (typeof ephemeralKey === "object" && ephemeralKey !== null && "publicKey" in ephemeralKey && "privateKey" in ephemeralKey) {
-		const candidate = ephemeralKey;
-		if (!candidate.publicKey || !candidate.privateKey) throw new TypeError("ECDH-ES custom ephemeral key must include both publicKey and privateKey.");
-		epk = candidate.publicKey;
-		epkPrivateKey = candidate.privateKey;
-	} else if (isCryptoKey(ephemeralKey)) {
-		if (ephemeralKey.type !== "private") throw new TypeError("ECDH-ES custom ephemeral CryptoKey must include private key material.");
-		epk = ephemeralKey;
-		epkPrivateKey = ephemeralKey;
-	} else if (isJWK(ephemeralKey)) {
-		if (!("d" in ephemeralKey) || typeof ephemeralKey.d !== "string") throw new TypeError("ECDH-ES custom ephemeral JWK must include private parameter \"d\".");
-		epk = ephemeralKey;
-		epkPrivateKey = ephemeralKey;
-	} else throw new TypeError("Unsupported ECDH-ES ephemeral key material provided in options.");
-	return {
-		epk,
-		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 { JWTError, decrypt, encrypt, isJWTError };
+import { D as JWTError, O as isJWTError } from "../_chunks/utils.mjs";
+import { a as generalToFlattened, i as encryptMulti, n as encrypt, r as decryptMulti, t as decrypt } from "../_chunks/jwe.mjs";
+export { JWTError, decrypt, decryptMulti, encrypt, encryptMulti, generalToFlattened, isJWTError };

package/dist/core/jwk.d.mts

@@ -1,24 +1,91 @@
-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
+import { $ as JWKAlgorithm, At as JWK_RSA_Public, Ct as JWK_Pair, Dt as JWK_RSA_ENC, Et as JWK_RSA, F as JWTErrorCauseMap, Ft as KeyManagementAlgorithm, G as DeriveKeyOptions, H as JoseHeaderParameters, I as JWTErrorCode, It as UnwrapKeyOptions, J as GenerateJWKReturn, K as DeriveKeyReturn, L as isJWTError, Lt as WrapKeyOptions, Mt as JWK_Symmetric, Nt as JWK_Symmetric_Algorithm, Ot as JWK_RSA_PSS, P as JWTError, Pt as JWK_oct, Q as JWK, Rt as WrapKeyResult, St as JWK_PBES2, Tt as JWK_Public, U as CompositeKey, W as ContentEncryptionAlgorithm, X as GenerateKeyOptions, Y as GenerateKeyAlgorithm, Z as GenerateKeyReturn, _t as JWK_HMAC, at as JWKSet, bt as JWK_OKP_Public, ct as JWK_AES_GCM_KW, dt as JWK_Asymmetric_Algorithm, et as JWKCacheAdapter, ft as JWK_EC, gt as JWK_EC_Public, ht as JWK_EC_Private, it as JWKParameters, jt as JWK_RSA_SIGN, kt as JWK_RSA_Private, lt as JWK_AES_KW, mt as JWK_ECDSA, nt as JWKLookupFunctionHeader, ot as JWK_AES_CBC_HMAC, pt as JWK_ECDH_ES, q as GenerateJWKOptions, rt as JWKPEMAlgorithm, st as JWK_AES_GCM, tt as JWKLookupFunction, ut as JWK_Asymmetric, vt as JWK_OKP, wt as JWK_Private, xt as JWK_OKP_SIGN, yt as JWK_OKP_Private } from "../_chunks/index.mjs";
 /**
-* Generates a cryptographic key for the specified algorithm.
+* Generates a cryptographic key for the specified JWA 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.
+* The return type is narrowed by `alg` and `options.toJWK`. When `toJWK` is not set
+* (or is `false`):
+*
+* - **Symmetric algorithms** (`HS*`, `A*KW`, `A*GCM`, `A*GCMKW`) → `CryptoKey`. The key
+*   is imported with Web Crypto usages derived from the algorithm (e.g. `["sign", "verify"]`
+*   for HMAC, `["wrapKey", "unwrapKey"]` for AES-KW, `["encrypt", "decrypt"]` for AES-GCM).
+* - **AES-CBC + HMAC composites** (`A128CBC-HS256`, `A192CBC-HS384`, `A256CBC-HS512`) →
+*   `Uint8Array`. These keys are returned as raw bytes because the composite layout
+*   (AES key ∥ HMAC key) is not directly importable via `crypto.subtle.importKey`. They
+*   are split internally during encrypt/decrypt.
+* - **Asymmetric algorithms** (`RS*`, `PS*`, `ES*`, `RSA-OAEP*`, `Ed25519`, `EdDSA`,
+*   `ECDH-ES*`) → `CryptoKeyPair`.
+*
+* When `options.toJWK` is `true`, the same call returns a JWK / JWK pair instead, with
+* a freshly generated `kid` attached (use {@link generateJWK} to customise `kid`,
+* `use`, etc.). Composite AES-CBC+HMAC keys are serialised to a single `JWK_oct` and
+* re-split internally on use.
+*
+* PBES2 is not a key-generation algorithm — use {@link deriveKeyFromPassword} or
+* {@link deriveJWKFromPassword} instead.
+*
+* @param alg The JWA algorithm identifier (e.g. `"HS256"`, `"RS256"`, `"A128GCM"`,
+*            `"A256CBC-HS512"`). PBES2, `"dir"`, and `"none"` are not accepted.
+* @param options
+*   - `toJWK?` — when `true`, return JWK / JWK pair instead of `CryptoKey` / `CryptoKeyPair`.
+*   - `extractable?` — forwarded to `crypto.subtle.generateKey`. Defaults to `true`.
+*   - `keyUsage?` — override the default usages derived from `alg`.
+*   - `modulusLength?` — RSA only; defaults to `2048`.
+*   - `publicExponent?` — RSA only; defaults to `0x010001`.
+*   - `namedCurve?` — EC and OKP only; defaults to `"P-256"` for EC and `"Ed25519"` for OKP.
+*
+* @example
+* ```ts
+* // HS256 → CryptoKey
+* const hmac = await generateKey("HS256");
+*
+* // A256CBC-HS512 → Uint8Array (composite key)
+* const cek = await generateKey("A256CBC-HS512");
+*
+* // RS256 → CryptoKeyPair
+* const rsa = await generateKey("RS256", { modulusLength: 2048 });
+*
+* // As JWK pair
+* const { privateKey, publicKey } = await generateKey("ES256", { toJWK: true });
+* ```
 */
 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.
+* Generates a ready-to-use JWK (or JWK pair) for the specified algorithm.
+*
+* Always returns JWK form with a `kid` attached — auto-generated via
+* `crypto.randomUUID()` when not supplied. For a `CryptoKey` / `CryptoKeyPair`
+* result instead, use {@link generateKey}. PBES2 is not a key-generation
+* algorithm — use {@link deriveJWKFromPassword}.
+*
+* Composite AES-CBC+HMAC keys (`A128CBC-HS256`, `A192CBC-HS384`, `A256CBC-HS512`)
+* are serialised to a single `JWK_oct` and re-split internally on use.
 *
-* @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.
+* @param alg The JWA algorithm identifier (e.g. `"HS256"`, `"RS256"`, `"ES256"`,
+*            `"A128GCM"`, `"A256CBC-HS512"`). PBES2, `"dir"`, and `"none"` are
+*            not accepted.
+* @param options
+*   - `extractable?` — forwarded to `crypto.subtle.generateKey`. Defaults to `true`.
+*   - `keyUsage?` — override the default usages derived from `alg`.
+*   - `modulusLength?` — RSA only; defaults to `2048`.
+*   - `publicExponent?` — RSA only; defaults to `0x010001`.
+*   - `namedCurve?` — EC and OKP only; defaults to `"P-256"` for EC and `"Ed25519"` for OKP.
+*   - JWK metadata (`kid`, `use`, `x5c`, `x5t`, `x5t#S256`, `x5u`) is merged onto the
+*     result. `alg`, `kty`, `key_ops`, and `ext` are managed by the library and cannot
+*     be overridden here.
+*
+* @example
+* ```ts
+* // HS256 → JWK_oct
+* const hmac = await generateJWK("HS256");
+*
+* // RS256 → { privateKey: JWK_RSA_Private; publicKey: JWK_RSA_Public }
+* const rsa = await generateJWK("RS256", { modulusLength: 2048, kid: "rsa-1" });
+*
+* // ES256 with explicit metadata
+* const { privateKey, publicKey } = await generateJWK("ES256", { kid: "ec-1", use: "sig" });
+* ```
 */
-declare function generateJWK<TAlg extends GenerateKeyAlgorithm>(alg: TAlg, jwkParams?: Omit<JWKParameters, "alg" | "kty" | "key_ops" | "ext">, options?: GenerateJWKOptions): Promise<GenerateJWKReturn<TAlg>>;
+declare function generateJWK<TAlg extends GenerateKeyAlgorithm>(alg: TAlg, options?: GenerateJWKOptions & Omit<JWKParameters, "alg" | "kty" | "key_ops" | "ext">): Promise<GenerateJWKReturn<TAlg>>;
 /**
 * Derives a key from a password using PBKDF2 as specified by PBES2 algorithms.
 *
@@ -29,15 +96,25 @@ declare function generateJWK<TAlg extends GenerateKeyAlgorithm>(alg: TAlg, jwkPa
 */
 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.
+* Derives a `JWK_oct` from a password using PBKDF2 as specified by PBES2
+* (RFC 7518 §4.8). The resulting JWK's `alg` is the underlying AES-KW variant
+* (`A128KW` / `A192KW` / `A256KW`), ready to use with {@link wrapKey} /
+* {@link unwrapKey}.
 *
-* @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).
+* For a `CryptoKey` result without JWK metadata, use {@link deriveKeyFromPassword}.
+*
+* @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
+*   - `salt` — PBKDF2 salt input (`p2s`). Must be at least 8 octets (RFC 7518 §4.8.1.1).
+*   - `iterations` — PBKDF2 iteration count (`p2c`). Must be a positive integer.
+*   - `keyUsage?` — defaults to `["wrapKey", "unwrapKey"]`.
+*   - `extractable?` — forwarded to `crypto.subtle.importKey`. Defaults to `false`.
+*   - JWK metadata (`kid`, `use`, `x5c`, `x5t`, `x5t#S256`, `x5u`) is merged onto the
+*     result. `alg`, `kty`, `key_ops`, and `ext` are managed by the library and cannot
+*     be overridden here.
 */
-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>;
+declare function deriveJWKFromPassword(password: string | Uint8Array<ArrayBuffer>, alg: JWK_PBES2, options: Omit<DeriveKeyOptions, "toJWK"> & Omit<JWKParameters, "alg" | "kty" | "key_ops" | "ext">): Promise<JWK_oct>;
 /**
 * Default JWK import cache backed by a WeakMap.
 *
@@ -86,14 +163,21 @@ 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.
+* - 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), an algorithm hint is required (positional or via options)
+*   and a `CryptoKey` is returned.
+*
+* ### `expect` option (asymmetric only)
+*
+* Pass `expect: "public"` or `expect: "private"` to validate the caller's intent against the key's
+* shape before the import. A private JWK passed with `expect: "public"` throws `ERR_JWK_INVALID`
+* instead of silently importing the private material. Callers who deliberately want to drop private
+* fields can do so themselves — no silent stripping.
 *
-* @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.
+* `expect` is a no-op for symmetric (`oct`) JWKs and for `CryptoKey` instances whose
+* `algorithm.type` is `"secret"`.
 */
 declare function importKey(key: string): Promise<Uint8Array<ArrayBuffer>>;
 declare function importKey(key: Uint8Array<ArrayBuffer>): Promise<Uint8Array<ArrayBuffer>>;
@@ -105,6 +189,10 @@ declare function importKey(key: JWK_oct, options: {
   usage: KeyUsage[]; /** Mark the key as extractable. Defaults to `false`. */
   extractable?: boolean;
 }): Promise<CryptoKey>;
+declare function importKey(key: CryptoKey | JWK | Uint8Array<ArrayBuffer> | string, options: {
+  /** Algorithm hint. Required when `key.alg` is absent on an asymmetric JWK. */alg?: string; /** Reject on shape mismatch instead of silently importing. */
+  expect?: "public" | "private";
+}): Promise<CryptoKey | Uint8Array<ArrayBuffer>>;
 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.
@@ -113,17 +201,19 @@ declare function importKey(key: CryptoKey | JWK | Uint8Array<ArrayBuffer> | stri
 * @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>;
+declare function exportKey<T extends JWK>(key: CryptoKey, jwkParams?: Omit<JWKParameters, "alg" | "kty" | "key_ops" | "ext">): Promise<T>;
 /**
 * Wraps a Content Encryption Key (CEK) using the specified algorithm and wrapping key.
 *
+* The return shape is narrowed by `alg` — see {@link WrapKeyResult}.
+*
 * @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.).
+* @returns A Promise resolving to an alg-specific {@link WrapKeyResult}.
 */
-declare function wrapKey(alg: KeyManagementAlgorithm, keyToWrap: CryptoKey | Uint8Array<ArrayBuffer>, wrappingKey: CryptoKey | JWK | string | Uint8Array<ArrayBuffer>, options?: WrapKeyOptions): Promise<WrapKeyResult>;
+declare function wrapKey<TAlg extends KeyManagementAlgorithm>(alg: TAlg, keyToWrap: CryptoKey | Uint8Array<ArrayBuffer>, wrappingKey: CryptoKey | JWK | string | Uint8Array<ArrayBuffer>, options?: WrapKeyOptions): Promise<WrapKeyResult<TAlg>>;
 /**
 * Unwraps a Content Encryption Key (CEK) using the specified algorithm and unwrapping key.
 *
@@ -141,28 +231,95 @@ declare function unwrapKey(alg: KeyManagementAlgorithm, wrappedKey: Uint8Array<A
 }): 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.
+* Imports a PEM-encoded key and returns it as a JWK.
+*
+* The PEM type is inferred from the `-----BEGIN <X>-----` label:
+* - `PRIVATE KEY` → PKCS#8 private key (RFC 5208)
+* - `PUBLIC KEY`  → SubjectPublicKeyInfo public key (RFC 5280 §4.1.2.7)
+* - `CERTIFICATE` → X.509 certificate; its SPKI is extracted into the JWK and all cert metadata
+*                   (issuer, validity, extensions) is discarded — a JWK cannot represent it
+*
+* A caller can override the inference via `options.pemType`; the underlying label assertion
+* still runs, so a mismatched override (e.g. `pemType: "pkcs8"` on a SPKI body) throws
+* `ERR_JWK_INVALID` before any crypto work.
 *
 * @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.
+* @param alg The JWA algorithm identifier. Required for `crypto.subtle.importKey` to understand
+*            the key's intended algorithm and for setting the `alg` field on the resulting JWK.
+* @param options
+*   - `pemType?` — explicit PEM type; inferred from the label when omitted.
+*   - `extractable?` — forwarded to `crypto.subtle.importKey`. Defaults to `false` for private
+*     keys and `true` for public keys.
+*   - `jwkParams?` — additional JWK properties merged into the result (e.g. `kid`, `use`).
+*     `alg`, `kty`, `key_ops`, and `ext` are reserved and cannot be overridden here.
+* @throws `JWTError("ERR_JWK_INVALID")` if the PEM type cannot be inferred (no recognised label
+*         and no `options.pemType`), or if the label does not match the requested/inferred type.
+* @throws `JWTError("ERR_JWK_UNSUPPORTED")` if `options.pemType` is a value outside the supported set.
+*
+* @example
+* ```ts
+* // Inferred — label on the PEM drives selection.
+* const jwk = await importPEM(pemString, "RS256", { jwkParams: { kid: "rsa-1" } });
+*
+* // Explicit override.
+* const jwk2 = await importPEM(pemString, "RS256", { pemType: "x509" });
+* ```
+*/
+declare function importPEM<T extends JWK>(pem: string, alg: JWKPEMAlgorithm, options?: {
+  /** PEM type. Inferred from the PEM label when omitted. */pemType?: "pkcs8" | "spki" | "x509"; /** 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>;
+/**
+* @deprecated Use {@link importPEM} instead. `pemType` has moved into the options object and
+* is now inferred from the PEM label by default.
 */
 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`). */
+  extractable?: boolean;
   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.
+* The PEM format is inferred from the JWK shape:
+* - JWK with `d` (private component) → PKCS#8 (`-----BEGIN PRIVATE KEY-----`)
+* - JWK without `d` → SubjectPublicKeyInfo (`-----BEGIN PUBLIC KEY-----`)
+*
+* X.509 certificate export is intentionally not supported: a certificate carries metadata
+* (subject/issuer DNs, validity window, extensions) and a CA signature that a JWK cannot provide.
+* Producing a cert is a CA operation, not a key-format conversion.
+*
+* Symmetric `oct` JWKs cannot be exported to PEM — PKCS#8/SPKI are asymmetric-key formats.
+*
+* @param jwk The JWK to export. Must not be `kty: "oct"`.
+* @param options
+*   - `pemFormat?` — force the output format. Inferred from the JWK shape when omitted.
+*   - `alg?` — algorithm hint used only when `jwk.alg` is absent (both `kty: "RSA"` / `"EC"` /
+*     `"OKP"` JWKs need an algorithm to be round-tripped through `crypto.subtle.importKey`).
+* @throws `JWTError("ERR_JWK_UNSUPPORTED")` for `oct` JWKs, or an unrecognised `pemFormat`.
+* @throws `JWTError("ERR_JWK_INVALID")` if the JWK requires an `alg` hint that was not supplied,
+*         or if `pemFormat` is forced to a value incompatible with the JWK's public/private shape.
+*
+* @example
+* ```ts
+* // Inferred — private JWKs become PKCS#8, public JWKs become SPKI.
+* const pem = await exportPEM(jwk);
+*
+* // Override (will throw if incompatible with the JWK shape).
+* const spki = await exportPEM(jwk, { pemFormat: "spki" });
+*
+* // JWK without `alg` — provide a hint.
+* const pem2 = await exportPEM(rawJwk, { alg: "RS256" });
+* ```
+*/
+declare function exportPEM(jwk: JWK, options?: {
+  /** PEM format. Inferred from the JWK shape when omitted. */pemFormat?: "pkcs8" | "spki"; /** Algorithm hint used when `jwk.alg` is absent. */
+  alg?: JWKPEMAlgorithm;
+}): Promise<string>;
+/**
+* @deprecated Use {@link exportPEM} instead. `pemFormat` has moved into the options object and
+* is now inferred from the JWK shape by default. The `algForCryptoKeyImport` parameter has
+* been renamed to `options.alg`.
 */
 declare function exportToPEM(jwk: JWK, pemFormat: "pkcs8" | "spki", algForCryptoKeyImport?: JWKPEMAlgorithm): Promise<string>;
 /**
@@ -227,5 +384,4 @@ declare function getJWKFromSet(jwkSet: JWKSet, kidOrProtectedHeader: string | (J
 * @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 };
+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, exportPEM, exportToPEM, generateJWK, generateKey, getJWKFromSet, getJWKsFromSet, importFromPEM, importKey, importPEM, isJWTError, unwrapKey, wrapKey };