unjwt 0.7.2 → 0.8.0

package/dist/_chunks/jwe.mjs

@@ -1,122 +1,318 @@
-import { JWTError, applyTypCtyDefaults, computeJwtTimeClaims, decodePayloadFromBytes, getPlaintextBytes, isCryptoKey, isJWK, isJWKSet, validateCriticalHeadersJWE } from "./utils.mjs";
-import { base64UrlDecode, base64UrlEncode, sanitizeObjectCopy, secureRandomBytes, textEncoder } from "./libs/unsecure.mjs";
-import { decrypt as decrypt$1, encrypt as encrypt$1, encryptKey, generateCEK, generateIV, getJWKsFromSet, importKey, unwrapKey } from "./jwk.mjs";
-import { JWE_ALG_CTX, buildJWKSetFilter, checkAlgAllowed, decodeProtectedHeader, parseEphemeralKey, validateJwtClaimsIfJsonPayload } from "./_internal.mjs";
-const DIRECT_ALGS = /* @__PURE__ */ new Set(["dir", "ECDH-ES"]);
+import { sanitizeObjectCopy, secureRandomBytes, textEncoder } from "./libs/unsecure.mjs";
+import { JWTError, applyTypDefault, base64UrlStringify, computeJwtTimeClaims, getPlaintextBytes, isJWK, isJWKSet, validateCriticalHeadersJWE } from "./_jwt-internal.mjs";
+import { isContentEncryptionAlgorithm } from "./algorithms.mjs";
+import { DEFAULT_PBES2_ITERATIONS, JWE_ALG_CTX, JWE_DIRECT_ALGS, asDecryptionError, asKeyLookupError, assertCompactToken, assertConsumerOptions, assertDirectKeyRole, assertEntryLimit, assertJWEAlgSupported, assertJWEEncSupported, assertJWKSetCandidates, assertNoZipOption, assertOptionEntry, assertPBES2Params, assertProducerCEK, assertProducerCrit, assertProducerIV, assertProtectedOnlyOption, assertSerializationObject, buildECDHAgreementParams, buildJWKSetFilter, buildUnwrapKeyOptions, checkAlgAllowed, checkJWEAlgSupported, checkJWEContentSegments, checkJWEDirectEncryptedKey, checkJWEEncAllowed, checkJWEEncSupported, checkJWEUnprotectedCrit, checkJWEZip, checkProtectedTyp, checkSerializationEntry, createPBES2Budget, decodeJWEPayload, decodeProtectedHeader, decodeSegment, decrypt as decrypt$1, encrypt as encrypt$1, encryptKey, exportReturnedCek, generateCEK, generateIV, getJWKsFromSet, importKey, isJWEAlgSupported, keyMatchesHeader, resolveKeyInput, resolveLimit, resolvePasswordKey, resolvePayloadMode, serializeProtectedHeader, unwrapKey, validateClaimsIfJson } from "./jwk.mjs";
+function buildKeyManagementParams(alg, source) {
+	const { keyManagementIV, p2s, p2c, ecdh } = source;
+	const isPBES2 = alg.startsWith("PBES2");
+	const params = buildECDHAgreementParams(ecdh);
+	if (keyManagementIV) params.iv = keyManagementIV;
+	if (p2s !== void 0) params.p2s = p2s;
+	else if (isPBES2) params.p2s = secureRandomBytes(16);
+	if (p2c !== void 0) params.p2c = p2c;
+	else if (isPBES2) params.p2c = DEFAULT_PBES2_ITERATIONS;
+	return params;
+}
+async function unwrapAndDecrypt(alg, rawKeyMaterial, options) {
+	const { enc, encryptedKey, unwrapKeyOptions, ciphertext, iv, tag, aad, kid, allowSymmetric, keyCandidates, pbes2Budget } = options;
+	if (isJWKSet(rawKeyMaterial)) {
+		const candidates = getJWKsFromSet(rawKeyMaterial, buildJWKSetFilter({
+			kid,
+			alg
+		}, {
+			op: "enc",
+			allowSymmetric
+		}));
+		assertJWKSetCandidates(candidates, {
+			limit: keyCandidates,
+			kid
+		});
+		const attempts = [];
+		for (const candidate of candidates) try {
+			if (alg === "dir") assertDirectKeyRole(candidate, enc);
+			pbes2Budget.spend(unwrapKeyOptions);
+			const unwrappingKey = await importKey(candidate, {
+				alg,
+				expect: "private"
+			});
+			const cek = await unwrapKey(encryptedKey, unwrappingKey, unwrapKeyOptions);
+			return {
+				cek,
+				plaintextBytes: await decrypt$1(enc, cek, ciphertext, iv, tag, aad)
+			};
+		} catch (err) {
+			attempts.push(asDecryptionError(err));
+		}
+		throw new JWTError("JWE decryption failed.", "ERR_JWE_DECRYPTION_FAILED", attempts);
+	}
+	if (alg === "dir") assertDirectKeyRole(rawKeyMaterial, enc);
+	pbes2Budget.spend(unwrapKeyOptions);
+	try {
+		const unwrappingKey = await importKey(resolvePasswordKey(alg, rawKeyMaterial), {
+			alg,
+			expect: "private"
+		});
+		const cek = await unwrapKey(encryptedKey, unwrappingKey, unwrapKeyOptions);
+		return {
+			cek,
+			plaintextBytes: await decrypt$1(enc, cek, ciphertext, iv, tag, aad)
+		};
+	} catch (err) {
+		throw asDecryptionError(err);
+	}
+}
 async function encryptMulti(payload, recipients, options = {}) {
 	if (!Array.isArray(recipients) || recipients.length === 0) throw new JWTError("encryptMulti requires at least one recipient.", "ERR_JWE_INVALID");
+	assertOptionEntry(options, {
+		label: "options",
+		objects: ["protectedHeader", "sharedUnprotectedHeader"]
+	});
+	_assertAADOption(options.aad);
+	assertNoZipOption(options.protectedHeader, "protected");
+	assertNoZipOption(options.sharedUnprotectedHeader, "shared unprotected");
+	assertProtectedOnlyOption(options.sharedUnprotectedHeader, {
+		tier: "shared unprotected",
+		family: "JWE"
+	});
+	for (const [index, recipient] of recipients.entries()) {
+		assertOptionEntry(recipient, {
+			label: `recipients[${index}]`,
+			objects: ["header"]
+		});
+		assertNoZipOption(recipient.header, "per-recipient");
+		assertProtectedOnlyOption(recipient.header, {
+			tier: "per-recipient",
+			family: "JWE"
+		});
+	}
 	const resolvedAlgs = recipients.map((r, i) => _resolveRecipientAlg(r.key, i));
 	const enc = options.enc ?? "A256GCM";
+	const encError = checkJWEEncSupported(enc);
+	if (encError) throw encError;
+	assertProducerCEK(options.cek, enc);
+	assertProducerIV(options.contentEncryptionIV, enc);
+	for (const [index, recipient] of recipients.entries()) if (resolvedAlgs[index].startsWith("PBES2")) assertPBES2Params({
+		p2s: recipient.p2s,
+		p2c: recipient.p2c
+	});
 	const userProtected = sanitizeObjectCopy(options.protectedHeader);
 	const sharedUnprotected = sanitizeObjectCopy(options.sharedUnprotectedHeader);
 	const protectedHeader = {};
 	if (userProtected) Object.assign(protectedHeader, userProtected);
 	protectedHeader.enc = enc;
-	applyTypCtyDefaults(protectedHeader, payload);
-	const plaintextBytes = getPlaintextBytes(computeJwtTimeClaims(payload, options) || payload);
+	applyTypDefault(protectedHeader, payload);
+	assertProducerCrit(protectedHeader, "JWE");
+	const computedPayload = computeJwtTimeClaims(payload, options);
+	const plaintextBytes = getPlaintextBytes(computedPayload || payload);
 	const cek = options.cek ?? generateCEK(enc);
 	const wireRecipients = [];
 	for (let i = 0; i < recipients.length; i++) {
 		const recipient = recipients[i];
 		const alg = resolvedAlgs[i];
-		const keyMgmtParams = _buildRecipientKeyMgmtParams(recipient, alg);
-		const { encryptedKey, parameters: keyMgmtOut } = await encryptKey(alg, enc, await importKey(recipient.key, {
+		const keyMgmtParams = buildKeyManagementParams(alg, recipient);
+		const wrappingKey = await importKey(recipient.key, {
 			alg,
 			expect: "public"
-		}), cek, keyMgmtParams);
+		});
+		const { encryptedKey, parameters: keyMgmtOut } = await encryptKey(alg, enc, wrappingKey, cek, keyMgmtParams);
 		const perRecipientHeader = _buildPerRecipientHeader(recipient, alg, keyMgmtOut);
 		_assertDisjointHeaders(protectedHeader, sharedUnprotected, perRecipientHeader);
 		const wireRecipient = {};
 		if (Object.keys(perRecipientHeader).length > 0) wireRecipient.header = perRecipientHeader;
-		if (encryptedKey) wireRecipient.encrypted_key = base64UrlEncode(encryptedKey);
+		if (encryptedKey) wireRecipient.encrypted_key = base64UrlStringify(encryptedKey);
 		wireRecipients.push(wireRecipient);
 	}
-	const protectedHeaderEncoded = base64UrlEncode(JSON.stringify(protectedHeader));
+	const protectedHeaderEncoded = base64UrlStringify(serializeProtectedHeader(protectedHeader));
 	let aadEncoded;
 	let aadForCipher = protectedHeaderEncoded;
-	if (options.aad !== void 0) {
-		aadEncoded = base64UrlEncode(typeof options.aad === "string" ? textEncoder.encode(options.aad) : options.aad);
+	const aadBytes = typeof options.aad === "string" ? textEncoder.encode(options.aad) : options.aad;
+	if (aadBytes !== void 0 && aadBytes.length > 0) {
+		aadEncoded = base64UrlStringify(aadBytes);
 		aadForCipher = `${protectedHeaderEncoded}.${aadEncoded}`;
 	}
 	const contentAadBytes = textEncoder.encode(aadForCipher);
-	const { ciphertext: contentCiphertext, tag: contentAuthTag, iv: actualContentIV } = await encrypt$1(enc, plaintextBytes, cek, options.contentEncryptionIV ?? generateIV(enc), contentAadBytes);
-	if (!actualContentIV || !contentAuthTag) throw new JWTError("Content encryption did not return an IV / auth tag.", "ERR_JWE_INVALID");
+	const contentIVBytes = options.contentEncryptionIV ?? generateIV(enc);
+	const { ciphertext: contentCiphertext, tag: contentAuthTag, iv: actualContentIV } = await encrypt$1(enc, plaintextBytes, cek, contentIVBytes, contentAadBytes);
 	const output = {
 		protected: protectedHeaderEncoded,
 		recipients: wireRecipients,
-		iv: base64UrlEncode(actualContentIV),
-		ciphertext: base64UrlEncode(contentCiphertext),
-		tag: base64UrlEncode(contentAuthTag)
+		iv: base64UrlStringify(actualContentIV),
+		ciphertext: base64UrlStringify(contentCiphertext),
+		tag: base64UrlStringify(contentAuthTag)
 	};
 	if (sharedUnprotected && Object.keys(sharedUnprotected).length > 0) output.unprotected = sharedUnprotected;
 	if (aadEncoded !== void 0) output.aad = aadEncoded;
 	return output;
 }
 async function decryptMulti(jwe, keyOrLookup, options = {}) {
+	assertConsumerOptions(options);
+	const payloadMode = resolvePayloadMode(options);
+	const recipientLimit = resolveLimit(options.limits, "recipients");
+	const keyCandidates = resolveLimit(options.limits, "keyCandidates");
+	const pbes2Budget = createPBES2Budget(resolveLimit(options.limits, "pbes2Iterations"));
 	const general = _normalizeSerialization(jwe);
 	if (typeof general.iv !== "string" || typeof general.ciphertext !== "string" || typeof general.tag !== "string" || !Array.isArray(general.recipients) || general.recipients.length === 0) throw new JWTError("Invalid JWE JSON Serialization: missing iv/ciphertext/tag/recipients.", "ERR_JWE_INVALID_SERIALIZATION");
+	assertEntryLimit(general.recipients.length, recipientLimit, {
+		family: "JWE",
+		what: "recipients"
+	});
+	const envelopeError = checkSerializationEntry(general, {
+		family: "JWE",
+		label: "JSON Serialization",
+		objects: ["unprotected"],
+		strings: ["protected", "aad"]
+	});
+	if (envelopeError) throw envelopeError;
 	const protectedHeaderEncoded = general.protected ?? "";
 	const protectedHeader = decodeProtectedHeader(protectedHeaderEncoded || void 0, "JWE");
-	const enc = protectedHeader.enc;
-	if (!enc) throw new JWTError("Invalid JWE: Protected header is missing \"enc\".", "ERR_JWE_INVALID");
-	if (options.encryptionAlgorithms && !options.encryptionAlgorithms.includes(enc)) throw new JWTError(`Content encryption algorithm not allowed: ${enc}`, "ERR_JWE_ALG_NOT_ALLOWED");
 	const sharedUnprotected = sanitizeObjectCopy(general.unprotected);
-	const ivBytes = base64UrlDecode(general.iv, { returnAs: "uint8array" });
-	const ciphertextBytes = base64UrlDecode(general.ciphertext, { returnAs: "uint8array" });
-	const tagBytes = base64UrlDecode(general.tag, { returnAs: "uint8array" });
-	const contentAadBytes = textEncoder.encode(general.aad ? `${protectedHeaderEncoded}.${general.aad}` : protectedHeaderEncoded);
+	const sharedError = checkJWEZip(protectedHeader) ?? checkJWEUnprotectedCrit(sharedUnprotected) ?? checkJWEZip(sharedUnprotected);
+	if (sharedError) throw sharedError;
+	_assertDisjointHeaders(protectedHeader, sharedUnprotected, void 0);
+	const enc = protectedHeader.enc ?? sharedUnprotected?.enc;
+	if (!enc) throw new JWTError("Invalid JWE: \"enc\" is missing from the protected and shared unprotected headers.", "ERR_JWE_INVALID");
+	assertJWEEncSupported(enc);
+	const encError = checkJWEEncAllowed(enc, options.encryptionAlgorithms);
+	if (encError) throw encError;
+	validateCriticalHeadersJWE(protectedHeader, options.recognizedHeaders);
+	const typError = checkProtectedTyp(options.typ, protectedHeader, { family: "JWE" });
+	if (typError) throw typError;
+	const ivBytes = decodeSegment(general.iv, {
+		family: "JWE",
+		what: "Initialization vector"
+	});
+	const ciphertextBytes = decodeSegment(general.ciphertext, {
+		family: "JWE",
+		what: "Ciphertext"
+	});
+	const tagBytes = decodeSegment(general.tag, {
+		family: "JWE",
+		what: "Authentication tag"
+	});
+	const segmentError = checkJWEContentSegments(enc, ivBytes, tagBytes);
+	if (segmentError) throw segmentError;
+	const contentAadBytes = textEncoder.encode(general.aad === void 0 ? protectedHeaderEncoded : `${protectedHeaderEncoded}.${general.aad}`);
 	let lastError;
 	let cryptoAttempted = false;
 	for (let i = 0; i < general.recipients.length; i++) {
+		const shapeError = checkSerializationEntry(general.recipients[i], {
+			family: "JWE",
+			label: `Recipient[${i}]`,
+			objects: ["header"],
+			strings: ["encrypted_key"]
+		});
+		if (shapeError) {
+			lastError = shapeError;
+			continue;
+		}
 		const wireRecipient = general.recipients[i];
 		const recipientHeader = sanitizeObjectCopy(wireRecipient.header);
-		_assertDisjointHeaders(protectedHeader, sharedUnprotected, recipientHeader);
+		const recipientError = checkJWEUnprotectedCrit(recipientHeader) ?? checkJWEZip(recipientHeader);
+		if (recipientError) {
+			lastError = recipientError;
+			continue;
+		}
+		try {
+			_assertDisjointHeaders(protectedHeader, sharedUnprotected, recipientHeader);
+		} catch (err) {
+			lastError = asDecryptionError(err);
+			continue;
+		}
 		const effective = _mergeHeaders(protectedHeader, sharedUnprotected, recipientHeader);
 		const alg = effective.alg;
 		if (!alg) {
 			lastError = new JWTError(`Recipient[${i}] has no "alg" in the effective header.`, "ERR_JWE_INVALID");
 			continue;
 		}
-		const rawKeyMaterial = typeof keyOrLookup === "function" ? await keyOrLookup(effective, protectedHeaderEncoded) : keyOrLookup;
-		const algError = checkAlgAllowed(alg, rawKeyMaterial, options.algorithms, JWE_ALG_CTX);
+		if (!isJWEAlgSupported(alg)) {
+			lastError = checkJWEAlgSupported(alg);
+			continue;
+		}
+		const directKeyError = checkJWEDirectEncryptedKey(alg, wireRecipient.encrypted_key);
+		if (directKeyError) {
+			lastError = directKeyError;
+			continue;
+		}
+		let rawKeyMaterial;
+		try {
+			rawKeyMaterial = await resolveKeyInput(keyOrLookup, {
+				header: effective,
+				token: protectedHeaderEncoded,
+				what: `recipient[${i}]`
+			});
+		} catch (err) {
+			lastError = asKeyLookupError(err, `recipient[${i}]`);
+			continue;
+		}
+		const algError = checkAlgAllowed(alg, rawKeyMaterial, {
+			ctx: JWE_ALG_CTX,
+			algorithms: options.algorithms,
+			allowSymmetric: options.allowSymmetricJWKSet
+		});
 		if (algError) {
 			lastError = algError;
 			continue;
 		}
-		if (options.strictRecipientMatch && !_recipientKeyMatches(effective, rawKeyMaterial)) continue;
-		const encryptedKeyBytes = base64UrlDecode(wireRecipient.encrypted_key ?? "", { returnAs: "uint8array" });
-		const unwrapKeyOpts = _buildUnwrapKeyOptions(effective, enc, options);
+		if (options.strictRecipientMatch && !keyMatchesHeader(effective, rawKeyMaterial, {
+			ctx: JWE_ALG_CTX,
+			allowSymmetric: options.allowSymmetricJWKSet
+		})) continue;
+		let encryptedKeyBytes;
+		try {
+			encryptedKeyBytes = decodeSegment(wireRecipient.encrypted_key ?? "", {
+				family: "JWE",
+				what: "Encrypted key"
+			});
+		} catch (err) {
+			lastError = asDecryptionError(err);
+			continue;
+		}
+		const unwrapKeyOpts = buildUnwrapKeyOptions(effective, {
+			alg,
+			enc
+		}, options);
 		cryptoAttempted = true;
+		let cek;
+		let plaintextBytes;
 		try {
-			const { cek, plaintextBytes } = await _unwrapAndDecrypt(alg, enc, rawKeyMaterial, encryptedKeyBytes, unwrapKeyOpts, ciphertextBytes, ivBytes, tagBytes, contentAadBytes, effective.kid);
-			const payload = decodePayloadFromBytes(plaintextBytes, options.forceUint8Array);
-			if (protectedHeader.crit || options.recognizedHeaders?.length) validateCriticalHeadersJWE(protectedHeader, options.recognizedHeaders);
-			validateJwtClaimsIfJsonPayload(payload, options);
-			const result = {
-				payload,
-				protectedHeader: {
-					...protectedHeader,
-					alg,
-					enc
-				},
-				recipientIndex: i
-			};
-			if (sharedUnprotected) result.sharedUnprotectedHeader = sharedUnprotected;
-			if (recipientHeader) result.recipientHeader = recipientHeader;
-			if (options.returnCek) {
-				result.cek = isCryptoKey(cek) ? new Uint8Array(await crypto.subtle.exportKey("raw", cek)) : cek;
-				result.aad = contentAadBytes;
-			}
-			return result;
+			({cek, plaintextBytes} = await unwrapAndDecrypt(alg, rawKeyMaterial, {
+				enc,
+				encryptedKey: encryptedKeyBytes,
+				unwrapKeyOptions: unwrapKeyOpts,
+				ciphertext: ciphertextBytes,
+				iv: ivBytes,
+				tag: tagBytes,
+				aad: contentAadBytes,
+				kid: effective.kid,
+				allowSymmetric: options.allowSymmetricJWKSet,
+				keyCandidates,
+				pbes2Budget
+			}));
 		} catch (err) {
-			if (err instanceof JWTError && err.code !== "ERR_JWE_DECRYPTION_FAILED" && err.code !== "ERR_JWK_KEY_NOT_FOUND") throw err;
-			lastError = err instanceof JWTError ? err : void 0;
+			lastError = asDecryptionError(err);
+			continue;
 		}
+		const payload = decodeJWEPayload(plaintextBytes, payloadMode);
+		validateClaimsIfJson(payload, payloadMode, options);
+		const result = {
+			payload,
+			protectedHeader,
+			recipientIndex: i
+		};
+		if (sharedUnprotected) result.sharedUnprotectedHeader = sharedUnprotected;
+		if (recipientHeader) result.recipientHeader = recipientHeader;
+		if (options.returnCek) {
+			result.cek = await exportReturnedCek(cek);
+			result.aad = contentAadBytes;
+		}
+		return result;
 	}
 	if (options.strictRecipientMatch && !cryptoAttempted) throw new JWTError("No recipient matched the provided key under strictRecipientMatch.", "ERR_JWE_NO_MATCHING_RECIPIENT");
 	throw lastError ?? new JWTError("JWE decryption failed.", "ERR_JWE_DECRYPTION_FAILED");
 }
 function generalToFlattened(jwe) {
+	assertSerializationObject(jwe, "JWE");
+	if (!Array.isArray(jwe.recipients)) throw new JWTError("Invalid JWE JSON Serialization: missing \"recipients\".", "ERR_JWE_INVALID_SERIALIZATION");
 	if (jwe.recipients.length !== 1) throw new JWTError(`Flattened JWE Serialization requires exactly one recipient, got ${jwe.recipients.length}.`, "ERR_JWE_INVALID_SERIALIZATION");
 	const { recipients, ...rest } = jwe;
 	const [recipient] = recipients;
@@ -127,27 +323,13 @@ function generalToFlattened(jwe) {
 }
 function _resolveRecipientAlg(key, index) {
 	if (!isJWK(key)) throw new JWTError(`Recipient[${index}] key is not a JWK.`, "ERR_JWE_RECIPIENT_ALG_INFERENCE");
-	const alg = key.alg;
-	if (!alg) throw new JWTError(`Cannot infer "alg" for recipient[${index}]: the JWK has no "alg" property.`, "ERR_JWE_RECIPIENT_ALG_INFERENCE");
-	if (DIRECT_ALGS.has(alg)) throw new JWTError(`Recipient[${index}] resolves to "${alg}", which requires exactly one recipient. Use encrypt() instead.`, "ERR_JWE_ALG_FORBIDDEN_IN_MULTI");
+	const declared = key.alg;
+	if (!declared) throw new JWTError(`Cannot infer "alg" for recipient[${index}]: the JWK has no "alg" property.`, "ERR_JWE_RECIPIENT_ALG_INFERENCE");
+	const alg = key.kty === "oct" && isContentEncryptionAlgorithm(declared) ? "dir" : declared;
+	if (JWE_DIRECT_ALGS.has(alg)) throw new JWTError(`Recipient[${index}] resolves to "${alg}", which requires exactly one recipient. Use encrypt() instead.`, "ERR_JWE_ALG_FORBIDDEN_IN_MULTI");
+	assertJWEAlgSupported(alg);
 	return alg;
 }
-function _buildRecipientKeyMgmtParams(recipient, alg) {
-	const params = {};
-	if (recipient.keyManagementIV) params.iv = recipient.keyManagementIV;
-	if (recipient.p2s) params.p2s = recipient.p2s;
-	else if (alg.startsWith("PBES2")) params.p2s = secureRandomBytes(16);
-	if (recipient.p2c) params.p2c = recipient.p2c;
-	else if (alg.startsWith("PBES2")) params.p2c = 6e5;
-	if (recipient.ecdh?.partyUInfo) params.apu = recipient.ecdh.partyUInfo;
-	if (recipient.ecdh?.partyVInfo) params.apv = recipient.ecdh.partyVInfo;
-	if (recipient.ecdh?.ephemeralKey) {
-		const { epk, epkPrivateKey } = parseEphemeralKey(recipient.ecdh.ephemeralKey);
-		params.epk = epk;
-		params.epkPrivateKey = epkPrivateKey;
-	}
-	return params;
-}
 function _buildPerRecipientHeader(recipient, alg, keyMgmtOut) {
 	const header = {};
 	if (recipient.key.kid) header.kid = recipient.key.kid;
@@ -177,219 +359,162 @@ function _mergeHeaders(protectedHeader, sharedUnprotected, recipientHeader) {
 	return merged;
 }
 function _normalizeSerialization(input) {
-	if (!input || typeof input !== "object") throw new JWTError("Invalid JWE JSON Serialization: expected an object.", "ERR_JWE_INVALID_SERIALIZATION");
-	const obj = input;
-	if (Array.isArray(obj.recipients)) return obj;
-	if ("encrypted_key" in obj || "header" in obj) {
-		const flattened = obj;
-		const general = {
-			recipients: [{
-				...flattened.header !== void 0 ? { header: flattened.header } : {},
-				...flattened.encrypted_key !== void 0 ? { encrypted_key: flattened.encrypted_key } : {}
-			}],
-			iv: flattened.iv,
-			ciphertext: flattened.ciphertext,
-			tag: flattened.tag
-		};
-		if (flattened.protected !== void 0) general.protected = flattened.protected;
-		if (flattened.unprotected !== void 0) general.unprotected = flattened.unprotected;
-		if (flattened.aad !== void 0) general.aad = flattened.aad;
-		return general;
-	}
-	throw new JWTError("Invalid JWE JSON Serialization: missing both recipients[] and flattened header/encrypted_key.", "ERR_JWE_INVALID_SERIALIZATION");
-}
-function _recipientKeyMatches(effectiveHeader, keyMaterial) {
-	const headerKid = effectiveHeader.kid;
-	if (isJWKSet(keyMaterial)) return keyMaterial.keys.some((k) => !headerKid || k.kid === headerKid);
-	if (isJWK(keyMaterial)) {
-		if (headerKid && keyMaterial.kid && headerKid !== keyMaterial.kid) return false;
-		return true;
+	assertSerializationObject(input, "JWE");
+	if ("recipients" in input) {
+		if ("encrypted_key" in input || "header" in input) throw new JWTError("Invalid JWE JSON Serialization: \"recipients\" must not be combined with a top-level \"header\" or \"encrypted_key\".", "ERR_JWE_INVALID_SERIALIZATION");
+		return input;
 	}
-	return !headerKid;
-}
-function _buildUnwrapKeyOptions(effectiveHeader, enc, options) {
-	const opts = {
-		enc,
-		format: enc.includes("GCM") ? "cryptokey" : "raw",
-		keyUsage: options.keyUsage || ["decrypt"]
+	const flattened = input;
+	const recipient = {};
+	if (flattened.header !== void 0) recipient.header = flattened.header;
+	if (flattened.encrypted_key !== void 0) recipient.encrypted_key = flattened.encrypted_key;
+	const general = {
+		recipients: [recipient],
+		iv: flattened.iv,
+		ciphertext: flattened.ciphertext,
+		tag: flattened.tag
 	};
-	if (effectiveHeader.iv) opts.iv = effectiveHeader.iv;
-	if (effectiveHeader.tag) opts.tag = effectiveHeader.tag;
-	if (effectiveHeader.p2s) opts.p2s = effectiveHeader.p2s;
-	if (effectiveHeader.p2c) opts.p2c = effectiveHeader.p2c;
-	if (effectiveHeader.epk) opts.epk = effectiveHeader.epk;
-	if (effectiveHeader.apu) opts.apu = effectiveHeader.apu;
-	if (effectiveHeader.apv) opts.apv = effectiveHeader.apv;
-	if (options.unwrappedKeyAlgorithm) opts.unwrappedKeyAlgorithm = options.unwrappedKeyAlgorithm;
-	if (options.extractable) opts.extractable = options.extractable;
-	if (options.minIterations !== void 0) opts.minIterations = options.minIterations;
-	if (options.maxIterations !== void 0) opts.maxIterations = options.maxIterations;
-	return opts;
+	if (flattened.protected !== void 0) general.protected = flattened.protected;
+	if (flattened.unprotected !== void 0) general.unprotected = flattened.unprotected;
+	if (flattened.aad !== void 0) general.aad = flattened.aad;
+	return general;
 }
-async function _unwrapAndDecrypt(alg, enc, rawKeyMaterial, encryptedKeyBytes, unwrapKeyOpts, ciphertextBytes, ivBytes, tagBytes, contentAadBytes, headerKid) {
-	if (isJWKSet(rawKeyMaterial)) {
-		const candidates = getJWKsFromSet(rawKeyMaterial, buildJWKSetFilter({
-			kid: headerKid,
-			alg
-		}));
-		if (candidates.length === 0) throw new JWTError("No key found in JWK Set.", "ERR_JWK_KEY_NOT_FOUND");
-		let lastErr;
-		for (const candidate of candidates) {
-			const unwrappingKey = await importKey(candidate, {
-				alg,
-				expect: "private"
-			});
-			try {
-				const cek = await unwrapKey(alg, encryptedKeyBytes, unwrappingKey, unwrapKeyOpts);
-				return {
-					cek,
-					plaintextBytes: await decrypt$1(enc, cek, ciphertextBytes, ivBytes, tagBytes, contentAadBytes)
-				};
-			} catch (err) {
-				if (err instanceof JWTError && err.code !== "ERR_JWE_DECRYPTION_FAILED") throw err;
-				lastErr = err;
-			}
-		}
-		throw lastErr ?? new JWTError("JWE decryption failed.", "ERR_JWE_DECRYPTION_FAILED");
-	}
-	const unwrappingKey = await importKey(rawKeyMaterial, {
-		alg,
-		expect: "private"
-	});
-	try {
-		const cek = await unwrapKey(alg, encryptedKeyBytes, unwrappingKey, unwrapKeyOpts);
-		return {
-			cek,
-			plaintextBytes: await decrypt$1(enc, cek, ciphertextBytes, ivBytes, tagBytes, contentAadBytes)
-		};
-	} catch (err) {
-		if (err instanceof JWTError) throw err;
-		throw new JWTError("JWE decryption failed.", "ERR_JWE_DECRYPTION_FAILED", err);
-	}
+function _assertAADOption(aad) {
+	if (aad === void 0 || typeof aad === "string" || aad instanceof Uint8Array) return;
+	throw new JWTError("\"aad\" must be a string or a Uint8Array.", "ERR_INVALID_OPTION");
 }
 async function encrypt(payload, key, options = {}) {
+	assertOptionEntry(options, {
+		label: "options",
+		objects: ["protectedHeader"]
+	});
 	const { protectedHeader: userHeader, cek: providedCek, contentEncryptionIV: providedContentIV, keyManagementIV, p2s, p2c, ecdh } = options;
-	let { alg, enc } = options;
+	let alg = options.alg;
+	let enc = options.enc;
+	assertNoZipOption(userHeader, "protected");
+	const cekRole = isJWK(key) && key.kty === "oct" && typeof key.alg === "string" ? isContentEncryptionAlgorithm(key.alg) ? key.alg : void 0 : void 0;
 	if (!alg) {
-		if (typeof key === "string" || key instanceof Uint8Array) alg = "PBES2-HS256+A128KW";
+		if (typeof key === "string") alg = "PBES2-HS256+A128KW";
+		else if (cekRole) alg = "dir";
 		else if (isJWK(key)) alg = key.alg;
 	}
 	if (!alg) throw new JWTError("JWE \"alg\" (Key Management Algorithm) must be provided in options or inferable from the key", "ERR_JWE_ALG_MISSING");
-	if (!enc) if (alg === "dir") {
-		enc = isJWK(key) && "enc" in key ? key.enc : void 0;
-		if (!enc) throw new JWTError("JWE \"enc\" must be provided when alg is \"dir\"", "ERR_JWE_ENC_MISSING");
-	} 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 = secureRandomBytes(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 parsed = parseEphemeralKey(ecdh.ephemeralKey);
-		jweKeyManagementParams.epk = parsed.epk;
-		jweKeyManagementParams.epkPrivateKey = parsed.epkPrivateKey;
+	if (!enc) {
+		if (alg === "dir") {
+			enc = cekRole ?? (isJWK(key) ? key.enc : void 0);
+			if (!enc) throw new JWTError("JWE \"enc\" must be provided when alg is \"dir\"", "ERR_JWE_ENC_MISSING");
+		} else enc = isJWK(key) && key.enc !== void 0 ? key.enc : "A256GCM";
 	}
-	const wrappingKeyMaterial = await importKey(key, {
+	assertJWEAlgSupported(alg);
+	assertJWEEncSupported(enc);
+	assertProducerCEK(providedCek, enc);
+	assertProducerIV(providedContentIV, enc);
+	if (alg.startsWith("PBES2")) assertPBES2Params({
+		p2s,
+		p2c
+	});
+	const jweKeyManagementParams = buildKeyManagementParams(alg, {
+		keyManagementIV,
+		p2s,
+		p2c,
+		ecdh
+	});
+	const wrappingKeyMaterial = await importKey(resolvePasswordKey(alg, key), {
 		alg,
 		expect: "public"
 	});
+	if (alg === "dir") assertDirectKeyRole(key, enc);
 	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, options) || payload);
-	const protectedHeaderEncoded = base64UrlEncode(JSON.stringify(protectedHeader));
+	const computedPayload = computeJwtTimeClaims(payload, options);
+	const plaintextBytes = getPlaintextBytes(computedPayload || payload);
+	const protectedHeaderSerialized = serializeProtectedHeader(protectedHeader);
+	const protectedHeaderEncoded = base64UrlStringify(protectedHeaderSerialized);
 	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)
+		jweEncryptedKey ? base64UrlStringify(jweEncryptedKey) : "",
+		base64UrlStringify(actualContentIV),
+		base64UrlStringify(contentCiphertext),
+		base64UrlStringify(contentAuthTag)
 	].join(".");
 }
 async function decrypt(jwe, key, options = {}) {
+	assertCompactToken(jwe, "JWE");
+	assertConsumerOptions(options);
+	const payloadMode = resolvePayloadMode(options);
+	const keyCandidateLimit = resolveLimit(options.limits, "keyCandidates");
+	const pbes2Budget = createPBES2Budget(resolveLimit(options.limits, "pbes2Iterations"));
 	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;
 	const protectedHeader = decodeProtectedHeader(protectedHeaderEncoded, "JWE");
-	if (!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?.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 algError = checkAlgAllowed(alg, rawKeyMaterial, options?.algorithms, JWE_ALG_CTX);
+	assertHeaderAlgorithms(protectedHeader);
+	const { alg, enc } = protectedHeader;
+	const headerError = checkJWEZip(protectedHeader) ?? checkJWEEncAllowed(enc, options.encryptionAlgorithms);
+	if (headerError) throw headerError;
+	validateCriticalHeadersJWE(protectedHeader, options.recognizedHeaders);
+	const typError = checkProtectedTyp(options.typ, protectedHeader, { family: "JWE" });
+	if (typError) throw typError;
+	const directKeyError = checkJWEDirectEncryptedKey(alg, encryptedKeyEncoded);
+	if (directKeyError) throw directKeyError;
+	const encryptedKeyBytes = decodeSegment(encryptedKeyEncoded, {
+		family: "JWE",
+		what: "Encrypted key"
+	});
+	const contentIVBytes = decodeSegment(ivEncoded, {
+		family: "JWE",
+		what: "Initialization vector"
+	});
+	const contentAuthTagBytes = decodeSegment(authTagEncoded, {
+		family: "JWE",
+		what: "Authentication tag"
+	});
+	const ciphertextBytes = decodeSegment(ciphertextEncoded, {
+		family: "JWE",
+		what: "Ciphertext"
+	});
+	const segmentError = checkJWEContentSegments(enc, contentIVBytes, contentAuthTagBytes);
+	if (segmentError) throw segmentError;
+	const rawKeyMaterial = await resolveKeyInput(key, {
+		header: protectedHeader,
+		token: jwe,
+		what: "the JWE"
+	});
+	const algError = checkAlgAllowed(alg, rawKeyMaterial, {
+		ctx: JWE_ALG_CTX,
+		algorithms: options.algorithms,
+		allowSymmetric: options.allowSymmetricJWKSet
+	});
 	if (algError) throw algError;
-	const encryptedKeyBytes = base64UrlDecode(encryptedKeyEncoded, { returnAs: "uint8array" });
-	const contentIVBytes = base64UrlDecode(ivEncoded, { returnAs: "uint8array" });
-	const contentAuthTagBytes = base64UrlDecode(authTagEncoded, { returnAs: "uint8array" });
-	const ciphertextBytes = base64UrlDecode(ciphertextEncoded, { returnAs: "uint8array" });
-	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;
-	if (options?.minIterations !== void 0) unwrapKeyOpts.minIterations = options.minIterations;
-	if (options?.maxIterations !== void 0) unwrapKeyOpts.maxIterations = options.maxIterations;
+	const unwrapKeyOpts = buildUnwrapKeyOptions(protectedHeader, {
+		alg,
+		enc
+	}, options);
 	const aadBytes = textEncoder.encode(protectedHeaderEncoded);
-	let cek;
-	let plaintextBytes;
-	if (isJWKSet(rawKeyMaterial)) {
-		const candidates = getJWKsFromSet(rawKeyMaterial, buildJWKSetFilter(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) {
-			const unwrappingKey = await importKey(candidate, {
-				alg,
-				expect: "private"
-			});
-			try {
-				const candidateCek = await unwrapKey(alg, encryptedKeyBytes, unwrappingKey, unwrapKeyOpts);
-				plaintextBytes = await decrypt$1(enc, candidateCek, ciphertextBytes, contentIVBytes, contentAuthTagBytes, aadBytes);
-				cek = candidateCek;
-				decrypted = true;
-				break;
-			} catch (err) {
-				if (err instanceof JWTError && err.code !== "ERR_JWE_DECRYPTION_FAILED") throw err;
-			}
-		}
-		if (!decrypted) throw new JWTError("JWE decryption failed.", "ERR_JWE_DECRYPTION_FAILED");
-	} else {
-		const unwrappingKey = await importKey(rawKeyMaterial, {
-			alg,
-			expect: "private"
-		});
-		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, options?.forceUint8Array);
-	if (protectedHeader.crit || options?.recognizedHeaders?.length) validateCriticalHeadersJWE(protectedHeader, options?.recognizedHeaders);
-	validateJwtClaimsIfJsonPayload(payload, options);
+	const { cek, plaintextBytes } = await unwrapAndDecrypt(alg, rawKeyMaterial, {
+		enc,
+		encryptedKey: encryptedKeyBytes,
+		unwrapKeyOptions: unwrapKeyOpts,
+		ciphertext: ciphertextBytes,
+		iv: contentIVBytes,
+		tag: contentAuthTagBytes,
+		aad: aadBytes,
+		kid: protectedHeader.kid,
+		allowSymmetric: options.allowSymmetricJWKSet,
+		keyCandidates: keyCandidateLimit,
+		pbes2Budget
+	});
+	const payload = decodeJWEPayload(plaintextBytes, payloadMode);
+	validateClaimsIfJson(payload, payloadMode, options);
 	const result = {
 		payload,
 		protectedHeader
 	};
 	if (options.returnCek) {
-		result.cek = isCryptoKey(cek) ? new Uint8Array(await crypto.subtle.exportKey("raw", cek)) : cek;
+		result.cek = await exportReturnedCek(cek);
 		result.aad = aadBytes;
 	}
 	return result;
@@ -402,6 +527,13 @@ function _buildJWEHeader(alg, enc, key, userHeader, keyManagementParams, payload
 	if (keyManagementParams) Object.assign(header, keyManagementParams);
 	header.alg = alg;
 	header.enc = enc;
-	return applyTypCtyDefaults(header, payload);
+	applyTypDefault(header, payload);
+	assertProducerCrit(header, "JWE");
+	return header;
+}
+function assertHeaderAlgorithms(header) {
+	if (!header.alg || !header.enc) throw new JWTError("Invalid JWE: Protected header must be an object with \"alg\" and \"enc\" properties.", "ERR_JWE_INVALID");
+	assertJWEAlgSupported(header.alg);
+	assertJWEEncSupported(header.enc);
 }
 export { decrypt, decryptMulti, encrypt, encryptMulti, generalToFlattened };