@fedify/fedify 2.4.0-dev.2103 → 2.4.0-dev.2115

package/dist/{http-tTlTeFa0.js → http-Ce6_Lf7k.js}

@@ -14,7 +14,7 @@ import serialize from "json-canon";
 import { ATTR_HTTP_REQUEST_HEADER, ATTR_HTTP_REQUEST_METHOD, ATTR_URL_FULL } from "@opentelemetry/semantic-conventions";
 //#region deno.json
 var name = "@fedify/fedify";
-var version = "2.4.0-dev.2103+3be829c0";
+var version = "2.4.0-dev.2115+e2feaf2b";
 //#endregion
 //#region src/sig/portable-key-id.ts
 const COMPATIBLE_KEY_ID_PATH_PATTERN = /^\/\.well-known\/apgateway\/did(?::|%3A)/i;
@@ -70,8 +70,9 @@ function hasPortableActor(activity) {
 /**
 * Checks whether a key ID looks like an [FEP-ef61] compatible identifier,
 * i.e., an HTTP(S) URL under a gateway's `/.well-known/apgateway/did:` path.
-* Such a key ID names a key that a gateway holds for a portable actor, so it
-* is resolved only as a gateway key, and never cached in a key cache.
+* Such a key ID may name a key that a gateway holds for a portable actor,
+* which only HTTP Signatures accept, so what it resolves to is cached apart
+* for each purpose, never under the key ID itself.
 *
 * [FEP-ef61]: https://w3id.org/fep/ef61
 * @internal
@@ -1315,6 +1316,32 @@ async function verifyKeyOwnership(key, options = {}) {
 	});
 	return null;
 }
+/**
+* Wraps a key cache so that lookups through the wrapper miss, while
+* whatever they resolve is still written to the cache.  It is used to retry
+* a verification that failed with a cached key with a freshly fetched one.
+* @param keyCache The key cache to wrap.
+* @returns The wrapped key cache.
+* @internal
+*/
+function bypassKeyCacheReads(keyCache) {
+	const cache = keyCache;
+	const bypassed = {
+		get: () => Promise.resolve(void 0),
+		set: async (keyId, key) => await cache?.set(keyId, key),
+		getFetchError: () => Promise.resolve(void 0),
+		setFetchError: async (keyId, error) => await cache?.setFetchError?.(keyId, error)
+	};
+	if (cache?.compatibleKeyScope != null) bypassed.compatibleKeyScope = (scope) => {
+		const scoped = cache.compatibleKeyScope(scope);
+		return {
+			get: () => Promise.resolve(void 0),
+			set: async (keyId, key, options) => await scoped.set(keyId, key, options),
+			delete: async (keyId) => await scoped.delete(keyId)
+		};
+	};
+	return bypassed;
+}
 async function withFetchKeySpan(keyId, tracerProvider, fetcher) {
 	tracerProvider ??= trace.getTracerProvider();
 	return await tracerProvider.getTracer(name, version).startActiveSpan("activitypub.fetch_key", {
@@ -1351,9 +1378,9 @@ async function withFetchKeySpan(keyId, tracerProvider, fetcher) {
 * Gateway keys of [FEP-ef61] portable actors, i.e., keys whose IDs are
 * compatible identifiers that dereference to portable actor documents, are
 * not resolved by this function, as they only authenticate HTTP requests;
-* use `verifyRequest()` or `getKeyOwner()` for them instead.  Keys
-* whose IDs are compatible identifiers are never read from or written to
-* the key cache.
+* use `verifyRequest()` or `getKeyOwner()` for them instead.  Keys whose IDs
+* are compatible identifiers are never read from or written to the key
+* cache under their IDs, except for failures to fetch them.
 *
 * [FEP-ef61]: https://w3id.org/fep/ef61
 * @template T The type of the key to fetch.  Either {@link CryptographicKey}
@@ -1376,9 +1403,9 @@ function fetchKey(keyId, cls, options = {}) {
 * Gateway keys of [FEP-ef61] portable actors, i.e., keys whose IDs are
 * compatible identifiers that dereference to portable actor documents, are
 * not resolved by this function, as they only authenticate HTTP requests;
-* use `verifyRequest()` or `getKeyOwner()` for them instead.  Keys
-* whose IDs are compatible identifiers are never read from or written to
-* the key cache.
+* use `verifyRequest()` or `getKeyOwner()` for them instead.  Keys whose IDs
+* are compatible identifiers are never read from or written to the key
+* cache under their IDs, except for failures to fetch them.
 *
 * [FEP-ef61]: https://w3id.org/fep/ef61
 *
@@ -1561,11 +1588,13 @@ async function resolveFetchedKey(document, cacheKey, documentUrl, keyId, cls, {
 		}
 	}
 	if (isCompatibleKeyId(cacheKey) && isPortableActorDocument(object)) {
+		const scopedCache = keyCache;
 		if (portableGatewayKeyResolver == null || cls !== CryptographicKey) {
 			logger.debug("Failed to verify; key {keyId} is a gateway key of the portable actor {actorId}, which is only accepted for HTTP Signatures.", {
 				keyId,
 				actorId: object.id?.href
 			});
+			await scopedCache?.set(cacheKey, null);
 			return {
 				key: null,
 				cached: false
@@ -1577,11 +1606,13 @@ async function resolveFetchedKey(document, cacheKey, documentUrl, keyId, cls, {
 				keyId,
 				actorId: object.id?.href
 			});
+			await scopedCache?.set(cacheKey, null);
 			return {
 				key: null,
 				cached: false
 			};
 		}
+		await scopedCache?.set(cacheKey, resolution.key, { expires: resolution.expires });
 		return {
 			key: resolution.key,
 			cached: false
@@ -1710,8 +1741,9 @@ async function resolveFetchedKey(document, cacheKey, documentUrl, keyId, cls, {
 }
 /**
 * Tells whether a key claims a portable actor as its owner.  Such a key can
-* only be a gateway key, which is never cached, so a cached one was cached
-* by an older version that trusted web origins, and is fetched again.
+* only be a gateway key, which is never cached under its ID, so a cached one
+* was cached by an older version that trusted web origins, and is fetched
+* again.
 */
 function claimsPortableOwner(key) {
 	const ownerId = key instanceof CryptographicKey ? key.ownerId : key?.controllerId;
@@ -1727,11 +1759,12 @@ async function fetchKeyWithResult(cacheKey, cls, options, onCachedUnavailable, o
 			"key"
 		]);
 		const keyId = cacheKey.href;
-		if (isCompatibleKeyId(cacheKey)) options = {
-			...options,
-			keyCache: void 0
-		};
 		const keyCache = options.keyCache;
+		if (isCompatibleKeyId(cacheKey)) {
+			const result = await fetchCompatibleKey(cacheKey, cls, options, onCachedUnavailable, onFetchError, logger);
+			outcome = result.outcome;
+			return result.result;
+		}
 		const didKey = await resolveDidKey(cacheKey, cls, keyCache, logger);
 		if (didKey != null) {
 			outcome = { result: didKey.key == null ? "invalid" : didKey.cached ? "hit" : "fetched" };
@@ -1773,6 +1806,65 @@ async function fetchKeyWithResult(cacheKey, cls, options, onCachedUnavailable, o
 		});
 	}
 }
+/**
+* Tells which purpose a lookup of a key at a compatible identifier serves.
+*/
+function getCompatibleKeyScope(cls, options) {
+	if (cls !== CryptographicKey) return "multikey";
+	return options.portableGatewayKeyResolver == null ? "cryptographicKey" : "httpSignature";
+}
+/**
+* Looks up a key at an [FEP-ef61] compatible identifier.  Such a key may be
+* a gateway key of a portable actor, which is accepted for some purposes but
+* not for others, so everything resolved from the document at the key ID is
+* cached in a namespace of the lookup's purpose, and one purpose never reuses
+* what another resolved, nor what another rejected.  A failure to fetch
+* the document fails every purpose alike, so it is cached in the shared
+* namespace, as for any other key.
+*
+* [FEP-ef61]: https://w3id.org/fep/ef61
+*/
+async function fetchCompatibleKey(cacheKey, cls, options, onCachedUnavailable, onFetchError, logger) {
+	const keyId = cacheKey.href;
+	const sharedCache = options.keyCache;
+	const scopedCache = sharedCache?.compatibleKeyScope?.(getCompatibleKeyScope(cls, options));
+	const cached = await getCachedFetchKey(cacheKey, keyId, cls, scopedCache, logger);
+	if (cached != null) return {
+		result: cached,
+		outcome: { result: "hit" }
+	};
+	if (await sharedCache?.get(cacheKey) === null) {
+		logger.debug("Entry {keyId} found in cache, but it could not be fetched.", { keyId });
+		return {
+			result: await onCachedUnavailable(cacheKey, keyId, sharedCache, logger),
+			outcome: { result: "hit" }
+		};
+	}
+	logger.debug("Fetching key {keyId} to verify signature...", { keyId });
+	let document;
+	let documentUrl;
+	try {
+		const remoteDocument = await (options.documentLoader ?? getDocumentLoader())(keyId);
+		document = remoteDocument.document;
+		documentUrl = new URL(remoteDocument.documentUrl ?? "", cacheKey);
+	} catch (error) {
+		const outcome = classifyFetchError(error);
+		const result = await onFetchError(error, cacheKey, keyId, sharedCache, logger);
+		await scopedCache?.delete(cacheKey);
+		return {
+			result,
+			outcome
+		};
+	}
+	const resolved = await resolveFetchedKey(document, cacheKey, documentUrl, keyId, cls, {
+		...options,
+		keyCache: scopedCache
+	}, logger);
+	return {
+		result: resolved,
+		outcome: { result: resolved.key != null ? "fetched" : "invalid" }
+	};
+}
 async function fetchKeyInternal(keyId, cls, options = {}) {
 	return await fetchKeyWithResult(typeof keyId === "string" ? new URL(keyId) : keyId, cls, options, (_cacheKey, _keyId, _keyCache, _logger) => {
 		return {
@@ -2289,10 +2381,7 @@ async function verifySignature(jsonLd, options = {}) {
 		});
 		const { key } = await measureSignatureKeyFetch(options.meterProvider, "linked_data", () => fetchKey(new URL(sig.creator), CryptographicKey, {
 			...options,
-			keyCache: {
-				get: () => Promise.resolve(void 0),
-				set: async (keyId, key) => await options.keyCache?.set(keyId, key)
-			}
+			keyCache: bypassKeyCacheReads(options.keyCache)
 		}));
 		if (key == null) return null;
 		return await crypto.subtle.verify("RSASSA-PKCS1-v1_5", key.publicKey, signature.slice(), messageBytes) ? key : null;
@@ -3338,38 +3427,42 @@ function equalStringSets(left, right) {
 }
 async function hasValidProofOptions(proofConfig, options, documentLoader) {
 	const expires = await getProofOption(proofConfig, SECURITY_EXPIRATION, ["expires", SECURITY_EXPIRATION], documentLoader);
-	if (expires == null) return false;
+	if (expires == null) return null;
+	let expiration;
 	if (expires.present) {
-		if (typeof expires.value !== "string") return false;
-		let expiration;
+		if (typeof expires.value !== "string") return null;
 		try {
 			expiration = Temporal.Instant.from(expires.value);
 		} catch {
-			return false;
+			return null;
 		}
-		if (Temporal.Instant.compare(Temporal.Now.instant(), expiration) >= 0) return false;
+		if (Temporal.Instant.compare(Temporal.Now.instant(), expiration) >= 0) return null;
 	}
 	const domain = await getProofOption(proofConfig, SECURITY_DOMAIN, ["domain", SECURITY_DOMAIN], documentLoader);
-	if (domain == null) return false;
+	if (domain == null) return null;
 	const proofDomains = domain.present ? parseStringSet(domain.value) : null;
-	if (domain.present && proofDomains == null) return false;
+	if (domain.present && proofDomains == null) return null;
 	if (options.domain != null) {
 		const expectedDomains = parseStringSet(options.domain);
-		if (expectedDomains == null || proofDomains == null || !equalStringSets(proofDomains, expectedDomains)) return false;
+		if (expectedDomains == null || proofDomains == null || !equalStringSets(proofDomains, expectedDomains)) return null;
 	}
 	const challenge = await getProofOption(proofConfig, SECURITY_CHALLENGE, ["challenge", SECURITY_CHALLENGE], documentLoader);
-	if (challenge == null || challenge.present && typeof challenge.value !== "string" || options.challenge != null && (!challenge.present || challenge.value !== options.challenge)) return false;
+	if (challenge == null || challenge.present && typeof challenge.value !== "string" || options.challenge != null && (!challenge.present || challenge.value !== options.challenge)) return null;
 	const nonce = await getProofOption(proofConfig, SECURITY_NONCE, ["nonce", SECURITY_NONCE], documentLoader);
-	if (nonce == null || nonce.present && typeof nonce.value !== "string") return false;
+	if (nonce == null || nonce.present && typeof nonce.value !== "string") return null;
 	const previousProof = await getProofOption(proofConfig, SECURITY_PREVIOUS_PROOF, ["previousProof", SECURITY_PREVIOUS_PROOF], documentLoader);
-	if (previousProof == null || previousProof.present && typeof previousProof.value !== "string" && (!Array.isArray(previousProof.value) || previousProof.value.some((item) => typeof item !== "string"))) return false;
-	return true;
+	if (previousProof == null || previousProof.present && typeof previousProof.value !== "string" && (!Array.isArray(previousProof.value) || previousProof.value.some((item) => typeof item !== "string"))) return null;
+	return { expires: expiration };
 }
 async function verifyProofInternal(jsonLd, proof, options, messageDigestCache, rawProofCandidate, keyIdBoundByCaller = false) {
 	if (!isJsonLdNode(jsonLd) || proof.cryptosuite !== "eddsa-jcs-2022" || proof.verificationMethodId == null || proof.proofPurpose !== "assertionMethod" || proof.proofValue == null || proof.created == null) return null;
 	const proofContextLoader = messageDigestCache.proofContextLoader ?? preloadedOnlyDocumentLoader;
 	const proofConfiguration = await createProofConfiguration(jsonLd, proof, options, proofContextLoader, rawProofCandidate);
-	if (proofConfiguration == null || !await hasValidProofOptions(proofConfiguration.value, options, proofContextLoader)) return null;
+	if (proofConfiguration == null) return null;
+	const validProofOptions = await hasValidProofOptions(proofConfiguration.value, options, proofContextLoader);
+	if (validProofOptions == null) return null;
+	const { expires } = validProofOptions;
+	if (expires != null && (messageDigestCache.expires == null || Temporal.Instant.compare(expires, messageDigestCache.expires) < 0)) messageDigestCache.expires = expires;
 	const publicKeyPromise = measureSignatureKeyFetch(options.meterProvider, "object_integrity", () => fetchKey(proof.verificationMethodId, Multikey, {
 		...options,
 		keyIdBoundByCaller
@@ -3403,10 +3496,7 @@ async function verifyProofInternal(jsonLd, proof, options, messageDigestCache, r
 			});
 			return await verifyProofInternal(jsonLd, proof, {
 				...options,
-				keyCache: {
-					get: () => Promise.resolve(void 0),
-					set: async (keyId, key) => await options.keyCache?.set(keyId, key)
-				}
+				keyCache: bypassKeyCacheReads(options.keyCache)
 			}, messageDigestCache, rawProofCandidate, keyIdBoundByCaller);
 		}
 		logger$1.debug("The fetched key (verificationMethod) for the proof is not a valid Ed25519 key:\n{keyId}", {
@@ -3442,10 +3532,7 @@ async function verifyProofInternal(jsonLd, proof, options, messageDigestCache, r
 		});
 		return await verifyProofInternal(jsonLd, proof, {
 			...options,
-			keyCache: {
-				get: () => Promise.resolve(void 0),
-				set: async (keyId, key) => await options.keyCache?.set(keyId, key)
-			}
+			keyCache: bypassKeyCacheReads(options.keyCache)
 		}, messageDigestCache, rawProofCandidate, keyIdBoundByCaller);
 	}
 	logger$1.debug("Failed to verify the proof with the fetched key {keyId}:\n{proof}", {
@@ -3774,21 +3861,24 @@ async function verifyPortableObjectProofWithRoot(jsonLd, options = {}) {
 		...prepared.root == null ? {} : { root: prepared.root },
 		...prepared.objectType == null ? {} : { objectType: prepared.objectType }
 	};
-	const { root, objectType } = prepared;
+	const { root, objectType, proofContextLoader } = prepared;
+	const messageDigestCache = { proofContextLoader };
+	const result = await verifyPreparedPortableObjectProof(jsonLd, prepared, options, messageDigestCache);
+	const { expires } = messageDigestCache;
 	return {
-		result: await verifyPreparedPortableObjectProof(jsonLd, prepared, options),
+		result,
 		root,
-		objectType
+		objectType,
+		...result.verified && expires != null ? { expires } : {}
 	};
 }
-async function verifyPreparedPortableObjectProof(jsonLd, prepared, options) {
+async function verifyPreparedPortableObjectProof(jsonLd, prepared, options, messageDigestCache) {
 	const { proofs, rawProofValues, proofContextLoader } = prepared;
 	const keys = [];
 	const rawProofCandidatePool = {
 		candidates: await parseRawProofCandidates(jsonLd, rawProofValues, options, proofContextLoader),
 		used: /* @__PURE__ */ new Set()
 	};
-	const messageDigestCache = { proofContextLoader };
 	for (let proofIndex = 0; proofIndex < proofs.length; proofIndex++) {
 		const rawProofCandidate = takeRawProofCandidate(rawProofCandidatePool, proofs[proofIndex]);
 		if (rawProofCandidate == null) return {
@@ -3986,7 +4076,7 @@ async function verifyPortableGatewayKeyDocument(document, actor, keyId, options
 		if (!(error instanceof TypeError)) throw error;
 		return reject(`The actor document is malformed: ${error.message}`);
 	}
-	const { result, root } = verification;
+	const { result, root, expires } = verification;
 	if (!result.verified) return reject("The actor document does not satisfy the FEP-ef61 proof policy: " + result.reason.type);
 	if (root == null) return reject("The actor document could not be expanded.");
 	const refuse = (url) => Promise.reject(/* @__PURE__ */ new Error(`Refusing to fetch ${url}.`));
@@ -4058,7 +4148,8 @@ async function verifyPortableGatewayKeyDocument(document, actor, keyId, options
 	return {
 		type: "verified",
 		actor,
-		key
+		key,
+		...expires == null ? {} : { expires }
 	};
 }
 /**
@@ -4787,10 +4878,7 @@ async function verifyRequestDraft(request, span, metricsContext, { documentLoade
 				contextLoader,
 				timeWindow,
 				currentTime,
-				keyCache: {
-					get: () => Promise.resolve(void 0),
-					set: async (keyId, key) => await keyCache?.set(keyId, key)
-				},
+				keyCache: bypassKeyCacheReads(keyCache),
 				meterProvider,
 				tracerProvider
 			});
@@ -5039,10 +5127,7 @@ async function verifyRequestRfc9421(request, span, metricsContext, { documentLoa
 					contextLoader,
 					timeWindow,
 					currentTime,
-					keyCache: {
-						get: () => Promise.resolve(void 0),
-						set: async (keyId, key) => await keyCache?.set(keyId, key)
-					},
+					keyCache: bypassKeyCacheReads(keyCache),
 					spec: "rfc9421",
 					meterProvider,
 					tracerProvider

package/dist/{http-n2v6DPxu.d.ts → http-D76Py0M4.d.cts}

@@ -1,7 +1,7 @@
 /// <reference lib="esnext.temporal" />
 import { Actor, CryptographicKey, Multikey } from "@fedify/vocab";
-import { MeterProvider, TracerProvider } from "@opentelemetry/api";
 import { DocumentLoader } from "@fedify/vocab-runtime";
+import { MeterProvider, TracerProvider } from "@opentelemetry/api";
 
 //#region src/sig/portable-key.d.ts
 /**
@@ -23,6 +23,11 @@ type PortableGatewayKeyResolution = {
   readonly key: CryptographicKey & {
     publicKey: CryptoKey;
   };
+  /**
+  * When the proof of the actor's document expires, if it does.  The
+  * document does not vouch for the key after that.
+  */
+  readonly expires?: Temporal.Instant;
 };
 //#endregion
 //#region src/sig/key.d.ts
@@ -177,9 +182,9 @@ type FetchableKeyClass<T extends CryptographicKey | Multikey> = (new (...args: a
 * Gateway keys of [FEP-ef61] portable actors, i.e., keys whose IDs are
 * compatible identifiers that dereference to portable actor documents, are
 * not resolved by this function, as they only authenticate HTTP requests;
-* use `verifyRequest()` or `getKeyOwner()` for them instead.  Keys
-* whose IDs are compatible identifiers are never read from or written to
-* the key cache.
+* use `verifyRequest()` or `getKeyOwner()` for them instead.  Keys whose IDs
+* are compatible identifiers are never read from or written to the key
+* cache under their IDs, except for failures to fetch them.
 *
 * [FEP-ef61]: https://w3id.org/fep/ef61
 * @template T The type of the key to fetch.  Either {@link CryptographicKey}
@@ -199,9 +204,9 @@ declare function fetchKey<T extends CryptographicKey | Multikey>(keyId: URL | st
 * Gateway keys of [FEP-ef61] portable actors, i.e., keys whose IDs are
 * compatible identifiers that dereference to portable actor documents, are
 * not resolved by this function, as they only authenticate HTTP requests;
-* use `verifyRequest()` or `getKeyOwner()` for them instead.  Keys
-* whose IDs are compatible identifiers are never read from or written to
-* the key cache.
+* use `verifyRequest()` or `getKeyOwner()` for them instead.  Keys whose IDs
+* are compatible identifiers are never read from or written to the key
+* cache under their IDs, except for failures to fetch them.
 *
 * [FEP-ef61]: https://w3id.org/fep/ef61
 *

package/dist/{key-I8gLBkcf.mjs → key-CkNxztNV.mjs}

@@ -1,9 +1,9 @@
 import "temporal-polyfill";
 import "urlpattern-polyfill";
 globalThis.addEventListener = () => {};
-import { n as version, t as name } from "./deno-CkjiYK_Z.mjs";
-import { _ as recordKeyLookup, n as getDurationMs, t as classifyFetchError } from "./metrics-BCAa5-kE.mjs";
-import { a as isCompatibleKeyId, o as isPortableActorDocument, s as isPortableId } from "./portable-key-id-Bva5iT3W.mjs";
+import { n as version, t as name } from "./deno-CCABdw7r.mjs";
+import { _ as recordKeyLookup, n as getDurationMs, t as classifyFetchError } from "./metrics-em_7lwhG.mjs";
+import { a as isCompatibleKeyId, o as isPortableActorDocument, s as isPortableId } from "./portable-key-id-T7lecIbt.mjs";
 import { getLogger } from "@logtape/logtape";
 import { CryptographicKey, Multikey, Object as Object$1, isActor } from "@fedify/vocab";
 import { SpanKind, SpanStatusCode, trace } from "@opentelemetry/api";
@@ -210,6 +210,32 @@ async function verifyKeyOwnership(key, options = {}) {
 	});
 	return null;
 }
+/**
+* Wraps a key cache so that lookups through the wrapper miss, while
+* whatever they resolve is still written to the cache.  It is used to retry
+* a verification that failed with a cached key with a freshly fetched one.
+* @param keyCache The key cache to wrap.
+* @returns The wrapped key cache.
+* @internal
+*/
+function bypassKeyCacheReads(keyCache) {
+	const cache = keyCache;
+	const bypassed = {
+		get: () => Promise.resolve(void 0),
+		set: async (keyId, key) => await cache?.set(keyId, key),
+		getFetchError: () => Promise.resolve(void 0),
+		setFetchError: async (keyId, error) => await cache?.setFetchError?.(keyId, error)
+	};
+	if (cache?.compatibleKeyScope != null) bypassed.compatibleKeyScope = (scope) => {
+		const scoped = cache.compatibleKeyScope(scope);
+		return {
+			get: () => Promise.resolve(void 0),
+			set: async (keyId, key, options) => await scoped.set(keyId, key, options),
+			delete: async (keyId) => await scoped.delete(keyId)
+		};
+	};
+	return bypassed;
+}
 async function withFetchKeySpan(keyId, tracerProvider, fetcher) {
 	tracerProvider ??= trace.getTracerProvider();
 	return await tracerProvider.getTracer(name, version).startActiveSpan("activitypub.fetch_key", {
@@ -246,9 +272,9 @@ async function withFetchKeySpan(keyId, tracerProvider, fetcher) {
 * Gateway keys of [FEP-ef61] portable actors, i.e., keys whose IDs are
 * compatible identifiers that dereference to portable actor documents, are
 * not resolved by this function, as they only authenticate HTTP requests;
-* use `verifyRequest()` or `getKeyOwner()` for them instead.  Keys
-* whose IDs are compatible identifiers are never read from or written to
-* the key cache.
+* use `verifyRequest()` or `getKeyOwner()` for them instead.  Keys whose IDs
+* are compatible identifiers are never read from or written to the key
+* cache under their IDs, except for failures to fetch them.
 *
 * [FEP-ef61]: https://w3id.org/fep/ef61
 * @template T The type of the key to fetch.  Either {@link CryptographicKey}
@@ -271,9 +297,9 @@ function fetchKey(keyId, cls, options = {}) {
 * Gateway keys of [FEP-ef61] portable actors, i.e., keys whose IDs are
 * compatible identifiers that dereference to portable actor documents, are
 * not resolved by this function, as they only authenticate HTTP requests;
-* use `verifyRequest()` or `getKeyOwner()` for them instead.  Keys
-* whose IDs are compatible identifiers are never read from or written to
-* the key cache.
+* use `verifyRequest()` or `getKeyOwner()` for them instead.  Keys whose IDs
+* are compatible identifiers are never read from or written to the key
+* cache under their IDs, except for failures to fetch them.
 *
 * [FEP-ef61]: https://w3id.org/fep/ef61
 *
@@ -456,11 +482,13 @@ async function resolveFetchedKey(document, cacheKey, documentUrl, keyId, cls, {
 		}
 	}
 	if (isCompatibleKeyId(cacheKey) && isPortableActorDocument(object)) {
+		const scopedCache = keyCache;
 		if (portableGatewayKeyResolver == null || cls !== CryptographicKey) {
 			logger.debug("Failed to verify; key {keyId} is a gateway key of the portable actor {actorId}, which is only accepted for HTTP Signatures.", {
 				keyId,
 				actorId: object.id?.href
 			});
+			await scopedCache?.set(cacheKey, null);
 			return {
 				key: null,
 				cached: false
@@ -472,11 +500,13 @@ async function resolveFetchedKey(document, cacheKey, documentUrl, keyId, cls, {
 				keyId,
 				actorId: object.id?.href
 			});
+			await scopedCache?.set(cacheKey, null);
 			return {
 				key: null,
 				cached: false
 			};
 		}
+		await scopedCache?.set(cacheKey, resolution.key, { expires: resolution.expires });
 		return {
 			key: resolution.key,
 			cached: false
@@ -605,8 +635,9 @@ async function resolveFetchedKey(document, cacheKey, documentUrl, keyId, cls, {
 }
 /**
 * Tells whether a key claims a portable actor as its owner.  Such a key can
-* only be a gateway key, which is never cached, so a cached one was cached
-* by an older version that trusted web origins, and is fetched again.
+* only be a gateway key, which is never cached under its ID, so a cached one
+* was cached by an older version that trusted web origins, and is fetched
+* again.
 */
 function claimsPortableOwner(key) {
 	const ownerId = key instanceof CryptographicKey ? key.ownerId : key?.controllerId;
@@ -622,11 +653,12 @@ async function fetchKeyWithResult(cacheKey, cls, options, onCachedUnavailable, o
 			"key"
 		]);
 		const keyId = cacheKey.href;
-		if (isCompatibleKeyId(cacheKey)) options = {
-			...options,
-			keyCache: void 0
-		};
 		const keyCache = options.keyCache;
+		if (isCompatibleKeyId(cacheKey)) {
+			const result = await fetchCompatibleKey(cacheKey, cls, options, onCachedUnavailable, onFetchError, logger);
+			outcome = result.outcome;
+			return result.result;
+		}
 		const didKey = await resolveDidKey(cacheKey, cls, keyCache, logger);
 		if (didKey != null) {
 			outcome = { result: didKey.key == null ? "invalid" : didKey.cached ? "hit" : "fetched" };
@@ -668,6 +700,65 @@ async function fetchKeyWithResult(cacheKey, cls, options, onCachedUnavailable, o
 		});
 	}
 }
+/**
+* Tells which purpose a lookup of a key at a compatible identifier serves.
+*/
+function getCompatibleKeyScope(cls, options) {
+	if (cls !== CryptographicKey) return "multikey";
+	return options.portableGatewayKeyResolver == null ? "cryptographicKey" : "httpSignature";
+}
+/**
+* Looks up a key at an [FEP-ef61] compatible identifier.  Such a key may be
+* a gateway key of a portable actor, which is accepted for some purposes but
+* not for others, so everything resolved from the document at the key ID is
+* cached in a namespace of the lookup's purpose, and one purpose never reuses
+* what another resolved, nor what another rejected.  A failure to fetch
+* the document fails every purpose alike, so it is cached in the shared
+* namespace, as for any other key.
+*
+* [FEP-ef61]: https://w3id.org/fep/ef61
+*/
+async function fetchCompatibleKey(cacheKey, cls, options, onCachedUnavailable, onFetchError, logger) {
+	const keyId = cacheKey.href;
+	const sharedCache = options.keyCache;
+	const scopedCache = sharedCache?.compatibleKeyScope?.(getCompatibleKeyScope(cls, options));
+	const cached = await getCachedFetchKey(cacheKey, keyId, cls, scopedCache, logger);
+	if (cached != null) return {
+		result: cached,
+		outcome: { result: "hit" }
+	};
+	if (await sharedCache?.get(cacheKey) === null) {
+		logger.debug("Entry {keyId} found in cache, but it could not be fetched.", { keyId });
+		return {
+			result: await onCachedUnavailable(cacheKey, keyId, sharedCache, logger),
+			outcome: { result: "hit" }
+		};
+	}
+	logger.debug("Fetching key {keyId} to verify signature...", { keyId });
+	let document;
+	let documentUrl;
+	try {
+		const remoteDocument = await (options.documentLoader ?? getDocumentLoader())(keyId);
+		document = remoteDocument.document;
+		documentUrl = new URL(remoteDocument.documentUrl ?? "", cacheKey);
+	} catch (error) {
+		const outcome = classifyFetchError(error);
+		const result = await onFetchError(error, cacheKey, keyId, sharedCache, logger);
+		await scopedCache?.delete(cacheKey);
+		return {
+			result,
+			outcome
+		};
+	}
+	const resolved = await resolveFetchedKey(document, cacheKey, documentUrl, keyId, cls, {
+		...options,
+		keyCache: scopedCache
+	}, logger);
+	return {
+		result: resolved,
+		outcome: { result: resolved.key != null ? "fetched" : "invalid" }
+	};
+}
 async function fetchKeyInternal(keyId, cls, options = {}) {
 	return await fetchKeyWithResult(typeof keyId === "string" ? new URL(keyId) : keyId, cls, options, (_cacheKey, _keyId, _keyCache, _logger) => {
 		return {
@@ -692,4 +783,4 @@ async function fetchKeyInternal(keyId, cls, options = {}) {
 	});
 }
 //#endregion
-export { generateCryptoKeyPair as a, verifyKeyOwnership as c, fetchKeyDetailed as i, fetchActorDocument as n, importJwk as o, fetchKey as r, validateCryptoKey as s, exportJwk as t };
+export { fetchKeyDetailed as a, validateCryptoKey as c, fetchKey as i, verifyKeyOwnership as l, exportJwk as n, generateCryptoKeyPair as o, fetchActorDocument as r, importJwk as s, bypassKeyCacheReads as t };