unjwt 0.7.3 → 0.8.1

package/dist/_chunks/jws.mjs

@@ -1,28 +1,103 @@
-import { JWTError, applyTypCtyDefaults, computeJwtTimeClaims, getPlaintextBytes, isJWK, isJWKSet, validateCriticalHeadersJWS } from "./utils.mjs";
-import { base64UrlDecode, base64UrlEncode, sanitizeObjectCopy, textDecoder, textEncoder } from "./libs/unsecure.mjs";
-import { getJWKsFromSet, importKey, sign as sign$1, verify as verify$1 } from "./jwk.mjs";
-import { JWS_ALG_CTX, buildJWKSetFilter, checkAlgAllowed, decodeJWSPayload, decodeProtectedHeader, resolveSigningKey, validateJwtClaimsIfJsonPayload } from "./_internal.mjs";
+import { sanitizeObjectCopy, textEncoder } from "./libs/unsecure.mjs";
+import { JWTError, applyTypDefault, base64UrlStringify, computeJwtTimeClaims, getPlaintextBytes, isJWK, isJWKSet, parsePayloadText, validateCriticalHeadersJWS } from "./_jwt-internal.mjs";
+import { inferJWSAllowedAlgorithms } from "./algorithms.mjs";
+import { JWS_ALG_CTX, applyB64Header, asJWTError, asKeyLookupError, asKeyUsageError, assertB64Option, assertCompactToken, assertConsumerOptions, assertEntryLimit, assertJWKSetCandidates, assertNotStringKey, assertOptionEntry, assertProducerCrit, assertProtectedOnlyOption, assertSerializationObject, buildJWKSetFilter, checkAlgAllowed, checkJWSAlgSupported, checkJWSB64, checkProtectedTyp, checkSerializationEntry, decodeJWSPayload, decodeProtectedHeader, decodeSegment, getJWKsFromSet, importKey, keyMatchesHeader, resolveKeyInput, resolveLimit, resolvePayloadMode, resolveSigningKey, serializeProtectedHeader, sign as sign$1, stringKeyError, validateClaimsIfJson, verify as verify$1 } from "./jwk.mjs";
+function buildJWSProtectedHeader(alg, key, userHeader, options) {
+	const safeHeader = sanitizeObjectCopy(userHeader);
+	const header = {};
+	if (isJWK(key) && key.kid) header.kid = key.kid;
+	if (safeHeader) Object.assign(header, safeHeader);
+	header.alg = alg;
+	applyTypDefault(header, options.payload);
+	if (options.b64 === false) header.b64 = false;
+	applyB64Header(header);
+	assertProducerCrit(header, "JWS");
+	return header;
+}
+async function verifyWithKey(alg, rawKeyMaterial, options) {
+	try {
+		return await verifyWithKeyMaterial(alg, rawKeyMaterial, options);
+	} catch (err) {
+		throw asKeyUsageError(err, alg);
+	}
+}
+async function verifyWithKeyMaterial(alg, rawKeyMaterial, options) {
+	const { signature, signingInput, kid, allowSymmetric, keyCandidates } = options;
+	if (isJWKSet(rawKeyMaterial)) {
+		const candidates = getJWKsFromSet(rawKeyMaterial, buildJWKSetFilter({
+			kid,
+			alg
+		}, {
+			op: "sig",
+			allowSymmetric
+		}));
+		assertJWKSetCandidates(candidates, {
+			limit: keyCandidates,
+			kid
+		});
+		const attempts = [];
+		for (const candidate of candidates) try {
+			const verificationKey = await resolveSigningKey(alg, await importKey(candidate, {
+				alg,
+				expect: "public"
+			}), "verify");
+			if (await verify$1(alg, verificationKey, signature, signingInput)) return true;
+			attempts.push(new JWTError("JWS signature verification failed.", "ERR_JWS_SIGNATURE_INVALID"));
+		} catch (error) {
+			attempts.push(asKeyUsageError(error, alg));
+		}
+		throw new JWTError("JWS signature verification failed.", "ERR_JWS_SIGNATURE_INVALID", attempts);
+	}
+	const verificationKey = await resolveSigningKey(alg, await importKey(rawKeyMaterial, {
+		alg,
+		expect: "public"
+	}), "verify");
+	return verify$1(alg, verificationKey, signature, signingInput);
+}
 async function signMulti(payload, signers, options = {}) {
 	if (!Array.isArray(signers) || signers.length === 0) throw new JWTError("signMulti requires at least one signer.", "ERR_JWS_INVALID");
-	const resolvedAlgs = signers.map((s, i) => _resolveSignerAlg(s.key, i));
+	for (const [index, signer] of signers.entries()) {
+		assertOptionEntry(signer, {
+			label: `signers[${index}]`,
+			objects: ["protectedHeader", "unprotectedHeader"]
+		});
+		assertNotStringKey(signer.key);
+		assertProtectedOnlyOption(signer.unprotectedHeader, {
+			tier: "unprotected",
+			family: "JWS"
+		});
+		assertB64Option(signer.protectedHeader);
+	}
+	const resolvedAlgs = signers.map((s, i) => _resolveSignerAlg(s, i));
 	const b64 = _resolveB64(signers);
-	const payloadBytes = getPlaintextBytes(computeJwtTimeClaims(payload, options) || payload);
-	const payloadEncoded = b64 ? base64UrlEncode(payloadBytes) : textDecoder.decode(payloadBytes);
+	const computedPayload = computeJwtTimeClaims(payload, options);
+	const payloadBytes = getPlaintextBytes(computedPayload || payload);
+	const payloadEncoded = b64 ? base64UrlStringify(payloadBytes) : parsePayloadText(payloadBytes);
 	const wireSignatures = [];
 	for (let i = 0; i < signers.length; i++) {
 		const signer = signers[i];
 		const alg = resolvedAlgs[i];
-		const protectedHeader = _buildSignerProtectedHeader(signer, alg, payload, b64);
+		const protectedHeader = buildJWSProtectedHeader(alg, signer.key, signer.protectedHeader, {
+			payload,
+			b64
+		});
 		const unprotectedHeader = sanitizeObjectCopy(signer.unprotectedHeader);
 		_assertDisjointHeaders(protectedHeader, unprotectedHeader);
-		const protectedHeaderEncoded = base64UrlEncode(JSON.stringify(protectedHeader));
+		const protectedHeaderEncoded = base64UrlStringify(serializeProtectedHeader(protectedHeader));
 		const signingInputBytes = textEncoder.encode(`${protectedHeaderEncoded}.${payloadEncoded}`);
-		const wireSig = {
-			protected: protectedHeaderEncoded,
-			signature: base64UrlEncode(await sign$1(alg, await resolveSigningKey(alg, await importKey(signer.key, {
+		let signatureBytes;
+		try {
+			const signingKey = await resolveSigningKey(alg, await importKey(signer.key, {
 				alg,
 				expect: "private"
-			}), "sign"), signingInputBytes))
+			}), "sign");
+			signatureBytes = await sign$1(alg, signingKey, signingInputBytes);
+		} catch (error) {
+			throw asKeyUsageError(error, alg);
+		}
+		const wireSig = {
+			protected: protectedHeaderEncoded,
+			signature: base64UrlStringify(signatureBytes)
 		};
 		if (unprotectedHeader && Object.keys(unprotectedHeader).length > 0) wireSig.header = unprotectedHeader;
 		wireSignatures.push(wireSig);
@@ -33,54 +108,83 @@ async function signMulti(payload, signers, options = {}) {
 	};
 }
 async function verifyMulti(jws, keyOrLookup, options = {}) {
-	const general = _normalizeSerialization(jws);
-	if (typeof general.payload !== "string" || !Array.isArray(general.signatures) || general.signatures.length === 0) throw new JWTError("Invalid JWS JSON Serialization: missing payload or signatures.", "ERR_JWS_INVALID_SERIALIZATION");
+	assertConsumerOptions(options);
+	const payloadMode = resolvePayloadMode(options);
+	const signatureLimit = resolveLimit(options.limits, "signatures");
+	const keyCandidates = resolveLimit(options.limits, "keyCandidates");
+	const general = _readGeneralSerialization(jws, signatureLimit);
 	let lastError;
 	let cryptoAttempted = false;
 	for (let i = 0; i < general.signatures.length; i++) {
-		const wireSig = general.signatures[i];
-		if (typeof wireSig.signature !== "string") {
-			lastError = new JWTError(`Signature[${i}] is missing the "signature" field.`, "ERR_JWS_INVALID");
+		const read = _readSignatureHeaders(general.signatures[i], i);
+		if (read.error) {
+			lastError = read.error;
 			continue;
 		}
-		let protectedHeader;
-		try {
-			protectedHeader = decodeProtectedHeader(wireSig.protected, "JWS");
-		} catch (err) {
-			lastError = err instanceof JWTError ? err : void 0;
+		const { wireSig, protectedHeader, unprotectedHeader, effective, alg } = read;
+		const typError = checkProtectedTyp(options.typ, protectedHeader, {
+			family: "JWS",
+			label: `signature[${i}]`
+		});
+		if (typError) {
+			lastError = typError;
 			continue;
 		}
-		if (!protectedHeader.alg) {
-			lastError = new JWTError(`Invalid JWS: Signature[${i}] protected header must have an "alg" property.`, "ERR_JWS_INVALID");
+		let rawKeyMaterial;
+		try {
+			rawKeyMaterial = await resolveKeyInput(keyOrLookup, {
+				header: effective,
+				token: wireSig.protected ?? "",
+				what: `signature[${i}]`
+			});
+		} catch (err) {
+			lastError = asKeyLookupError(err, `signature[${i}]`);
 			continue;
 		}
-		const unprotectedHeader = sanitizeObjectCopy(wireSig.header);
-		_assertDisjointHeaders(protectedHeader, unprotectedHeader);
-		const effective = _mergeHeaders(protectedHeader, unprotectedHeader);
-		const alg = protectedHeader.alg;
-		if (options.typ && protectedHeader.typ !== options.typ) {
-			lastError = new JWTError(`Invalid JWS: "typ" Header Parameter mismatch on signature[${i}]. Expected "${options.typ}", got "${protectedHeader.typ}".`, "ERR_JWS_INVALID");
+		if (typeof rawKeyMaterial === "string") {
+			lastError = stringKeyError();
 			continue;
 		}
-		const rawKeyMaterial = typeof keyOrLookup === "function" ? await keyOrLookup(effective, wireSig.protected ?? "") : keyOrLookup;
-		const algError = checkAlgAllowed(alg, rawKeyMaterial, options.algorithms, JWS_ALG_CTX);
+		const algError = checkAlgAllowed(alg, rawKeyMaterial, {
+			ctx: JWS_ALG_CTX,
+			algorithms: options.algorithms,
+			allowSymmetric: options.allowSymmetricJWKSet
+		});
 		if (algError) {
 			lastError = algError;
 			continue;
 		}
-		if (options.strictSignerMatch && !_signerKeyMatches(effective, rawKeyMaterial)) continue;
-		const signatureBytes = base64UrlDecode(wireSig.signature, { returnAs: "uint8array" });
+		if (options.strictSignerMatch && !keyMatchesHeader(effective, rawKeyMaterial, {
+			ctx: JWS_ALG_CTX,
+			allowSymmetric: options.allowSymmetricJWKSet
+		})) continue;
+		let signatureBytes;
+		try {
+			signatureBytes = decodeSegment(wireSig.signature, {
+				family: "JWS",
+				what: "Signature"
+			});
+		} catch (err) {
+			lastError = asJWTError(err, INVALID_JWS);
+			continue;
+		}
 		const signingInputBytes = textEncoder.encode(`${wireSig.protected ?? ""}.${general.payload}`);
 		cryptoAttempted = true;
 		try {
-			if (!await _verifyWithKey(alg, rawKeyMaterial, signatureBytes, signingInputBytes, effective.kid)) {
+			if (!await verifyWithKey(alg, rawKeyMaterial, {
+				signature: signatureBytes,
+				signingInput: signingInputBytes,
+				kid: effective.kid,
+				allowSymmetric: options.allowSymmetricJWKSet,
+				keyCandidates
+			})) {
 				lastError = new JWTError("JWS signature verification failed.", "ERR_JWS_SIGNATURE_INVALID");
 				continue;
 			}
-			const useB64 = protectedHeader.b64 !== false;
-			const payload = decodeJWSPayload(general.payload, useB64, options.forceUint8Array);
 			validateCriticalHeadersJWS(protectedHeader, options.recognizedHeaders);
-			validateJwtClaimsIfJsonPayload(payload, options);
+			const useB64 = protectedHeader.b64 !== false;
+			const payload = decodeJWSPayload(general.payload, useB64, payloadMode);
+			validateClaimsIfJson(payload, payloadMode, options);
 			const result = {
 				payload,
 				protectedHeader,
@@ -89,21 +193,31 @@ async function verifyMulti(jws, keyOrLookup, options = {}) {
 			if (unprotectedHeader) result.signerHeader = unprotectedHeader;
 			return result;
 		} catch (err) {
-			if (err instanceof JWTError && err.code !== "ERR_JWS_SIGNATURE_INVALID" && err.code !== "ERR_JWK_KEY_NOT_FOUND") throw err;
-			lastError = err instanceof JWTError ? err : void 0;
+			const error = asJWTError(err, INVALID_SIGNATURE);
+			if (!PER_SIGNATURE_ERROR_CODES.has(error.code)) throw error;
+			lastError = error;
 		}
 	}
 	if (options.strictSignerMatch && !cryptoAttempted) throw new JWTError("No signature matched the provided key under strictSignerMatch.", "ERR_JWS_NO_MATCHING_SIGNER");
 	throw lastError ?? new JWTError("JWS signature verification failed.", "ERR_JWS_SIGNATURE_INVALID");
 }
 async function verifyMultiAll(jws, keyResolver, options = {}) {
-	const general = _normalizeSerialization(jws);
-	if (typeof general.payload !== "string" || !Array.isArray(general.signatures) || general.signatures.length === 0) throw new JWTError("Invalid JWS JSON Serialization: missing payload or signatures.", "ERR_JWS_INVALID_SERIALIZATION");
+	assertConsumerOptions(options);
+	const payloadMode = resolvePayloadMode(options);
+	const signatureLimit = resolveLimit(options.limits, "signatures");
+	const keyCandidates = resolveLimit(options.limits, "keyCandidates");
+	const general = _readGeneralSerialization(jws, signatureLimit);
 	const outcomes = [];
-	for (let i = 0; i < general.signatures.length; i++) outcomes.push(await _verifyOneSignature(general.payload, general.signatures[i], i, keyResolver, options));
+	for (let i = 0; i < general.signatures.length; i++) outcomes.push(await _verifyOneSignature(general.payload, general.signatures[i], i, keyResolver, {
+		options,
+		payloadMode,
+		keyCandidates
+	}));
 	return outcomes;
 }
 function generalToFlattenedJWS(jws) {
+	assertSerializationObject(jws, "JWS");
+	if (!Array.isArray(jws.signatures)) throw new JWTError("Invalid JWS JSON Serialization: missing \"signatures\".", "ERR_JWS_INVALID_SERIALIZATION");
 	if (jws.signatures.length !== 1) throw new JWTError(`Flattened JWS Serialization requires exactly one signature, got ${jws.signatures.length}.`, "ERR_JWS_INVALID_SERIALIZATION");
 	const [signature] = jws.signatures;
 	const flattened = {
@@ -114,13 +228,86 @@ function generalToFlattenedJWS(jws) {
 	if (signature.header !== void 0) flattened.header = signature.header;
 	return flattened;
 }
-function _resolveSignerAlg(key, index) {
-	if (!isJWK(key)) throw new JWTError(`Signer[${index}] key is not a JWK.`, "ERR_JWS_SIGNER_ALG_INFERENCE");
-	const alg = key.alg;
-	if (!alg) throw new JWTError(`Cannot infer "alg" for signer[${index}]: the JWK has no "alg" property.`, "ERR_JWS_SIGNER_ALG_INFERENCE");
-	if (alg === "none") throw new JWTError("\"none\" is not a valid signing algorithm", "ERR_JWS_ALG_NOT_ALLOWED");
+const INVALID_JWS = {
+	code: "ERR_JWS_INVALID",
+	message: "Invalid JWS."
+};
+const INVALID_SIGNATURE = {
+	code: "ERR_JWS_SIGNATURE_INVALID",
+	message: "JWS signature verification failed."
+};
+const INVALID_CLAIMS = {
+	code: "ERR_JWT_CLAIM_INVALID",
+	message: "JWT claim validation failed."
+};
+const PER_SIGNATURE_ERROR_CODES = /* @__PURE__ */ new Set([
+	"ERR_JWS_SIGNATURE_INVALID",
+	"ERR_JWK_KEY_NOT_FOUND",
+	"ERR_JWK_INVALID"
+]);
+function _checkUnprotectedHeader(header) {
+	if (!header) return void 0;
+	if (Object.hasOwn(header, "crit")) return new JWTError("Invalid JWS: \"crit\" must be integrity protected (RFC 7515 §4.1.11).", "ERR_JWS_INVALID");
+	if (Object.hasOwn(header, "b64")) return new JWTError("Invalid JWS: \"b64\" must occur only within the protected header (RFC 7797 §3).", "ERR_JWS_INVALID");
+}
+function _readSignatureHeaders(entry, index) {
+	const shapeError = checkSerializationEntry(entry, {
+		family: "JWS",
+		label: `Signature[${index}]`,
+		objects: ["header"],
+		strings: ["protected"]
+	});
+	if (shapeError) return { error: shapeError };
+	const wireSig = entry;
+	if (typeof wireSig.signature !== "string") return { error: new JWTError(`Signature[${index}] is missing the "signature" field.`, "ERR_JWS_INVALID") };
+	let protectedHeader;
+	try {
+		protectedHeader = decodeProtectedHeader(wireSig.protected, "JWS");
+	} catch (err) {
+		return { error: asJWTError(err, INVALID_JWS) };
+	}
+	const unprotectedHeader = sanitizeObjectCopy(wireSig.header);
+	const failed = (error) => ({
+		error,
+		protectedHeader,
+		...unprotectedHeader ? { unprotectedHeader } : {}
+	});
+	const unprotectedError = _checkUnprotectedHeader(unprotectedHeader);
+	if (unprotectedError) return failed(unprotectedError);
+	try {
+		_assertDisjointHeaders(protectedHeader, unprotectedHeader);
+	} catch (err) {
+		return failed(asJWTError(err, INVALID_JWS));
+	}
+	const effective = _mergeHeaders(protectedHeader, unprotectedHeader);
+	const alg = effective.alg;
+	if (!alg) return failed(new JWTError(`Invalid JWS: Signature[${index}] has no "alg" in its protected or unprotected header.`, "ERR_JWS_INVALID"));
+	const algError = checkJWSAlgSupported(alg) ?? checkJWSB64(protectedHeader);
+	if (algError) return failed(algError);
+	return {
+		wireSig,
+		protectedHeader,
+		unprotectedHeader,
+		effective,
+		alg
+	};
+}
+function _resolveSignerAlg(signer, index) {
+	const alg = signer.alg ?? _inferSignerAlg(signer.key, index);
+	const unsupported = checkJWSAlgSupported(alg);
+	if (unsupported) throw unsupported;
 	return alg;
 }
+function _inferSignerAlg(key, index) {
+	if (isJWK(key)) {
+		const alg = key.alg;
+		if (!alg) throw new JWTError(`Cannot infer "alg" for signer[${index}]: the JWK has no "alg" property.`, "ERR_JWS_SIGNER_ALG_INFERENCE");
+		return alg;
+	}
+	const inferred = inferJWSAllowedAlgorithms(key);
+	if (!inferred?.length) throw new JWTError(`Cannot infer "alg" for signer[${index}]: pass it explicitly on the signer.`, "ERR_JWS_SIGNER_ALG_INFERENCE");
+	return inferred[0];
+}
 function _resolveB64(signers) {
 	let decided;
 	for (let i = 0; i < signers.length; i++) {
@@ -131,17 +318,6 @@ function _resolveB64(signers) {
 	}
 	return decided ?? true;
 }
-function _buildSignerProtectedHeader(signer, alg, payload, b64) {
-	const userHeader = sanitizeObjectCopy(signer.protectedHeader);
-	const header = {};
-	if (signer.key.kid) header.kid = signer.key.kid;
-	if (userHeader) Object.assign(header, userHeader);
-	header.alg = alg;
-	applyTypCtyDefaults(header, payload);
-	if (!b64) header.b64 = false;
-	else delete header.b64;
-	return header;
-}
 function _assertDisjointHeaders(protectedHeader, unprotectedHeader) {
 	if (!protectedHeader || !unprotectedHeader) return;
 	for (const k of Object.keys(unprotectedHeader)) if (k in protectedHeader) throw new JWTError(`JWS header parameter "${k}" appears in both protected and unprotected headers of a signature; they must be disjoint (RFC 7515 §7.2.1).`, "ERR_JWS_HEADER_PARAMS_NOT_DISJOINT");
@@ -153,12 +329,23 @@ function _mergeHeaders(protectedHeader, unprotectedHeader) {
 		...unprotectedHeader
 	};
 }
+function _readGeneralSerialization(input, signatureLimit) {
+	const general = _normalizeSerialization(input);
+	if (typeof general.payload !== "string" || !Array.isArray(general.signatures) || general.signatures.length === 0) throw new JWTError("Invalid JWS JSON Serialization: missing payload or signatures.", "ERR_JWS_INVALID_SERIALIZATION");
+	assertEntryLimit(general.signatures.length, signatureLimit, {
+		family: "JWS",
+		what: "signatures"
+	});
+	return general;
+}
 function _normalizeSerialization(input) {
-	if (!input || typeof input !== "object") throw new JWTError("Invalid JWS JSON Serialization: expected an object.", "ERR_JWS_INVALID_SERIALIZATION");
-	const obj = input;
-	if (Array.isArray(obj.signatures)) return obj;
-	if ("signature" in obj) {
-		const flattened = obj;
+	assertSerializationObject(input, "JWS");
+	if ("signatures" in input && Array.isArray(input.signatures)) {
+		if ("signature" in input || "protected" in input) throw new JWTError("Invalid JWS JSON Serialization: \"signatures\" must not be combined with a top-level \"signature\" or \"protected\".", "ERR_JWS_INVALID_SERIALIZATION");
+		return input;
+	}
+	if ("signature" in input) {
+		const flattened = input;
 		const signature = { signature: flattened.signature };
 		if (flattened.protected !== void 0) signature.protected = flattened.protected;
 		if (flattened.header !== void 0) signature.header = flattened.header;
@@ -169,34 +356,8 @@ function _normalizeSerialization(input) {
 	}
 	throw new JWTError("Invalid JWS JSON Serialization: missing both signatures[] and flattened signature.", "ERR_JWS_INVALID_SERIALIZATION");
 }
-function _signerKeyMatches(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;
-	}
-	return !headerKid;
-}
-async function _verifyWithKey(alg, rawKeyMaterial, signatureBytes, signingInputBytes, 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");
-		for (const candidate of candidates) if (await verify$1(alg, await resolveSigningKey(alg, await importKey(candidate, {
-			alg,
-			expect: "public"
-		}), "verify"), signatureBytes, signingInputBytes)) return true;
-		return false;
-	}
-	return verify$1(alg, await resolveSigningKey(alg, await importKey(rawKeyMaterial, {
-		alg,
-		expect: "public"
-	}), "verify"), signatureBytes, signingInputBytes);
-}
-async function _verifyOneSignature(payload, wireSig, index, keyResolver, options) {
+async function _verifyOneSignature(payload, entry, index, keyResolver, context) {
+	const { options, payloadMode, keyCandidates } = context;
 	const fail = (error, protectedHeader, signerHeader) => {
 		const outcome = {
 			signerIndex: index,
@@ -207,51 +368,70 @@ async function _verifyOneSignature(payload, wireSig, index, keyResolver, options
 		if (signerHeader) outcome.signerHeader = signerHeader;
 		return outcome;
 	};
-	if (typeof wireSig.signature !== "string") return fail(new JWTError(`Signature[${index}] is missing the "signature" field.`, "ERR_JWS_INVALID"));
-	let protectedHeader;
-	try {
-		protectedHeader = decodeProtectedHeader(wireSig.protected, "JWS");
-	} catch (err) {
-		return fail(_asJWTError(err, "ERR_JWS_INVALID"));
-	}
-	if (!protectedHeader.alg) return fail(new JWTError(`Invalid JWS: Signature[${index}] protected header must have an "alg" property.`, "ERR_JWS_INVALID"), protectedHeader);
-	const unprotectedHeader = sanitizeObjectCopy(wireSig.header);
+	const read = _readSignatureHeaders(entry, index);
+	if (read.error) return fail(read.error, read.protectedHeader, read.unprotectedHeader);
+	const { wireSig, protectedHeader, unprotectedHeader, effective, alg } = read;
+	const typError = checkProtectedTyp(options.typ, protectedHeader, {
+		family: "JWS",
+		label: `signature[${index}]`
+	});
+	if (typError) return fail(typError, protectedHeader, unprotectedHeader);
+	let rawKeyMaterial;
 	try {
-		_assertDisjointHeaders(protectedHeader, unprotectedHeader);
+		rawKeyMaterial = await resolveKeyInput(keyResolver, {
+			header: effective,
+			token: wireSig.protected ?? "",
+			what: `signature[${index}]`
+		});
 	} catch (err) {
-		return fail(_asJWTError(err, "ERR_JWS_INVALID"), protectedHeader, unprotectedHeader);
+		return fail(asKeyLookupError(err, `signature[${index}]`), protectedHeader, unprotectedHeader);
 	}
-	const effective = _mergeHeaders(protectedHeader, unprotectedHeader);
-	const alg = protectedHeader.alg;
-	if (options.typ && protectedHeader.typ !== options.typ) return fail(new JWTError(`Invalid JWS: "typ" Header Parameter mismatch on signature[${index}]. Expected "${options.typ}", got "${protectedHeader.typ}".`, "ERR_JWS_INVALID"), protectedHeader, unprotectedHeader);
-	let rawKeyMaterial;
+	if (typeof rawKeyMaterial === "string") return fail(stringKeyError(), protectedHeader, unprotectedHeader);
+	const algError = checkAlgAllowed(alg, rawKeyMaterial, {
+		ctx: JWS_ALG_CTX,
+		algorithms: options.algorithms,
+		allowSymmetric: options.allowSymmetricJWKSet
+	});
+	if (algError) return fail(algError, protectedHeader, unprotectedHeader);
+	let signatureBytes;
 	try {
-		rawKeyMaterial = await keyResolver(effective, wireSig.protected ?? "");
+		signatureBytes = decodeSegment(wireSig.signature, {
+			family: "JWS",
+			what: "Signature"
+		});
 	} catch (err) {
-		return fail(_asJWTError(err, "ERR_JWK_KEY_NOT_FOUND", `Key resolver failed for signature[${index}]`), protectedHeader, unprotectedHeader);
+		return fail(asJWTError(err, INVALID_JWS), protectedHeader, unprotectedHeader);
 	}
-	const algError = checkAlgAllowed(alg, rawKeyMaterial, options.algorithms, JWS_ALG_CTX);
-	if (algError) return fail(algError, protectedHeader, unprotectedHeader);
-	const signatureBytes = base64UrlDecode(wireSig.signature, { returnAs: "uint8array" });
 	const signingInputBytes = textEncoder.encode(`${wireSig.protected ?? ""}.${payload}`);
 	let verified;
 	try {
-		verified = await _verifyWithKey(alg, rawKeyMaterial, signatureBytes, signingInputBytes, effective.kid);
+		verified = await verifyWithKey(alg, rawKeyMaterial, {
+			signature: signatureBytes,
+			signingInput: signingInputBytes,
+			kid: effective.kid,
+			allowSymmetric: options.allowSymmetricJWKSet,
+			keyCandidates
+		});
 	} catch (err) {
-		return fail(_asJWTError(err, "ERR_JWS_SIGNATURE_INVALID"), protectedHeader, unprotectedHeader);
+		return fail(asJWTError(err, INVALID_SIGNATURE), protectedHeader, unprotectedHeader);
 	}
 	if (!verified) return fail(new JWTError(`JWS signature[${index}] verification failed.`, "ERR_JWS_SIGNATURE_INVALID"), protectedHeader, unprotectedHeader);
+	try {
+		validateCriticalHeadersJWS(protectedHeader, options.recognizedHeaders);
+	} catch (err) {
+		return fail(asJWTError(err, INVALID_JWS), protectedHeader, unprotectedHeader);
+	}
 	let decodedPayload;
 	try {
-		decodedPayload = decodeJWSPayload(payload, protectedHeader.b64 !== false, options.forceUint8Array);
+		const useB64 = protectedHeader.b64 !== false;
+		decodedPayload = decodeJWSPayload(payload, useB64, payloadMode);
 	} catch (err) {
-		return fail(_asJWTError(err, "ERR_JWS_INVALID"), protectedHeader, unprotectedHeader);
+		return fail(asJWTError(err, INVALID_JWS), protectedHeader, unprotectedHeader);
 	}
 	try {
-		validateCriticalHeadersJWS(protectedHeader, options.recognizedHeaders);
-		validateJwtClaimsIfJsonPayload(decodedPayload, options);
+		validateClaimsIfJson(decodedPayload, payloadMode, options);
 	} catch (err) {
-		return fail(_asJWTError(err, "ERR_JWT_CLAIM_INVALID"), protectedHeader, unprotectedHeader);
+		return fail(asJWTError(err, INVALID_CLAIMS), protectedHeader, unprotectedHeader);
 	}
 	const outcome = {
 		signerIndex: index,
@@ -262,88 +442,96 @@ async function _verifyOneSignature(payload, wireSig, index, keyResolver, options
 	if (unprotectedHeader) outcome.signerHeader = unprotectedHeader;
 	return outcome;
 }
-function _asJWTError(err, fallbackCode, fallbackMessage) {
-	if (err instanceof JWTError) return err;
-	return new JWTError(fallbackMessage ?? (err instanceof Error ? err.message : typeof err === "string" ? err : "Unknown error"), fallbackCode, err);
-}
 async function sign(payload, key, options = {}) {
+	assertOptionEntry(options, {
+		label: "options",
+		objects: ["protectedHeader"]
+	});
+	assertNotStringKey(key);
 	const { protectedHeader: userHeader } = options;
 	let { alg } = options;
-	if (!alg) if (isJWK(key) && key.alg) alg = key.alg;
-	else throw new JWTError("JWS \"alg\" (Algorithm) must be provided in options", "ERR_JWS_ALG_MISSING");
-	if (alg === "none") throw new JWTError("\"none\" is not a valid signing algorithm", "ERR_JWS_ALG_NOT_ALLOWED");
-	const signingKey = await resolveSigningKey(alg, await importKey(key, {
-		alg,
-		expect: "private"
-	}), "sign");
-	const protectedHeader = _buildJWSHeader(alg, key, userHeader, payload);
+	if (!alg) {
+		if (isJWK(key) && key.alg) alg = key.alg;
+		else throw new JWTError("JWS \"alg\" (Algorithm) must be provided in options", "ERR_JWS_ALG_MISSING");
+	}
+	const algSupportError = checkJWSAlgSupported(alg);
+	if (algSupportError) throw algSupportError;
+	let signingKey;
+	try {
+		signingKey = await resolveSigningKey(alg, await importKey(key, {
+			alg,
+			expect: "private"
+		}), "sign");
+	} catch (error) {
+		throw asKeyUsageError(error, alg);
+	}
+	const protectedHeader = buildJWSProtectedHeader(alg, key, userHeader, { payload });
 	const computedPayload = computeJwtTimeClaims(payload, options);
-	const protectedHeaderEncoded = base64UrlEncode(JSON.stringify(protectedHeader));
-	let payloadBytes;
-	if (payload instanceof Uint8Array) payloadBytes = payload;
-	else if (typeof payload === "string") payloadBytes = textEncoder.encode(payload);
-	else if (typeof payload === "object" && payload !== null) payloadBytes = textEncoder.encode(JSON.stringify(computedPayload || payload));
-	else throw new TypeError("Payload must be a string, Uint8Array, or a JSON-serializable object.");
-	const signingInputString = `${protectedHeaderEncoded}.${protectedHeader.b64 !== false ? base64UrlEncode(payloadBytes) : textDecoder.decode(payloadBytes)}`;
+	const protectedHeaderString = serializeProtectedHeader(protectedHeader);
+	const protectedHeaderEncoded = base64UrlStringify(protectedHeaderString);
+	const payloadBytes = getPlaintextBytes(computedPayload || payload);
+	const useB64 = protectedHeader.b64 !== false;
+	let payloadEncoded;
+	if (useB64) payloadEncoded = base64UrlStringify(payloadBytes);
+	else {
+		payloadEncoded = parsePayloadText(payloadBytes);
+		if (payloadEncoded.includes(".")) throw new JWTError("Invalid JWS: unencoded compact payload must not contain \".\" (RFC 7797 §5.2).", "ERR_JWS_INVALID");
+	}
+	const signingInputString = `${protectedHeaderEncoded}.${payloadEncoded}`;
 	const signingInputBytes = textEncoder.encode(signingInputString);
-	return `${signingInputString}.${base64UrlEncode(await sign$1(alg, signingKey, signingInputBytes))}`;
+	let signatureBytes;
+	try {
+		signatureBytes = await sign$1(alg, signingKey, signingInputBytes);
+	} catch (error) {
+		throw asKeyUsageError(error, alg);
+	}
+	return `${signingInputString}.${base64UrlStringify(signatureBytes)}`;
 }
 async function verify(jws, key, options = {}) {
+	assertCompactToken(jws, "JWS");
+	assertConsumerOptions(options);
+	const payloadMode = resolvePayloadMode(options);
+	const keyCandidateLimit = resolveLimit(options.limits, "keyCandidates");
 	const parts = jws.split(".");
 	if (parts.length !== 3) throw new JWTError("Invalid JWS: Must contain three parts separated by dots.", "ERR_JWS_INVALID");
 	const [protectedHeaderEncoded, payloadEncoded, signatureEncoded] = parts;
 	const protectedHeader = decodeProtectedHeader(protectedHeaderEncoded, "JWS");
 	if (!protectedHeader.alg) throw new JWTError("Invalid JWS: Protected header must be an object with an \"alg\" property.", "ERR_JWS_INVALID");
 	const alg = protectedHeader.alg;
-	if (options.typ && protectedHeader.typ !== options.typ) throw new JWTError(`Invalid JWS: "typ" (Type) Header Parameter mismatch. Expected "${options.typ}", got "${protectedHeader.typ}".`, "ERR_JWS_INVALID");
-	let signatureBytes;
-	try {
-		signatureBytes = base64UrlDecode(signatureEncoded, { returnAs: "uint8array" });
-	} catch {
-		throw new JWTError("Invalid JWS: Signature could not be decoded.", "ERR_JWS_INVALID");
-	}
-	const keyInput = typeof key === "function" ? await key(protectedHeader, jws) : key;
-	const algError = checkAlgAllowed(alg, keyInput, options.algorithms, JWS_ALG_CTX);
+	const algSupportError = checkJWSAlgSupported(alg);
+	if (algSupportError) throw algSupportError;
+	const headerError = checkJWSB64(protectedHeader) ?? checkProtectedTyp(options.typ, protectedHeader, { family: "JWS" });
+	if (headerError) throw headerError;
+	const signatureBytes = decodeSegment(signatureEncoded, {
+		family: "JWS",
+		what: "Signature"
+	});
+	const keyInput = await resolveKeyInput(key, {
+		header: protectedHeader,
+		token: jws,
+		what: "the JWS"
+	});
+	assertNotStringKey(keyInput);
+	const algError = checkAlgAllowed(alg, keyInput, {
+		ctx: JWS_ALG_CTX,
+		algorithms: options.algorithms,
+		allowSymmetric: options.allowSymmetricJWKSet
+	});
 	if (algError) throw algError;
-	const signingInputBytes = textEncoder.encode(`${protectedHeaderEncoded}.${payloadEncoded}`);
-	if (isJWKSet(keyInput)) {
-		const candidates = getJWKsFromSet(keyInput, 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 verified = false;
-		for (const candidate of candidates) if (await verify$1(alg, await resolveSigningKey(alg, await importKey(candidate, {
-			alg,
-			expect: "public"
-		}), "verify"), signatureBytes, signingInputBytes)) {
-			verified = true;
-			break;
-		}
-		if (!verified) throw new JWTError("JWS signature verification failed.", "ERR_JWS_SIGNATURE_INVALID");
-	} else if (!await verify$1(alg, await resolveSigningKey(alg, await importKey(keyInput, {
-		alg,
-		expect: "public"
-	}), "verify"), signatureBytes, signingInputBytes)) throw new JWTError("JWS signature verification failed.", "ERR_JWS_SIGNATURE_INVALID");
-	const useB64 = protectedHeader.b64 !== false;
-	let payload;
-	try {
-		payload = decodeJWSPayload(payloadEncoded, useB64, options.forceUint8Array);
-	} catch (error_) {
-		throw new JWTError(`Invalid JWS: Payload decoding failed (${error_ instanceof Error ? error_.message : String(error_)})`, "ERR_JWS_INVALID");
-	}
+	if (!await verifyWithKey(alg, keyInput, {
+		signature: signatureBytes,
+		signingInput: textEncoder.encode(`${protectedHeaderEncoded}.${payloadEncoded}`),
+		kid: protectedHeader.kid,
+		allowSymmetric: options.allowSymmetricJWKSet,
+		keyCandidates: keyCandidateLimit
+	})) throw new JWTError("JWS signature verification failed.", "ERR_JWS_SIGNATURE_INVALID");
 	validateCriticalHeadersJWS(protectedHeader, options.recognizedHeaders);
-	validateJwtClaimsIfJsonPayload(payload, options);
+	const useB64 = protectedHeader.b64 !== false;
+	const payload = decodeJWSPayload(payloadEncoded, useB64, payloadMode);
+	validateClaimsIfJson(payload, payloadMode, options);
 	return {
 		payload,
 		protectedHeader
 	};
 }
-function _buildJWSHeader(alg, key, userHeader, payload) {
-	const safeHeader = sanitizeObjectCopy(userHeader);
-	const header = {};
-	if (isJWK(key) && key.kid) header.kid = key.kid;
-	if (safeHeader) Object.assign(header, safeHeader);
-	header.alg = alg;
-	applyTypCtyDefaults(header, payload);
-	if (header.b64 === true) delete header.b64;
-	return header;
-}
 export { generalToFlattenedJWS, sign, signMulti, verify, verifyMulti, verifyMultiAll };