@fedify/fedify 2.1.0-dev.503 → 2.1.0-dev.523

package/dist/{http-CSX1-Mgi.js → http-DJmytoC2.js}

@@ -9,11 +9,11 @@ import { encodeHex } from "byte-encodings/hex";
 import { ATTR_HTTP_REQUEST_HEADER, ATTR_HTTP_REQUEST_METHOD, ATTR_URL_FULL } from "@opentelemetry/semantic-conventions";
 import { decodeBase64, encodeBase64 } from "byte-encodings/base64";
 import { Item, decodeDict, encodeItem } from "structured-field-values";
-import { getDocumentLoader } from "@fedify/vocab-runtime";
+import { FetchError, getDocumentLoader } from "@fedify/vocab-runtime";
 
 //#region deno.json
 var name = "@fedify/fedify";
-var version = "2.1.0-dev.503+1172d43b";
+var version = "2.1.0-dev.523+150998a5";
 var license = "MIT";
 var exports = {
 	".": "./src/mod.ts",
@@ -207,24 +207,10 @@ async function importJwk(jwk, type) {
 	validateCryptoKey(key, type);
 	return key;
 }
-/**
-* Fetches a {@link CryptographicKey} or {@link Multikey} from the given URL.
-* If the given URL contains an {@link Actor} object, it tries to find
-* the corresponding key in the `publicKey` or `assertionMethod` property.
-* @template T The type of the key to fetch.  Either {@link CryptographicKey}
-*              or {@link Multikey}.
-* @param keyId The URL of the key.
-* @param cls The class of the key to fetch.  Either {@link CryptographicKey}
-*            or {@link Multikey}.
-* @param options Options for fetching the key.  See {@link FetchKeyOptions}.
-* @returns The fetched key or `null` if the key is not found.
-* @since 1.3.0
-*/
-function fetchKey(keyId, cls, options = {}) {
-	const tracerProvider = options.tracerProvider ?? trace.getTracerProvider();
+async function withFetchKeySpan(keyId, tracerProvider, fetcher) {
+	tracerProvider ??= trace.getTracerProvider();
 	const tracer = tracerProvider.getTracer(deno_default.name, deno_default.version);
-	keyId = typeof keyId === "string" ? new URL(keyId) : keyId;
-	return tracer.startActiveSpan("activitypub.fetch_key", {
+	return await tracer.startActiveSpan("activitypub.fetch_key", {
 		kind: SpanKind.CLIENT,
 		attributes: {
 			"http.method": "GET",
@@ -237,7 +223,7 @@ function fetchKey(keyId, cls, options = {}) {
 		}
 	}, async (span) => {
 		try {
-			const result = await fetchKeyInternal(keyId, cls, options);
+			const result = await fetcher();
 			span.setAttribute("activitypub.actor.key.cached", result.cached);
 			return result;
 		} catch (e) {
@@ -251,43 +237,105 @@ function fetchKey(keyId, cls, options = {}) {
 		}
 	});
 }
-async function fetchKeyInternal(keyId, cls, { documentLoader, contextLoader, keyCache, tracerProvider } = {}) {
-	const logger = getLogger([
-		"fedify",
-		"sig",
-		"key"
-	]);
+/**
+* Fetches a {@link CryptographicKey} or {@link Multikey} from the given URL.
+* If the given URL contains an {@link Actor} object, it tries to find
+* the corresponding key in the `publicKey` or `assertionMethod` property.
+* @template T The type of the key to fetch.  Either {@link CryptographicKey}
+*              or {@link Multikey}.
+* @param keyId The URL of the key.
+* @param cls The class of the key to fetch.  Either {@link CryptographicKey}
+*            or {@link Multikey}.
+* @param options Options for fetching the key.  See {@link FetchKeyOptions}.
+* @returns The fetched key or `null` if the key is not found.
+* @since 1.3.0
+*/
+function fetchKey(keyId, cls, options = {}) {
+	keyId = typeof keyId === "string" ? new URL(keyId) : keyId;
+	return withFetchKeySpan(keyId, options.tracerProvider, () => fetchKeyInternal(keyId, cls, options));
+}
+/**
+* Fetches a {@link CryptographicKey} or {@link Multikey} from the given URL,
+* preserving transport-level fetch failures for callers that need to inspect
+* why the key could not be loaded.
+*
+* @template T The type of the key to fetch.  Either {@link CryptographicKey}
+*              or {@link Multikey}.
+* @param keyId The URL of the key.
+* @param cls The class of the key to fetch.  Either {@link CryptographicKey}
+*            or {@link Multikey}.
+* @param options Options for fetching the key.
+* @returns The fetched key, or detailed fetch failure information.
+* @since 2.1.0
+*/
+async function fetchKeyDetailed(keyId, cls, options = {}) {
 	const cacheKey = typeof keyId === "string" ? new URL(keyId) : keyId;
-	keyId = typeof keyId === "string" ? keyId : keyId.href;
-	if (keyCache != null) {
-		const cachedKey = await keyCache.get(cacheKey);
-		if (cachedKey instanceof cls && cachedKey.publicKey != null) {
-			logger.debug("Key {keyId} found in cache.", { keyId });
+	return await withFetchKeySpan(cacheKey, options.tracerProvider, async () => {
+		return await fetchKeyWithResult(cacheKey, cls, options, async (cacheKey$1, keyId$1, keyCache, logger) => {
+			const fetchError = await keyCache?.getFetchError?.(cacheKey$1);
+			if (fetchError != null) {
+				logger.debug("Entry {keyId} found in cache with preserved fetch failure details.", { keyId: keyId$1 });
+				return {
+					key: null,
+					cached: true,
+					fetchError
+				};
+			}
+			logger.debug("Entry {keyId} found in cache, but no fetch failure details are available.", { keyId: keyId$1 });
 			return {
-				key: cachedKey,
+				key: null,
 				cached: true
 			};
-		} else if (cachedKey === null) {
-			logger.debug("Entry {keyId} found in cache, but it is unavailable.", { keyId });
+		}, async (error, cacheKey$1, keyId$1, keyCache, logger) => {
+			logger.debug("Failed to fetch key {keyId}.", {
+				keyId: keyId$1,
+				error
+			});
+			await keyCache?.set(cacheKey$1, null);
+			if (error instanceof FetchError && error.response != null) {
+				const fetchError$1 = {
+					status: error.response.status,
+					response: error.response.clone()
+				};
+				await keyCache?.setFetchError?.(cacheKey$1, fetchError$1);
+				return {
+					key: null,
+					cached: false,
+					fetchError: fetchError$1
+				};
+			}
+			const fetchError = { error: error instanceof Error ? error : new Error(String(error)) };
+			await keyCache?.setFetchError?.(cacheKey$1, fetchError);
 			return {
 				key: null,
-				cached: true
+				cached: false,
+				fetchError
 			};
-		}
-	}
-	logger.debug("Fetching key {keyId} to verify signature...", { keyId });
-	let document;
-	try {
-		const remoteDocument = await (documentLoader ?? getDocumentLoader())(keyId);
-		document = remoteDocument.document;
-	} catch (_) {
-		logger.debug("Failed to fetch key {keyId}.", { keyId });
-		await keyCache?.set(cacheKey, null);
+		});
+	});
+}
+async function getCachedFetchKey(cacheKey, keyId, cls, keyCache, logger) {
+	if (keyCache == null) return null;
+	const cachedKey = await keyCache.get(cacheKey);
+	if (cachedKey instanceof cls && cachedKey.publicKey != null) {
+		logger.debug("Key {keyId} found in cache.", { keyId });
+		return {
+			key: cachedKey,
+			cached: true
+		};
+	} else if (cachedKey === null) {
+		logger.debug("Entry {keyId} found in cache, but it is unavailable.", { keyId });
 		return {
 			key: null,
-			cached: false
+			cached: true
 		};
 	}
+	return null;
+}
+async function clearFetchErrorMetadata(keyId, keyCache) {
+	await keyCache?.setFetchError?.(keyId, null);
+}
+async function resolveFetchedKey(document, cacheKey, keyId, cls, { documentLoader, contextLoader, keyCache, tracerProvider }, logger) {
 	let object;
 	try {
 		object = await Object$1.fromJsonLd(document, {
@@ -307,6 +355,7 @@ async function fetchKeyInternal(keyId, cls, { documentLoader, contextLoader, key
 			if (e$1 instanceof TypeError) {
 				logger.debug("Failed to verify; key {keyId} returned an invalid object.", { keyId });
 				await keyCache?.set(cacheKey, null);
+				await clearFetchErrorMetadata(cacheKey, keyCache);
 				return {
 					key: null,
 					cached: false
@@ -345,6 +394,7 @@ async function fetchKeyInternal(keyId, cls, { documentLoader, contextLoader, key
 				actorType: object.constructor.name
 			});
 			await keyCache?.set(cacheKey, null);
+			await clearFetchErrorMetadata(cacheKey, keyCache);
 			return {
 				key: null,
 				cached: false
@@ -353,6 +403,7 @@ async function fetchKeyInternal(keyId, cls, { documentLoader, contextLoader, key
 	} else {
 		logger.debug("Failed to verify; key {keyId} returned an invalid object.", { keyId });
 		await keyCache?.set(cacheKey, null);
+		await clearFetchErrorMetadata(cacheKey, keyCache);
 		return {
 			key: null,
 			cached: false
@@ -361,6 +412,7 @@ async function fetchKeyInternal(keyId, cls, { documentLoader, contextLoader, key
 	if (key.publicKey == null) {
 		logger.debug("Failed to verify; key {keyId} has no publicKeyPem field.", { keyId });
 		await keyCache?.set(cacheKey, null);
+		await clearFetchErrorMetadata(cacheKey, keyCache);
 		return {
 			key: null,
 			cached: false
@@ -370,11 +422,57 @@ async function fetchKeyInternal(keyId, cls, { documentLoader, contextLoader, key
 		await keyCache.set(cacheKey, key);
 		logger.debug("Key {keyId} cached.", { keyId });
 	}
+	await clearFetchErrorMetadata(cacheKey, keyCache);
 	return {
 		key,
 		cached: false
 	};
 }
+async function fetchKeyWithResult(cacheKey, cls, options, onCachedUnavailable, onFetchError) {
+	const logger = getLogger([
+		"fedify",
+		"sig",
+		"key"
+	]);
+	const keyId = cacheKey.href;
+	const keyCache = options.keyCache;
+	const cached = await getCachedFetchKey(cacheKey, keyId, cls, keyCache, logger);
+	if (cached?.key === null && cached.cached) return await onCachedUnavailable(cacheKey, keyId, keyCache, logger);
+	if (cached != null) return cached;
+	logger.debug("Fetching key {keyId} to verify signature...", { keyId });
+	let document;
+	try {
+		const remoteDocument = await (options.documentLoader ?? getDocumentLoader())(keyId);
+		document = remoteDocument.document;
+	} catch (error) {
+		return await onFetchError(error, cacheKey, keyId, keyCache, logger);
+	}
+	return await resolveFetchedKey(document, cacheKey, keyId, cls, options, logger);
+}
+async function fetchKeyInternal(keyId, cls, options = {}) {
+	const cacheKey = typeof keyId === "string" ? new URL(keyId) : keyId;
+	return await fetchKeyWithResult(cacheKey, cls, options, (_cacheKey, _keyId, _keyCache, _logger) => {
+		return {
+			key: null,
+			cached: true
+		};
+	}, async (error, cacheKey$1, keyId$1, keyCache, logger) => {
+		logger.debug("Failed to fetch key {keyId}.", {
+			keyId: keyId$1,
+			error
+		});
+		await keyCache?.set(cacheKey$1, null);
+		if (error instanceof FetchError && error.response != null) await keyCache?.setFetchError?.(cacheKey$1, {
+			status: error.response.status,
+			response: error.response.clone()
+		});
+		else await keyCache?.setFetchError?.(cacheKey$1, { error: error instanceof Error ? error : new Error(String(error)) });
+		return {
+			key: null,
+			cached: false
+		};
+	});
+}
 
 //#endregion
 //#region src/sig/http.ts
@@ -604,6 +702,55 @@ const supportedHashAlgorithms = {
 	"sha-256": "SHA-256",
 	"sha-512": "SHA-512"
 };
+function noSignatureResult() {
+	return {
+		verified: false,
+		reason: { type: "noSignature" }
+	};
+}
+function invalidSignatureResult(keyId) {
+	return keyId == null ? {
+		verified: false,
+		reason: { type: "invalidSignature" }
+	} : {
+		verified: false,
+		reason: {
+			type: "invalidSignature",
+			keyId
+		}
+	};
+}
+function keyFetchErrorResult(keyId, result) {
+	return {
+		verified: false,
+		reason: {
+			type: "keyFetchError",
+			keyId,
+			result
+		}
+	};
+}
+function parseKeyId(value) {
+	if (value == null) return null;
+	try {
+		return new URL(value);
+	} catch {
+		return null;
+	}
+}
+function getKeyFetchErrorName(error) {
+	return error.name || error.constructor.name || "Error";
+}
+function recordVerificationResult(span, result) {
+	span.setAttribute("http_signatures.verified", result.verified);
+	if (result.verified === true) return;
+	const reason = result.reason;
+	span.setAttribute("http_signatures.failure_reason", reason.type);
+	if ("keyId" in reason && reason.keyId != null) span.setAttribute("http_signatures.key_id", reason.keyId.href);
+	if (reason.type !== "keyFetchError") return;
+	if ("status" in reason.result) span.setAttribute("http_signatures.key_fetch_status", reason.result.status);
+	else span.setAttribute("http_signatures.key_fetch_error", getKeyFetchErrorName(reason.result.error));
+}
 /**
 * Verifies the signature of a request.
 *
@@ -618,6 +765,19 @@ const supportedHashAlgorithms = {
 *          could not be verified.
 */
 async function verifyRequest(request, options = {}) {
+	const result = await verifyRequestDetailed(request, options);
+	return result.verified ? result.key : null;
+}
+/**
+* Verifies the signature of a request and returns a structured failure reason
+* when verification does not succeed.
+*
+* @param request The request to verify.
+* @param options Options for verifying the request.
+* @returns The verified public key, or a structured verification failure.
+* @since 2.1.0
+*/
+async function verifyRequestDetailed(request, options = {}) {
 	const tracerProvider = options.tracerProvider ?? trace.getTracerProvider();
 	const tracer = tracerProvider.getTracer(deno_default.name, deno_default.version);
 	return await tracer.startActiveSpan("http_signatures.verify", async (span) => {
@@ -629,11 +789,12 @@ async function verifyRequest(request, options = {}) {
 		try {
 			let spec = options.spec;
 			if (spec == null) spec = request.headers.has("Signature-Input") ? "rfc9421" : "draft-cavage-http-signatures-12";
-			let key;
-			if (spec === "rfc9421") key = await verifyRequestRfc9421(request, span, options);
-			else key = await verifyRequestDraft(request, span, options);
-			if (key == null) span.setStatus({ code: SpanStatusCode.ERROR });
-			return key;
+			let result;
+			if (spec === "rfc9421") result = await verifyRequestRfc9421(request, span, options);
+			else result = await verifyRequestDraft(request, span, options);
+			recordVerificationResult(span, result);
+			if (!result.verified) span.setStatus({ code: SpanStatusCode.ERROR });
+			return result;
 		} catch (error) {
 			span.setStatus({
 				code: SpanStatusCode.ERROR,
@@ -653,27 +814,29 @@ async function verifyRequestDraft(request, span, { documentLoader, contextLoader
 	]);
 	if (request.bodyUsed) {
 		logger.error("Failed to verify; the request body is already consumed.", { url: request.url });
-		return null;
+		return noSignatureResult();
 	} else if (request.body?.locked) {
 		logger.error("Failed to verify; the request body is locked.", { url: request.url });
-		return null;
+		return noSignatureResult();
 	}
 	const originalRequest = request;
 	request = request.clone();
-	const dateHeader = request.headers.get("Date");
-	if (dateHeader == null) {
-		logger.debug("Failed to verify; no Date header found.", { headers: Object.fromEntries(request.headers.entries()) });
-		return null;
-	}
 	const sigHeader = request.headers.get("Signature");
 	if (sigHeader == null) {
 		logger.debug("Failed to verify; no Signature header found.", { headers: Object.fromEntries(request.headers.entries()) });
-		return null;
+		return noSignatureResult();
+	}
+	const sigValues = Object.fromEntries(sigHeader.split(",").map((pair) => pair.match(/^\s*([A-Za-z]+)=(?:"([^"]*)"|(\d+))\s*$/)).filter((m) => m != null).map((m) => [m[1], m[2] ?? m[3]]));
+	const parsedKeyId = parseKeyId(sigValues.keyId);
+	const dateHeader = request.headers.get("Date");
+	if (dateHeader == null) {
+		logger.debug("Failed to verify; no Date header found.", { headers: Object.fromEntries(request.headers.entries()) });
+		return invalidSignatureResult(parsedKeyId);
 	}
 	const digestHeader = request.headers.get("Digest");
 	if (request.method !== "GET" && request.method !== "HEAD" && digestHeader == null) {
 		logger.debug("Failed to verify; no Digest header found.", { headers: Object.fromEntries(request.headers.entries()) });
-		return null;
+		return invalidSignatureResult(parsedKeyId);
 	}
 	let body = null;
 	if (digestHeader != null) {
@@ -691,7 +854,7 @@ async function verifyRequestDraft(request, span, { documentLoader, contextLoader
 					digest: digestBase64,
 					error
 				});
-				return null;
+				return invalidSignatureResult(parsedKeyId);
 			}
 			if (span.isRecording()) span.setAttribute(`http_signatures.digest.${algo}`, encodeHex(digest));
 			const expectedDigest = await crypto.subtle.digest(supportedHashAlgorithms[algo], body);
@@ -701,7 +864,7 @@ async function verifyRequestDraft(request, span, { documentLoader, contextLoader
 					digest: digestBase64,
 					expectedDigest: encodeBase64(expectedDigest)
 				});
-				return null;
+				return invalidSignatureResult(parsedKeyId);
 			}
 			matched = true;
 		}
@@ -710,7 +873,7 @@ async function verifyRequestDraft(request, span, { documentLoader, contextLoader
 				supportedAlgorithms: Object.keys(supportedHashAlgorithms),
 				algorithms: digests.map(([algo]) => algo)
 			});
-			return null;
+			return invalidSignatureResult(parsedKeyId);
 		}
 	}
 	const date = Temporal.Instant.from(new Date(dateHeader).toISOString());
@@ -722,25 +885,24 @@ async function verifyRequestDraft(request, span, { documentLoader, contextLoader
 				date: date.toString(),
 				now: now.toString()
 			});
-			return null;
+			return invalidSignatureResult(parsedKeyId);
 		} else if (Temporal.Instant.compare(date, now.subtract(tw)) < 0) {
 			logger.debug("Failed to verify; Date is too far in the past.", {
 				date: date.toString(),
 				now: now.toString()
 			});
-			return null;
+			return invalidSignatureResult(parsedKeyId);
 		}
 	}
-	const sigValues = Object.fromEntries(sigHeader.split(",").map((pair) => pair.match(/^\s*([A-Za-z]+)=(?:"([^"]*)"|(\d+))\s*$/)).filter((m) => m != null).map((m) => [m[1], m[2] ?? m[3]]));
 	if (!("keyId" in sigValues)) {
 		logger.debug("Failed to verify; no keyId field found in the Signature header.", { signature: sigHeader });
-		return null;
+		return invalidSignatureResult(null);
 	} else if (!("headers" in sigValues)) {
 		logger.debug("Failed to verify; no headers field found in the Signature header.", { signature: sigHeader });
-		return null;
+		return invalidSignatureResult(parsedKeyId);
 	} else if (!("signature" in sigValues)) {
 		logger.debug("Failed to verify; no signature field found in the Signature header.", { signature: sigHeader });
-		return null;
+		return invalidSignatureResult(parsedKeyId);
 	}
 	if ("expires" in sigValues) {
 		const expiresSeconds = parseInt(sigValues.expires);
@@ -749,7 +911,7 @@ async function verifyRequestDraft(request, span, { documentLoader, contextLoader
 				expires: sigValues.expires,
 				signature: sigHeader
 			});
-			return null;
+			return invalidSignatureResult(parsedKeyId);
 		}
 		const expires = Temporal.Instant.fromEpochMilliseconds(expiresSeconds * 1e3);
 		if (Temporal.Instant.compare(now, expires) > 0) {
@@ -758,7 +920,7 @@ async function verifyRequestDraft(request, span, { documentLoader, contextLoader
 				now: now.toString(),
 				signature: sigHeader
 			});
-			return null;
+			return invalidSignatureResult(parsedKeyId);
 		}
 	}
 	if ("created" in sigValues) {
@@ -768,7 +930,7 @@ async function verifyRequestDraft(request, span, { documentLoader, contextLoader
 				created: sigValues.created,
 				signature: sigHeader
 			});
-			return null;
+			return invalidSignatureResult(parsedKeyId);
 		}
 		if (timeWindow !== false) {
 			const created = Temporal.Instant.fromEpochMilliseconds(createdSeconds * 1e3);
@@ -778,34 +940,37 @@ async function verifyRequestDraft(request, span, { documentLoader, contextLoader
 					created: created.toString(),
 					now: now.toString()
 				});
-				return null;
+				return invalidSignatureResult(parsedKeyId);
 			} else if (Temporal.Instant.compare(created, now.subtract(tw)) < 0) {
 				logger.debug("Failed to verify; created is too far in the past.", {
 					created: created.toString(),
 					now: now.toString()
 				});
-				return null;
+				return invalidSignatureResult(parsedKeyId);
 			}
 		}
 	}
 	const { keyId, headers, signature } = sigValues;
+	const keyIdUrl = parseKeyId(keyId);
+	if (keyIdUrl == null) return invalidSignatureResult(null);
 	span?.setAttribute("http_signatures.key_id", keyId);
 	if ("algorithm" in sigValues) span?.setAttribute("http_signatures.algorithm", sigValues.algorithm);
-	const { key, cached } = await fetchKey(new URL(keyId), CryptographicKey, {
+	const { key, cached, fetchError } = await fetchKeyDetailed(keyIdUrl, CryptographicKey, {
 		documentLoader,
 		contextLoader,
 		keyCache,
 		tracerProvider
 	});
-	if (key == null) return null;
+	if (fetchError != null) return keyFetchErrorResult(keyIdUrl, fetchError);
+	if (key == null) return invalidSignatureResult(keyIdUrl);
 	const headerNames = headers.split(/\s+/g);
 	if (!headerNames.includes("(request-target)") || !headerNames.includes("date")) {
 		logger.debug("Failed to verify; required headers missing in the Signature header: {headers}.", { headers });
-		return null;
+		return invalidSignatureResult(keyIdUrl);
 	}
 	if (body != null && !headerNames.includes("digest")) {
 		logger.debug("Failed to verify; required headers missing in the Signature header: {headers}.", { headers });
-		return null;
+		return invalidSignatureResult(keyIdUrl);
 	}
 	const message = headerNames.map((name$1) => `${name$1}: ` + (name$1 === "(request-target)" ? `${request.method.toLowerCase()} ${new URL(request.url).pathname}` : name$1 === "(created)" ? sigValues.created ?? "" : name$1 === "(expires)" ? sigValues.expires ?? "" : name$1 === "host" ? request.headers.get("host") ?? new URL(request.url).host : request.headers.get(name$1))).join("\n");
 	const sig = decodeBase64(signature);
@@ -818,7 +983,7 @@ async function verifyRequestDraft(request, span, { documentLoader, contextLoader
 				signature,
 				message
 			});
-			return await verifyRequest(originalRequest, {
+			return await verifyRequestDetailed(originalRequest, {
 				documentLoader,
 				contextLoader,
 				timeWindow,
@@ -834,9 +999,12 @@ async function verifyRequestDraft(request, span, { documentLoader, contextLoader
 			signature,
 			message
 		});
-		return null;
+		return invalidSignatureResult(keyIdUrl);
 	}
-	return key;
+	return {
+		verified: true,
+		key
+	};
 }
 /**
 * RFC 9421 map of algorithm identifiers to WebCrypto algorithms
@@ -907,22 +1075,22 @@ async function verifyRequestRfc9421(request, span, { documentLoader, contextLoad
 	]);
 	if (request.bodyUsed) {
 		logger.error("Failed to verify; the request body is already consumed.", { url: request.url });
-		return null;
+		return noSignatureResult();
 	} else if (request.body?.locked) {
 		logger.error("Failed to verify; the request body is locked.", { url: request.url });
-		return null;
+		return noSignatureResult();
 	}
 	const originalRequest = request;
 	request = request.clone();
 	const signatureInputHeader = request.headers.get("Signature-Input");
 	if (!signatureInputHeader) {
 		logger.debug("Failed to verify; no Signature-Input header found.", { headers: Object.fromEntries(request.headers.entries()) });
-		return null;
+		return noSignatureResult();
 	}
 	const signatureHeader = request.headers.get("Signature");
 	if (!signatureHeader) {
 		logger.debug("Failed to verify; no Signature header found.", { headers: Object.fromEntries(request.headers.entries()) });
-		return null;
+		return noSignatureResult();
 	}
 	const signatureInputs = parseRfc9421SignatureInput(signatureInputHeader);
 	logger.debug("Parsed Signature-Input header: {signatureInputs}", { signatureInputs });
@@ -930,18 +1098,23 @@ async function verifyRequestRfc9421(request, span, { documentLoader, contextLoad
 	const signatureNames = Object.keys(signatureInputs);
 	if (signatureNames.length === 0) {
 		logger.debug("Failed to verify; no valid signatures found in Signature-Input header.", { header: signatureInputHeader });
-		return null;
+		return invalidSignatureResult(null);
 	}
-	let validKey = null;
+	let failure = noSignatureResult();
 	for (const sigName of signatureNames) {
-		if (!signatures[sigName]) continue;
+		if (!signatures[sigName]) {
+			failure = invalidSignatureResult(parseKeyId(signatureInputs[sigName]?.keyId));
+			continue;
+		}
 		const sigInput = signatureInputs[sigName];
 		const sigBytes = signatures[sigName];
+		const keyId = parseKeyId(sigInput.keyId);
 		if (!sigInput.keyId) {
 			logger.debug("Failed to verify; missing keyId in signature {signatureName}.", {
 				signatureName: sigName,
 				signatureInput: signatureInputHeader
 			});
+			failure = invalidSignatureResult(null);
 			continue;
 		}
 		if (!sigInput.created) {
@@ -949,6 +1122,7 @@ async function verifyRequestRfc9421(request, span, { documentLoader, contextLoad
 				signatureName: sigName,
 				signatureInput: signatureInputHeader
 			});
+			failure = invalidSignatureResult(keyId);
 			continue;
 		}
 		const signatureCreated = Temporal.Instant.fromEpochMilliseconds(sigInput.created * 1e3);
@@ -960,12 +1134,14 @@ async function verifyRequestRfc9421(request, span, { documentLoader, contextLoad
 					created: signatureCreated.toString(),
 					now: now.toString()
 				});
+				failure = invalidSignatureResult(keyId);
 				continue;
 			} else if (Temporal.Instant.compare(signatureCreated, now.subtract(tw)) < 0) {
 				logger.debug("Failed to verify; signature created time is too far in the past.", {
 					created: signatureCreated.toString(),
 					now: now.toString()
 				});
+				failure = invalidSignatureResult(keyId);
 				continue;
 			}
 		}
@@ -973,25 +1149,36 @@ async function verifyRequestRfc9421(request, span, { documentLoader, contextLoad
 			const contentDigestHeader = request.headers.get("Content-Digest");
 			if (!contentDigestHeader) {
 				logger.debug("Failed to verify; Content-Digest header required but not found.", { components: sigInput.components });
+				failure = invalidSignatureResult(keyId);
 				continue;
 			}
 			const body = await request.arrayBuffer();
 			const digestValid = await verifyRfc9421ContentDigest(contentDigestHeader, body);
 			if (!digestValid) {
 				logger.debug("Failed to verify; Content-Digest verification failed.", { contentDigest: contentDigestHeader });
+				failure = invalidSignatureResult(keyId);
 				continue;
 			}
 		}
 		span?.setAttribute("http_signatures.key_id", sigInput.keyId);
 		span?.setAttribute("http_signatures.created", sigInput.created.toString());
-		const { key, cached } = await fetchKey(new URL(sigInput.keyId), CryptographicKey, {
+		if (keyId == null) {
+			failure = invalidSignatureResult(null);
+			continue;
+		}
+		const { key, cached, fetchError } = await fetchKeyDetailed(keyId, CryptographicKey, {
 			documentLoader,
 			contextLoader,
 			keyCache,
 			tracerProvider
 		});
+		if (fetchError != null) {
+			failure = keyFetchErrorResult(keyId, fetchError);
+			continue;
+		}
 		if (!key) {
 			logger.debug("Failed to fetch key: {keyId}", { keyId: sigInput.keyId });
+			failure = invalidSignatureResult(keyId);
 			continue;
 		}
 		let alg = sigInput.alg?.toLowerCase();
@@ -1008,6 +1195,7 @@ async function verifyRequestRfc9421(request, span, { documentLoader, contextLoad
 				algorithm: sigInput.alg,
 				supported: Object.keys(rfc9421AlgorithmMap)
 			});
+			failure = invalidSignatureResult(keyId);
 			continue;
 		}
 		let signatureBase;
@@ -1018,41 +1206,47 @@ async function verifyRequestRfc9421(request, span, { documentLoader, contextLoad
 				error,
 				signatureInput: sigInput
 			});
+			failure = invalidSignatureResult(keyId);
 			continue;
 		}
 		const signatureBaseBytes = new TextEncoder().encode(signatureBase);
 		span?.setAttribute("http_signatures.signature", encodeHex(sigBytes));
 		try {
 			const verified = await crypto.subtle.verify(algorithm, key.publicKey, sigBytes.slice(), signatureBaseBytes);
-			if (verified) {
-				validKey = key;
-				break;
-			} else if (cached) {
+			if (verified) return {
+				verified: true,
+				key
+			};
+			else if (cached) {
 				logger.debug("Failed to verify with cached key {keyId}; retrying with fresh key...", { keyId: sigInput.keyId });
-				return await verifyRequest(originalRequest, {
+				return await verifyRequestDetailed(originalRequest, {
 					documentLoader,
 					contextLoader,
 					timeWindow,
 					currentTime,
 					keyCache: {
 						get: () => Promise.resolve(void 0),
-						set: async (keyId, key$1) => await keyCache?.set(keyId, key$1)
+						set: async (keyId$1, key$1) => await keyCache?.set(keyId$1, key$1)
 					},
 					spec: "rfc9421"
 				});
-			} else logger.debug("Failed to verify signature with fetched key {keyId}; signature invalid.", {
-				keyId: sigInput.keyId,
-				signatureBase
-			});
+			} else {
+				logger.debug("Failed to verify signature with fetched key {keyId}; signature invalid.", {
+					keyId: sigInput.keyId,
+					signatureBase
+				});
+				failure = invalidSignatureResult(keyId);
+			}
 		} catch (error) {
 			logger.debug("Error during signature verification: {error}", {
 				error,
 				keyId: sigInput.keyId,
 				algorithm: sigInput.alg
 			});
+			failure = invalidSignatureResult(keyId);
 		}
 	}
-	return validKey;
+	return failure;
 }
 /**
 * Helper function to create a new Request for redirect handling.
@@ -1170,4 +1364,4 @@ function timingSafeEqual(a, b) {
 }
 
 //#endregion
-export { deno_default, doubleKnock, exportJwk, fetchKey, generateCryptoKeyPair, importJwk, signRequest, validateCryptoKey, verifyRequest };
+export { deno_default, doubleKnock, exportJwk, fetchKey, fetchKeyDetailed, generateCryptoKeyPair, importJwk, signRequest, validateCryptoKey, verifyRequest, verifyRequestDetailed };