@fedify/fedify 2.4.0-pr.936.41 → 2.5.0-dev.2271

package/dist/key-BspPiXqn.mjs

@@ -0,0 +1,951 @@
+import { Temporal } from "temporal-polyfill";
+import "urlpattern-polyfill";
+globalThis.addEventListener = () => {};
+import { c as isPortableActorDocument, d as isPortableUri, l as isPortableId, m as parseKeyIdString, s as isCompatibleKeyId } from "./portable-key-id-Ca30-hOa.mjs";
+import { a as verificationObservation } from "./verification-Dpfcw8ml.mjs";
+import { n as version, t as name } from "./deno-oR5aJKpU.mjs";
+import { _ as recordKeyLookup, n as getDurationMs, t as classifyFetchError } from "./metrics-CYg9yxBL.mjs";
+import { n as attachKeyOwnerEvidence, t as MAX_PORTABLE_KEY_TTL } from "./key-owner-evidence-APB6NpSk.mjs";
+import { getLogger } from "@logtape/logtape";
+import { CryptographicKey, Multikey, Object as Object$1, isActor } from "@fedify/vocab";
+import { SpanKind, SpanStatusCode, trace } from "@opentelemetry/api";
+import { FetchError, getDocumentLoader, parseDidKeyVerificationMethod } from "@fedify/vocab-runtime";
+//#region src/sig/key.ts
+/**
+* Checks if the given key is valid and supported.  No-op if the key is valid,
+* otherwise throws an error.
+* @param key The key to check.
+* @param type Which type of key to check.  If not specified, the key can be
+*             either public or private.
+* @throws {TypeError} If the key is invalid or unsupported.
+*/
+function validateCryptoKey(key, type) {
+	if (type != null && key.type !== type) throw new TypeError(`The key is not a ${type} key.`);
+	if (!key.extractable) throw new TypeError("The key is not extractable.");
+	if (key.algorithm.name !== "RSASSA-PKCS1-v1_5" && key.algorithm.name !== "Ed25519") throw new TypeError("Currently only RSASSA-PKCS1-v1_5 and Ed25519 keys are supported.  More algorithms will be added in the future!");
+	if (key.algorithm.name === "RSASSA-PKCS1-v1_5") {
+		if (key.algorithm.hash.name !== "SHA-256") throw new TypeError("For compatibility with the existing Fediverse software (e.g., Mastodon), hash algorithm for RSASSA-PKCS1-v1_5 keys must be SHA-256.");
+	}
+}
+/**
+* Generates a key pair which is appropriate for Fedify.
+* @param algorithm The algorithm to use.  Currently only RSASSA-PKCS1-v1_5 and
+*                  Ed25519 are supported.
+* @returns The generated key pair.
+* @throws {TypeError} If the algorithm is unsupported.
+*/
+function generateCryptoKeyPair(algorithm) {
+	if (algorithm == null) getLogger([
+		"fedify",
+		"sig",
+		"key"
+	]).warn("No algorithm specified.  Using RSASSA-PKCS1-v1_5 by default, but it is recommended to specify the algorithm explicitly as the parameter will be required in the future.");
+	if (algorithm == null || algorithm === "RSASSA-PKCS1-v1_5") return crypto.subtle.generateKey({
+		name: "RSASSA-PKCS1-v1_5",
+		modulusLength: 4096,
+		publicExponent: new Uint8Array([
+			1,
+			0,
+			1
+		]),
+		hash: "SHA-256"
+	}, true, ["sign", "verify"]);
+	else if (algorithm === "Ed25519") return crypto.subtle.generateKey("Ed25519", true, ["sign", "verify"]);
+	throw new TypeError("Unsupported algorithm: " + algorithm);
+}
+/**
+* Exports a key in JWK format.
+* @param key The key to export.  Either public or private key.
+* @returns The exported key in JWK format.  The key is suitable for
+*          serialization and storage.
+* @throws {TypeError} If the key is invalid or unsupported.
+*/
+async function exportJwk(key) {
+	validateCryptoKey(key);
+	const jwk = await crypto.subtle.exportKey("jwk", key);
+	if (jwk.crv === "Ed25519") jwk.alg = "Ed25519";
+	return jwk;
+}
+/**
+* Imports a key from JWK format.
+* @param jwk The key in JWK format.
+* @param type Which type of key to import, either `"public"` or `"private"`.
+* @returns The imported key.
+* @throws {TypeError} If the key is invalid or unsupported.
+*/
+async function importJwk(jwk, type) {
+	let key;
+	if (jwk.kty === "RSA" && jwk.alg === "RS256") key = await crypto.subtle.importKey("jwk", jwk, {
+		name: "RSASSA-PKCS1-v1_5",
+		hash: "SHA-256"
+	}, true, type === "public" ? ["verify"] : ["sign"]);
+	else if (jwk.kty === "OKP" && jwk.crv === "Ed25519") {
+		if (navigator?.userAgent === "Cloudflare-Workers") {
+			jwk = { ...jwk };
+			delete jwk.alg;
+		}
+		key = await crypto.subtle.importKey("jwk", jwk, "Ed25519", true, type === "public" ? ["verify"] : ["sign"]);
+	} else throw new TypeError("Unsupported JWK format.");
+	validateCryptoKey(key, type);
+	return key;
+}
+/**
+* Fetches the document that the given actor URI dereferences to, and returns
+* the actor only if the host that served the document is authoritative for
+* the id the document claims.
+*
+* Only the origin that serves an actor id can speak for it.  Without that
+* rule any host could serve a document describing somebody else's actor—and
+* listing its own keys as that actor's.
+*
+* @param actorId The URI of the actor to fetch.
+* @param options Options for fetching the document.
+* @returns The actor, or `null` if the document cannot be fetched, is not an
+*          actor, or belongs to another origin.
+* @internal
+*/
+async function fetchActorDocument(actorId, options = {}) {
+	const logger = getLogger([
+		"fedify",
+		"sig",
+		"key"
+	]);
+	if (isPortableId(actorId)) {
+		logger.debug("The actor {actorId} is a portable actor, which is not authenticated by the web origin that serves it.", { actorId: actorId.href });
+		return null;
+	}
+	const documentLoader = options.documentLoader ?? getDocumentLoader();
+	const contextLoader = options.contextLoader ?? getDocumentLoader();
+	const { tracerProvider } = options;
+	let document;
+	let documentUrl = actorId;
+	try {
+		const remoteDocument = await documentLoader(actorId.href);
+		document = remoteDocument.document;
+		documentUrl = new URL(remoteDocument.documentUrl ?? "", actorId);
+	} catch (error) {
+		logger.debug("Failed to fetch the actor {actorId}: {error}", {
+			actorId: actorId.href,
+			error
+		});
+		return null;
+	}
+	let object;
+	try {
+		object = await Object$1.fromJsonLd(document, {
+			documentLoader,
+			contextLoader,
+			tracerProvider,
+			baseUrl: documentUrl
+		});
+	} catch (error) {
+		if (!(error instanceof TypeError)) throw error;
+		logger.debug("The document served at {documentUrl} is not a valid object: {error}", {
+			documentUrl: documentUrl.href,
+			error
+		});
+		return null;
+	}
+	if (!isActor(object)) return null;
+	if (object.id != null && isPortableId(object.id)) {
+		logger.debug("The document served at {documentUrl} claims to be the portable actor {actorId}, which is not authenticated by the web origin that serves it.", {
+			documentUrl: documentUrl.href,
+			actorId: object.id?.href
+		});
+		return null;
+	}
+	if (object.id == null || object.id.origin !== documentUrl.origin) {
+		logger.debug("The document served at {documentUrl} claims to be the actor {actorId}, which belongs to another origin; refusing to treat it as that actor's document.", {
+			documentUrl: documentUrl.href,
+			actorId: object.id?.href
+		});
+		return null;
+	}
+	return object;
+}
+/**
+* Resolves the owner that the given key claims, and returns it only if the
+* claim holds.
+*
+* The `owner` of a {@link CryptographicKey}, like the `controller` of
+* a {@link Multikey}, proves nothing on its own: the key document and the
+* claim inside it are served by the same host, so anyone able to serve a key
+* document can name any actor in the world as its owner.  The claim becomes
+* meaningful only once the named actor's own document is fetched and turns
+* out to link back to the key.  This function performs that mutual-link
+* check, which is the only sound way to learn a fetched key's owner.
+*
+* The claimed owner is always dereferenced, never read out of the key
+* document: an owner embedded there is written by whoever wrote the key.
+*
+* @param key The key whose ownership claim is to be verified.  It must carry
+*            an `id`, as that is what the owner has to link back to.
+* @param options Options for fetching the claimed owner.
+* @returns The verified owner, or `null` if the key claims no owner, the
+*          owner cannot be fetched, or the owner does not link back to
+*          the key.
+* @internal
+*/
+async function verifyKeyOwnership(key, options = {}) {
+	const logger = getLogger([
+		"fedify",
+		"sig",
+		"key"
+	]);
+	const keyId = key.id;
+	if (keyId == null) return null;
+	const claimedOwnerId = key instanceof CryptographicKey ? key.ownerId : key.controllerId;
+	if (claimedOwnerId == null) return null;
+	const owner = await fetchActorDocument(claimedOwnerId, options);
+	if (owner == null) {
+		logger.debug("The owner ({claimedOwnerId}) that key {keyId} claims could not be resolved.", {
+			keyId: keyId.href,
+			claimedOwnerId: claimedOwnerId.href
+		});
+		return null;
+	}
+	const linkedKeyIds = key instanceof CryptographicKey ? owner.publicKeyIds : owner.assertionMethodIds;
+	for (const linkedKeyId of linkedKeyIds) if (linkedKeyId.href === keyId.href) return owner;
+	logger.debug("The owner ({claimedOwnerId}) that key {keyId} claims does not list the key as its own.", {
+		keyId: keyId.href,
+		claimedOwnerId: claimedOwnerId.href
+	});
+	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),
+			getEntry: () => Promise.resolve(void 0),
+			set: async (keyId, key, options) => await scoped.set(keyId, key, options),
+			delete: async (keyId) => await scoped.delete(keyId)
+		};
+	};
+	return bypassed;
+}
+/**
+* Parses a key ID given as a string.  Unlike `new URL()`, it accepts `ap:`
+* and `ap+ef61:` URIs, and refuses a portable or compatible key ID whose
+* identity URL parsing would change, e.g., by resolving dot segments.
+* @throws {TypeError} If the key ID is invalid.
+*/
+function parseKeyIdOrThrow(keyId) {
+	const parsed = parseKeyIdString(keyId);
+	if (parsed == null) throw new TypeError(`Invalid key ID: ${keyId}`);
+	return parsed;
+}
+async function withFetchKeySpan(keyId, tracerProvider, fetcher) {
+	tracerProvider ??= trace.getTracerProvider();
+	return await tracerProvider.getTracer(name, version).startActiveSpan("activitypub.fetch_key", {
+		kind: SpanKind.CLIENT,
+		attributes: {
+			"http.method": "GET",
+			"url.full": keyId.href,
+			"url.scheme": keyId.protocol.replace(/:$/, ""),
+			"url.domain": keyId.hostname,
+			"url.path": keyId.pathname,
+			"url.query": keyId.search.replace(/^\?/, ""),
+			"url.fragment": keyId.hash.replace(/^#/, "")
+		}
+	}, async (span) => {
+		try {
+			const result = await fetcher();
+			span.setAttribute("activitypub.actor.key.cached", result.cached);
+			return result;
+		} catch (e) {
+			span.setStatus({
+				code: SpanStatusCode.ERROR,
+				message: String(e)
+			});
+			throw e;
+		} finally {
+			span.end();
+		}
+	});
+}
+/**
+* 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. *
+* 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.  Nor are keys
+* of portable actors whose IDs are `ap:` or `ap+ef61:` URIs, for the same
+* reason.  Keys whose IDs are compatible identifiers or `ap:` or `ap+ef61:`
+* URIs 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}
+*              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" ? parseKeyIdOrThrow(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. *
+* 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.  Nor are keys
+* of portable actors whose IDs are `ap:` or `ap+ef61:` URIs, for the same
+* reason.  Keys whose IDs are compatible identifiers or `ap:` or `ap+ef61:`
+* URIs 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}
+*              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" ? parseKeyIdOrThrow(keyId) : keyId;
+	return await withFetchKeySpan(cacheKey, options.tracerProvider, async () => {
+		return await fetchKeyWithResult(cacheKey, cls, options, async (cacheKey, keyId, keyCache, logger) => {
+			const fetchError = await keyCache?.getFetchError?.(cacheKey);
+			if (fetchError != null) {
+				logger.debug("Entry {keyId} found in cache with preserved fetch failure details.", { keyId });
+				return {
+					key: null,
+					cached: true,
+					fetchError
+				};
+			}
+			logger.debug("Entry {keyId} found in cache, but no fetch failure details are available.", { keyId });
+			return {
+				key: null,
+				cached: true
+			};
+		}, async (error, cacheKey, keyId, keyCache, logger) => {
+			logger.debug("Failed to fetch key {keyId}.", {
+				keyId,
+				error
+			});
+			await keyCache?.set(cacheKey, null);
+			if (error instanceof FetchError && error.response != null) {
+				const fetchError = {
+					status: error.response.status,
+					response: error.response.clone()
+				};
+				await keyCache?.setFetchError?.(cacheKey, fetchError);
+				return {
+					key: null,
+					cached: false,
+					fetchError
+				};
+			}
+			const fetchError = { error: error instanceof Error ? error : new Error(String(error)) };
+			await keyCache?.setFetchError?.(cacheKey, fetchError);
+			return {
+				key: null,
+				cached: false,
+				fetchError
+			};
+		});
+	});
+}
+async function getCachedFetchKey(cacheKey, keyId, cls, keyCache, logger) {
+	if (keyCache == null) return null;
+	const cachedKey = await keyCache.get(cacheKey);
+	const hit = checkCachedKeyHit(cachedKey, keyId, cls, logger);
+	if (hit != null) return hit;
+	if (cachedKey === null) {
+		logger.debug("Entry {keyId} found in cache, but it is unavailable.", { keyId });
+		return {
+			key: null,
+			cached: true
+		};
+	}
+	return null;
+}
+function checkCachedKeyHit(cachedKey, keyId, cls, logger) {
+	if (cachedKey instanceof cls && cachedKey.publicKey != null) {
+		logger.debug("Key {keyId} found in cache.", { keyId });
+		return {
+			key: cachedKey,
+			cached: true
+		};
+	}
+	return null;
+}
+/**
+* Looks up a key at a compatible identifier, or at an `ap:` or `ap+ef61:`
+* URI, in the cache namespace of a purpose, like {@link getCachedFetchKey}.
+* A key that the verified document of its portable actor was cached with
+* gets the actor's evidence attached from the same entry; see
+* {@link attachKeyOwnerEvidence}.
+*/
+async function getCachedCompatibleKey(cacheKey, keyId, cls, scopedCache, logger) {
+	if (scopedCache?.getEntry == null) return await getCachedFetchKey(cacheKey, keyId, cls, scopedCache, logger);
+	const entry = await scopedCache.getEntry(cacheKey);
+	if (entry === void 0) return null;
+	if (entry === null) {
+		logger.debug("Entry {keyId} found in cache, but it is unavailable.", { keyId });
+		return {
+			key: null,
+			cached: true
+		};
+	}
+	const hit = checkCachedKeyHit(entry.key, keyId, cls, logger);
+	if (hit?.key instanceof CryptographicKey && entry.owner != null) attachKeyOwnerEvidence(hit.key, entry.owner, entry.expires);
+	return hit;
+}
+/**
+* Attaches the evidence of the portable actor whose document has just
+* vouched for a key to the key.  The evidence expires with the cache entry
+* of the key, so that it is never trusted longer than the key is cached.
+* Without a cache, it expires with the proof of the document, but no later
+* than {@link MAX_PORTABLE_KEY_TTL}, as a cache entry would.
+* @param resolution The resolution of the key.
+* @param scopedCache The cache namespace the key was stored in, if any.
+* @param cached When the cache entry expires, if the cache stored one.
+*/
+function attachResolvedKeyOwnerEvidence(resolution, scopedCache, cached) {
+	let expires;
+	if (scopedCache != null) {
+		if (cached == null) return;
+		expires = cached;
+	} else {
+		expires = Temporal.Now.instant().add(MAX_PORTABLE_KEY_TTL);
+		if (resolution.expires != null && Temporal.Instant.compare(resolution.expires, expires) < 0) expires = resolution.expires;
+	}
+	attachKeyOwnerEvidence(resolution.key, resolution.document, expires);
+}
+async function clearFetchErrorMetadata(keyId, keyCache) {
+	await keyCache?.setFetchError?.(keyId, null);
+}
+/**
+* Returns the identifier a fragment-bearing DID URL is a fragment of, or
+* `null` if the URL is not a DID URL.  `did:web:example.com#key` is thereby
+* traced back to `did:web:example.com`, the DID that resolving the key went
+* through in the first place.
+*/
+function stripFragment(keyId) {
+	if (keyId.protocol !== "did:") return null;
+	const did = new URL(keyId.href);
+	did.hash = "";
+	return did;
+}
+function isDidKeyUrl(keyId) {
+	return keyId.protocol === "did:" && keyId.pathname.startsWith("key:");
+}
+async function doRawKeysMatch(left, right) {
+	const [leftRaw, rightRaw] = await Promise.all([crypto.subtle.exportKey("raw", left), crypto.subtle.exportKey("raw", right)]);
+	if (leftRaw.byteLength !== rightRaw.byteLength) return false;
+	const leftBytes = new Uint8Array(leftRaw);
+	const rightBytes = new Uint8Array(rightRaw);
+	return leftBytes.every((byte, index) => byte === rightBytes[index]);
+}
+async function isCachedDidKeyValid(key, verificationMethod) {
+	try {
+		return key.id?.href === verificationMethod.id.href && key.controllerId?.href === verificationMethod.controller.href && await doRawKeysMatch(key.publicKey, verificationMethod.publicKey);
+	} catch {
+		return false;
+	}
+}
+async function resolveDidKey(cacheKey, cls, keyCache, logger) {
+	if (!isDidKeyUrl(cacheKey)) return null;
+	const keyId = cacheKey.href;
+	if (!(cls === Multikey)) {
+		logger.debug("Failed to resolve did:key {keyId}; did:key verification methods are only supported as Multikey values.", { keyId });
+		return {
+			key: null,
+			cached: false
+		};
+	}
+	let verificationMethod;
+	try {
+		verificationMethod = await parseDidKeyVerificationMethod(cacheKey);
+	} catch (error) {
+		logger.debug("Failed to resolve did:key verification method {keyId}: {error}", {
+			keyId,
+			error
+		});
+		return {
+			key: null,
+			cached: false
+		};
+	}
+	const hit = checkCachedKeyHit(await keyCache?.get(cacheKey), keyId, cls, logger);
+	if (hit?.key instanceof Multikey && await isCachedDidKeyValid(hit.key, verificationMethod)) return hit;
+	const key = new Multikey({
+		id: verificationMethod.id,
+		controller: verificationMethod.controller,
+		publicKey: verificationMethod.publicKey
+	});
+	await keyCache?.set(cacheKey, key);
+	await clearFetchErrorMetadata(cacheKey, keyCache);
+	logger.debug("Resolved did:key verification method {keyId}.", { keyId });
+	return {
+		key,
+		cached: false
+	};
+}
+async function resolveFetchedKey(document, cacheKey, documentUrl, keyId, cls, { documentLoader, contextLoader, keyCache, tracerProvider, keyIdBoundByCaller, portableKeyResolvers }, logger) {
+	let object;
+	try {
+		object = await Object$1.fromJsonLd(document, {
+			documentLoader,
+			contextLoader,
+			tracerProvider
+		});
+	} catch (e) {
+		if (!(e instanceof TypeError)) throw e;
+		try {
+			object = await cls.fromJsonLd(document, {
+				documentLoader,
+				contextLoader,
+				tracerProvider
+			});
+		} catch (e) {
+			if (e 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
+				};
+			}
+			throw e;
+		}
+	}
+	if (isCompatibleKeyId(cacheKey) && isPortableActorDocument(object)) {
+		const scopedCache = keyCache;
+		if (portableKeyResolvers == 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
+			};
+		}
+		const resolution = await portableKeyResolvers.gatewayKey(document, object, cacheKey);
+		if (resolution.type !== "verified") {
+			logger.debug("Failed to verify; the portable actor {actorId} does not vouch for its gateway key {keyId}.", {
+				keyId,
+				actorId: object.id?.href
+			});
+			await scopedCache?.set(cacheKey, null);
+			return {
+				key: null,
+				cached: false
+			};
+		}
+		attachResolvedKeyOwnerEvidence(resolution, scopedCache, await scopedCache?.set(cacheKey, resolution.key, {
+			expires: resolution.expires,
+			owner: resolution.document
+		}));
+		return {
+			key: resolution.key,
+			cached: false
+		};
+	}
+	let key = null;
+	let ownerDocument = null;
+	if (object instanceof cls && (object.id == null || object.id.href === keyId)) key = object.id == null ? object.clone({ id: cacheKey }) : object;
+	else if (isActor(object)) {
+		if (object.id == null || isPortableId(object.id) || object.id.origin !== documentUrl.origin) {
+			logger.debug("Failed to verify; the document served at {documentUrl} claims to be the actor {actorId}, which belongs to another origin.", {
+				keyId,
+				documentUrl: documentUrl.href,
+				actorId: object.id?.href
+			});
+			await keyCache?.set(cacheKey, null);
+			return {
+				key: null,
+				cached: false
+			};
+		}
+		ownerDocument = object;
+		const keys = cls === CryptographicKey ? object.getPublicKeys({
+			documentLoader,
+			contextLoader,
+			suppressError: true,
+			tracerProvider
+		}) : object.getAssertionMethods({
+			documentLoader,
+			contextLoader,
+			suppressError: true,
+			tracerProvider
+		});
+		let length = 0;
+		let lastKey = null;
+		try {
+			for await (const k of keys) {
+				length++;
+				lastKey = k;
+				if (k.id?.href === keyId) {
+					key = k;
+					break;
+				}
+			}
+		} catch (e) {
+			if (!(e instanceof TypeError)) throw e;
+			logger.debug("Failed to verify; a malformed key was encountered while iterating the keys of {keyId}; treating it as a missing key: {error}", {
+				keyId,
+				error: e
+			});
+		}
+		const keyIdUrl = new URL(keyId);
+		if (key == null && keyIdUrl.hash === "" && length === 1) key = lastKey;
+		if (key == null) {
+			logger.debug("Failed to verify; object {keyId} returned an {actorType}, but has no key matching {keyId}.", {
+				keyId,
+				actorType: object.constructor.name
+			});
+			await keyCache?.set(cacheKey, null);
+			await clearFetchErrorMetadata(cacheKey, keyCache);
+			return {
+				key: null,
+				cached: false
+			};
+		}
+	} 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
+		};
+	}
+	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
+		};
+	}
+	const claimedOwnerId = key instanceof CryptographicKey ? key.ownerId : key.controllerId;
+	if (!(keyIdBoundByCaller && claimedOwnerId != null && claimedOwnerId.href === stripFragment(cacheKey)?.href)) {
+		if (claimedOwnerId != null && isPortableId(claimedOwnerId)) {
+			logger.debug("Failed to verify; key {keyId} claims the portable actor {claimedOwnerId} as its owner, but is not its gateway key.", {
+				keyId,
+				claimedOwnerId: claimedOwnerId.href
+			});
+			await keyCache?.set(cacheKey, null);
+			await clearFetchErrorMetadata(cacheKey, keyCache);
+			return {
+				key: null,
+				cached: false
+			};
+		}
+		if (ownerDocument != null && claimedOwnerId == null) key = key instanceof CryptographicKey ? key.clone({ owner: ownerDocument.id }) : key.clone({ controller: ownerDocument.id });
+		else if (claimedOwnerId != null && claimedOwnerId.href !== ownerDocument?.id?.href) {
+			if (await verifyKeyOwnership(key, {
+				documentLoader,
+				contextLoader,
+				tracerProvider
+			}) == null) {
+				logger.debug("Failed to verify; the owner {claimedOwnerId} that key {keyId} claims does not list the key as its own.", {
+					keyId,
+					claimedOwnerId: claimedOwnerId.href
+				});
+				await keyCache?.set(cacheKey, null);
+				return {
+					key: null,
+					cached: false
+				};
+			}
+		}
+	}
+	if (keyCache != null) {
+		await keyCache.set(cacheKey, key);
+		logger.debug("Key {keyId} cached.", { keyId });
+	}
+	await clearFetchErrorMetadata(cacheKey, keyCache);
+	return {
+		key,
+		cached: false
+	};
+}
+/**
+* Tells whether a key claims a portable actor as its owner.  Such a key can
+* 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;
+	return ownerId != null && isPortableId(ownerId);
+}
+async function fetchKeyWithResult(cacheKey, cls, options, onCachedUnavailable, onFetchError) {
+	const start = performance.now();
+	let outcome = { result: "error" };
+	try {
+		const logger = getLogger([
+			"fedify",
+			"sig",
+			"key"
+		]);
+		const keyId = cacheKey.href;
+		const keyCache = options.keyCache;
+		if (isPortableUri(cacheKey)) {
+			const result = await fetchPortableActorKey(cacheKey, cls, options, onCachedUnavailable, onFetchError, logger);
+			outcome = result.outcome;
+			return result.result;
+		}
+		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" };
+			return didKey;
+		}
+		const cached = await getCachedFetchKey(cacheKey, keyId, cls, keyCache, logger);
+		if (cached?.key === null && cached.cached) {
+			const cachedUnavailable = await onCachedUnavailable(cacheKey, keyId, keyCache, logger);
+			outcome = { result: "hit" };
+			return cachedUnavailable;
+		}
+		if (cached != null && !claimsPortableOwner(cached.key)) {
+			outcome = { result: "hit" };
+			return cached;
+		}
+		logger.debug("Fetching key {keyId} to verify signature...", { keyId });
+		let document;
+		let documentUrl = cacheKey;
+		try {
+			const remoteDocument = await (options.documentLoader ?? getDocumentLoader())(keyId);
+			document = remoteDocument.document;
+			documentUrl = new URL(remoteDocument.documentUrl ?? "", cacheKey);
+		} catch (error) {
+			const classified = classifyFetchError(error);
+			const errored = await onFetchError(error, cacheKey, keyId, keyCache, logger);
+			outcome = classified;
+			return errored;
+		}
+		const resolved = await resolveFetchedKey(document, cacheKey, documentUrl, keyId, cls, options, logger);
+		outcome = { result: resolved.key != null ? "fetched" : "invalid" };
+		return resolved;
+	} finally {
+		recordKeyLookup(options.meterProvider, {
+			durationMs: getDurationMs(start),
+			result: outcome.result,
+			remoteUrl: cacheKey,
+			cacheEnabled: options.keyCache != null,
+			statusCode: outcome.statusCode
+		});
+	}
+}
+/**
+* Tells which purpose a lookup of a key at a compatible identifier serves.
+*/
+function getCompatibleKeyScope(cls, options) {
+	if (cls !== CryptographicKey) return "multikey";
+	return options.portableKeyResolvers == 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 getCachedCompatibleKey(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" }
+	};
+}
+/**
+* Looks up a key of an [FEP-ef61] portable actor at an `ap:` or `ap+ef61:`
+* key ID.  Such a key is accepted only for HTTP Signatures, and is rejected
+* for any other purpose without being fetched.  Like keys at compatible
+* identifiers, what it resolves to is cached in the namespace of the lookup's
+* purpose, and a failure to fetch the actor's document from every gateway is
+* cached in the shared namespace.  A failure that is neither, e.g., one
+* gateway being unreachable while another served an invalid document, is not
+* cached at all.
+*
+* [FEP-ef61]: https://w3id.org/fep/ef61
+*/
+async function fetchPortableActorKey(cacheKey, cls, options, onCachedUnavailable, onFetchError, logger) {
+	const keyId = cacheKey.href;
+	const resolvers = options.portableKeyResolvers;
+	if (resolvers == null || cls !== CryptographicKey) {
+		logger.debug("Failed to verify; key {keyId} is a key of a portable actor, which is only accepted for HTTP Signatures.", { keyId });
+		return {
+			result: {
+				key: null,
+				cached: false
+			},
+			outcome: { result: "invalid" }
+		};
+	}
+	const sharedCache = options.keyCache;
+	const scopedCache = sharedCache?.compatibleKeyScope?.("httpSignature");
+	const cached = await getCachedCompatibleKey(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("Resolving key {keyId} to verify signature...", { keyId });
+	const resolution = await resolvers.actorKey(cacheKey);
+	if (resolution.type === "verified") {
+		attachResolvedKeyOwnerEvidence(resolution, scopedCache, await scopedCache?.set(cacheKey, resolution.key, {
+			expires: resolution.expires,
+			owner: resolution.document
+		}));
+		return {
+			result: {
+				key: resolution.key,
+				cached: false
+			},
+			outcome: { result: "fetched" }
+		};
+	}
+	if (resolution.type === "rejected") {
+		await scopedCache?.set(cacheKey, null);
+		return {
+			result: {
+				key: null,
+				cached: false
+			},
+			outcome: { result: "invalid" }
+		};
+	}
+	await scopedCache?.delete(cacheKey);
+	return {
+		result: await onFetchError(resolution.error, cacheKey, keyId, resolution.cacheable ? sharedCache : void 0, logger),
+		outcome: resolution.cacheable ? classifyFetchError(resolution.error) : { result: "error" }
+	};
+}
+async function fetchKeyInternal(keyId, cls, options = {}) {
+	return await fetchKeyWithResult(typeof keyId === "string" ? parseKeyIdOrThrow(keyId) : keyId, cls, options, async (_cacheKey, _keyId, _keyCache, _logger) => {
+		const check = options[verificationObservation]?.check;
+		if (check != null) try {
+			const result = await _keyCache?.getFetchError?.(_cacheKey);
+			if (result != null) check.reason = {
+				type: "keyFetchError",
+				keyId: new URL(_cacheKey.href),
+				result
+			};
+		} catch {}
+		return {
+			key: null,
+			cached: true
+		};
+	}, async (error, cacheKey, keyId, keyCache, logger) => {
+		const check = options[verificationObservation]?.check;
+		if (check != null) {
+			let result;
+			try {
+				result = error instanceof FetchError && error.response != null ? {
+					status: error.response.status,
+					response: error.response.clone()
+				} : { error: error instanceof Error ? error : new Error(String(error)) };
+			} catch {
+				result = { error: error instanceof Error ? error : /* @__PURE__ */ new Error() };
+			}
+			check.reason = {
+				type: "keyFetchError",
+				keyId: new URL(cacheKey.href),
+				result
+			};
+		}
+		logger.debug("Failed to fetch key {keyId}.", {
+			keyId,
+			error
+		});
+		await keyCache?.set(cacheKey, null);
+		if (error instanceof FetchError && error.response != null) await keyCache?.setFetchError?.(cacheKey, {
+			status: error.response.status,
+			response: error.response.clone()
+		});
+		else await keyCache?.setFetchError?.(cacheKey, { error: error instanceof Error ? error : new Error(String(error)) });
+		return {
+			key: null,
+			cached: false
+		};
+	});
+}
+//#endregion
+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 };