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

package/dist/portable-key-BIMLrAP4.mjs

@@ -0,0 +1,549 @@
+import "temporal-polyfill";
+import "urlpattern-polyfill";
+globalThis.addEventListener = () => {};
+import { a as getRawCanonicalPortableId, c as isPortableActorDocument, d as isPortableUri, n as getCanonicalPortableId, p as isSamePublicKey } from "./portable-key-id-Ca30-hOa.mjs";
+import { u as verifyPortableObjectProofWithRoot } from "./proof-Dxy6ByqI.mjs";
+import { getLogger } from "@logtape/logtape";
+import { CryptographicKey, Multikey, Object as Object$1 } from "@fedify/vocab";
+import { FetchError, formatIri, getDocumentLoader, isGatewayUrl, parseIri, toCompatibleEf61Id } from "@fedify/vocab-runtime";
+import { getPortableGatewayCandidates } from "@fedify/vocab-runtime/internal/portable-dereference";
+//#region src/sig/portable-key.ts
+const logger = getLogger([
+	"fedify",
+	"sig",
+	"key"
+]);
+const SEC = "https://w3id.org/security#";
+/**
+* Verifies that the signed document of a portable actor vouches for
+* the gateway key with the given ID.
+*
+* A gateway key is accepted only if:
+*
+*  -  the document is an actor whose portable ID, i.e., its `ap:` ID or
+*     the canonical portable ID of its compatible identifier, is the one
+*     the key ID is the compatible identifier of;
+*  -  the document has a valid [FEP-8b32] Object Integrity Proof made by
+*     the DID of its ID, i.e., it satisfies the [FEP-ef61] proof policy;
+*  -  the document embeds a `Multikey` with that ID in its `assertionMethod`,
+*     whose `controller` is the actor, as [FEP-521a] requires, and a key
+*     embedded in its `publicKey` with the same ID agrees with it; or, if
+*     no `assertionMethod` entry has that ID, the document embeds
+*     a `CryptographicKey` with that ID in its `publicKey`, whose `owner` is
+*     the actor, as some publishers, e.g., tootik, list their RSA keys only
+*     there;
+*  -  no more than one entry of either property has that ID; and
+*  -  the key ID's origin is one of the actor's `gateways`.
+*
+* An entry has the key's ID if its ID is the key ID, or any compatible
+* identifier on the same gateway, or the `ap:` or `ap+ef61:` URI, with the
+* same canonical portable ID.  Some publishers, e.g., Mitra, list the keys
+* of portable actors under `ap:` URIs, but sign requests with compatible key
+* IDs on their own gateways.  IDs are compared as they are written in
+* the signed document, so an ID that URL parsing would turn into another,
+* e.g., by resolving dot segments, has no match.
+*
+* [FEP-8b32]: https://w3id.org/fep/8b32
+* [FEP-ef61]: https://w3id.org/fep/ef61
+* [FEP-521a]: https://w3id.org/fep/521a
+*
+* @param document The raw JSON-LD document served at the key ID.
+* @param actor The parsed document, which must be a portable actor.
+* @param keyId The key ID, which must be a compatible key ID.
+* @param options Loaders and telemetry providers.
+* @returns The verification result, which is never `legacy`.
+* @internal
+*/
+function verifyPortableGatewayKeyDocument(document, actor, keyId, options = {}) {
+	return verifyPortableKeyDocument(document, actor, keyId, true, options);
+}
+/**
+* Verifies that the signed document of a portable actor vouches for the key
+* with the given ID, either a gateway key at a compatible key ID, or a key of
+* the actor itself at an `ap:` or `ap+ef61:` key ID.  See
+* {@link verifyPortableGatewayKeyDocument} for the rules; a key of the actor
+* itself names no gateway, so instead of the key ID's origin being one of
+* the actor's `gateways`, the actor only has to have a valid gateway, as
+* FEP-ef61 requires of every portable actor.
+*/
+async function verifyPortableKeyDocument(document, actor, keyId, isGatewayKey, options) {
+	const reject = (reason) => {
+		logger.debug("Failed to verify key {keyId} of the portable actor {actorId}: {reason}", {
+			keyId: formatIri(keyId),
+			actorId: actor.id?.href,
+			reason
+		});
+		return {
+			type: "rejected",
+			reason
+		};
+	};
+	const keyBase = new URL(keyId.href);
+	keyBase.hash = "";
+	const claimedActorId = getCanonicalPortableId(keyBase);
+	const claimedKeyId = getCanonicalPortableId(keyId);
+	const actorId = actor.id == null ? null : getCanonicalPortableId(actor.id);
+	if (claimedActorId == null || claimedKeyId == null || actorId == null) return reject("The key ID or the actor ID is not a valid portable ID.");
+	if (claimedActorId !== actorId) return reject("The key ID is not a compatible identifier of the actor it dereferences to.");
+	let verification;
+	try {
+		verification = await verifyPortableObjectProofWithRoot(document, {
+			documentLoader: options.documentLoader,
+			contextLoader: options.contextLoader,
+			keyCache: options.keyCache,
+			tracerProvider: options.tracerProvider,
+			meterProvider: options.meterProvider
+		});
+	} catch (error) {
+		if (!(error instanceof TypeError)) throw error;
+		return reject(`The actor document is malformed: ${error.message}`);
+	}
+	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}.`));
+	const parseEmbeddedPublicKey = async (node) => {
+		if (isReference(node)) return null;
+		let key;
+		try {
+			key = await CryptographicKey.fromJsonLd(node, {
+				documentLoader: refuse,
+				contextLoader: options.contextLoader,
+				tracerProvider: options.tracerProvider
+			});
+		} catch (error) {
+			if (!(error instanceof TypeError)) throw error;
+			return null;
+		}
+		return key.publicKey == null ? null : key;
+	};
+	let verifiedActor;
+	try {
+		verifiedActor = await Object$1.fromJsonLd(root, {
+			documentLoader: refuse,
+			contextLoader: options.contextLoader,
+			tracerProvider: options.tracerProvider
+		});
+	} catch (error) {
+		if (!(error instanceof TypeError)) throw error;
+		return reject("The verified actor document is malformed.");
+	}
+	const rootId = root["@id"];
+	if (!isPortableActorDocument(verifiedActor) || getCanonicalPortableId(verifiedActor.id) !== claimedActorId || typeof rootId !== "string" || getRawCanonicalPortableId(rootId) !== claimedActorId) return reject("The key ID is not a compatible identifier of the actor whose document is signed.");
+	actor = verifiedActor;
+	const findKeyNodes = (values) => findNodes(values, claimedKeyId, isGatewayKey ? keyId.origin : null);
+	const assertionNodes = findKeyNodes(root[`${SEC}assertionMethod`]);
+	const publicKeyNodes = findKeyNodes(root[`${SEC}publicKey`]);
+	if (assertionNodes.length > 1 || publicKeyNodes.length > 1) return reject("The actor document has more than one key with the ID.");
+	let publicKey;
+	if (assertionNodes.length > 0) {
+		if (isReference(assertionNodes[0])) return reject("The actor document does not embed the key in its assertionMethod.");
+		let multikey;
+		try {
+			multikey = await Multikey.fromJsonLd(assertionNodes[0], {
+				documentLoader: refuse,
+				contextLoader: options.contextLoader,
+				tracerProvider: options.tracerProvider
+			});
+		} catch (error) {
+			if (!(error instanceof TypeError)) throw error;
+			return reject("The key in the assertionMethod is malformed.");
+		}
+		if (multikey.publicKey == null) return reject("The key in the assertionMethod has no public key.");
+		if (multikey.controllerId == null || getCanonicalPortableId(multikey.controllerId) !== actorId) return reject("The controller of the key is not the actor.");
+		publicKey = multikey.publicKey;
+		if (publicKeyNodes.length > 0 && !isReference(publicKeyNodes[0])) {
+			const embedded = await parseEmbeddedPublicKey(publicKeyNodes[0]);
+			if (embedded == null || !await isSamePublicKey(embedded.publicKey, publicKey) || embedded.ownerId != null && getCanonicalPortableId(embedded.ownerId) !== actorId) return reject("The key in the publicKey does not agree with the one in the assertionMethod.");
+		}
+	} else {
+		if (publicKeyNodes.length < 1) return reject("The actor document embeds the key in neither its assertionMethod nor its publicKey.");
+		const embedded = await parseEmbeddedPublicKey(publicKeyNodes[0]);
+		if (embedded == null) return reject("The key in the publicKey is not embedded or malformed.");
+		if (embedded.ownerId == null || getCanonicalPortableId(embedded.ownerId) !== actorId) return reject("The owner of the key is not the actor.");
+		publicKey = embedded.publicKey;
+	}
+	if (isGatewayKey) {
+		if (!actor.gateways.some((gateway) => isGatewayUrl(gateway) && gateway.origin === keyId.origin)) return reject(`The gateway ${keyId.origin} is not listed in the actor's gateways.`);
+	} else if (!actor.gateways.some(isGatewayUrl)) return reject("The actor has no valid gateways.");
+	const key = new CryptographicKey({
+		id: keyId,
+		owner: actor.id,
+		publicKey
+	});
+	return {
+		type: "verified",
+		actor,
+		key,
+		document: root,
+		...expires == null ? {} : { expires }
+	};
+}
+/**
+* Fetches the document at a compatible key ID, and resolves the key as
+* a gateway key if the document is a portable actor.
+*
+* @param keyId The key ID, which must be a compatible key ID.
+* @param options Loaders and telemetry providers.
+* @returns `legacy` if the document cannot be fetched or is not a portable
+*          actor, which leaves the key to the usual resolution; otherwise,
+*          the result of {@link verifyPortableGatewayKeyDocument}.
+* @internal
+*/
+async function fetchPortableGatewayKey(keyId, options = {}) {
+	const documentLoader = options.documentLoader ?? getDocumentLoader();
+	const contextLoader = options.contextLoader ?? getDocumentLoader();
+	let remoteDocument;
+	try {
+		remoteDocument = await documentLoader(keyId.href);
+	} catch (error) {
+		logger.debug("Failed to fetch key {keyId}: {error}", {
+			keyId: keyId.href,
+			error
+		});
+		return { type: "legacy" };
+	}
+	let object;
+	try {
+		object = await Object$1.fromJsonLd(remoteDocument.document, {
+			documentLoader,
+			contextLoader,
+			tracerProvider: options.tracerProvider
+		});
+	} catch (error) {
+		if (!(error instanceof TypeError)) throw error;
+		return { type: "legacy" };
+	}
+	if (!isPortableActorDocument(object)) return { type: "legacy" };
+	return await verifyPortableGatewayKeyDocument(remoteDocument.document, object, keyId, {
+		...options,
+		documentLoader,
+		contextLoader
+	});
+}
+/**
+* The maximum number of `@gateway` location hints followed for one `ap:` or
+* `ap+ef61:` key ID.  Whoever made a signature chooses the hints of its key
+* ID, so fewer of them are followed than when dereferencing objects, which
+* bounds the gateways one signature can make Fedify ask.  Further hints are
+* ignored.
+*/
+const MAX_KEY_ID_GATEWAY_HINTS = 3;
+/**
+* The default of {@link PortableActorKeyOptions.lookupTimeout}, in
+* milliseconds.
+*/
+const DEFAULT_KEY_ID_LOOKUP_TIMEOUT = 1e4;
+/** The longest delay that `setTimeout()` supports, in milliseconds. */
+const MAX_TIMEOUT = 2 ** 31 - 1;
+/**
+* Resolves a key of a portable actor at an `ap:` or `ap+ef61:` key ID, e.g.,
+* `ap://did:key:z6Mk…/actor#main-key`.  Such a key ID names no gateway, so
+* the actor's document, i.e., the key ID without its fragment, is fetched
+* through the gateways in its `@gateway` location hints, one after another,
+* until one of them serves a document that vouches for the key.  Without
+* location hints, the document loader is asked for the `ap:` URI itself,
+* which only a custom document loader can resolve.  The hints are chosen by
+* whoever made the signature, but that does not matter: only a document with
+* a valid proof by the DID of the key ID vouches for the key.
+*
+* The key is taken as a key of the actor itself, not of a gateway, so it is
+* accepted by the rules of {@link verifyPortableGatewayKeyDocument}, except
+* that it is listed under the `ap:` or `ap+ef61:` URI with the same canonical
+* ID as the key ID, and that the actor only has to have a valid gateway.
+* The key ID must have a fragment; a key served as a standalone document is
+* not supported.
+*
+* If no gateway serves a document that vouches for the key, the result is
+* `rejected` only if every gateway served a document that definitely does not
+* vouch for it.  If every gateway failed to serve a document at all, the
+* result is a cacheable `unavailable`, with the error of the first gateway if
+* every gateway responded with the same HTTP status, so that the status
+* describes the whole lookup.  Otherwise, e.g., if one gateway was
+* unreachable and another served an invalid document, nothing tells what the
+* unreachable gateway would have served, so the result is an `unavailable`
+* that is not cacheable.
+*
+* Only the first {@link MAX_KEY_ID_GATEWAY_HINTS} location hints are
+* followed, and all the gateways share one timeout, see
+* {@link PortableActorKeyOptions.lookupTimeout}.  A gateway that does not
+* serve the document in time failed to serve it, like an unreachable one,
+* with an error that has no HTTP status.  A gateway whose document could not
+* be processed in time, and the gateways left untried, make the result an
+* `unavailable` that is not cacheable.  A result that arrives after
+* the timeout is ignored, even if it vouches for the key.
+*
+* @param keyId The key ID, which must be an `ap:` or `ap+ef61:` URI.
+* @param options Loaders, telemetry providers, and the timeout.
+* @returns The resolution, which is never `legacy`.
+* @throws {RangeError} If the timeout is not a non-negative number of
+*                      milliseconds that `setTimeout()` supports.
+* @internal
+*/
+async function resolvePortableActorKey(keyId, options = {}) {
+	const lookupTimeout = options.lookupTimeout ?? DEFAULT_KEY_ID_LOOKUP_TIMEOUT;
+	if (!Number.isFinite(lookupTimeout) || lookupTimeout < 0 || lookupTimeout > MAX_TIMEOUT) throw new RangeError(`The lookup timeout must be between 0 and ${MAX_TIMEOUT} ms: ${lookupTimeout}`);
+	const documentLoader = options.documentLoader ?? getDocumentLoader();
+	const contextLoader = options.contextLoader ?? getDocumentLoader();
+	let formattedKeyId = keyId.href;
+	const reject = (reason) => {
+		logger.debug("Failed to verify key {keyId} of a portable actor: {reason}", {
+			keyId: formattedKeyId,
+			reason
+		});
+		return {
+			type: "rejected",
+			reason
+		};
+	};
+	if (!isPortableUri(keyId) || getCanonicalPortableId(keyId) == null) return reject("The key ID is not a valid ap: or ap+ef61: URI.");
+	formattedKeyId = formatIri(keyId);
+	if (keyId.hash === "" || keyId.hash === "#") return reject("The key ID has no fragment; only keys embedded in actor documents are supported.");
+	const actorUrl = new URL(keyId.href);
+	actorUrl.hash = "";
+	const gateways = getPortableGatewayCandidates(actorUrl);
+	if (gateways.length > MAX_KEY_ID_GATEWAY_HINTS) logger.debug("Following only the first {max} location hints of key {keyId}.", {
+		keyId: formattedKeyId,
+		max: MAX_KEY_ID_GATEWAY_HINTS
+	});
+	const requestUrls = [];
+	for (const gateway of gateways.slice(0, MAX_KEY_ID_GATEWAY_HINTS)) try {
+		requestUrls.push(toCompatibleEf61Id(actorUrl, gateway).href);
+	} catch (error) {
+		if (!(error instanceof TypeError)) throw error;
+		return reject(`The key ID cannot be fetched from gateways: ${error}`);
+	}
+	if (requestUrls.length < 1) requestUrls.push(formatIri(actorUrl));
+	const controller = new AbortController();
+	const timeoutError = new DOMException(`Timed out looking up the actor of key ${formattedKeyId} after ${lookupTimeout} ms.`, "TimeoutError");
+	let timer;
+	if (lookupTimeout > 0) timer = setTimeout(() => controller.abort(timeoutError), lookupTimeout);
+	else controller.abort(timeoutError);
+	const { signal } = controller;
+	const attemptOptions = {
+		...options,
+		documentLoader: withDeadline(documentLoader, signal),
+		contextLoader: withDeadline(contextLoader, signal),
+		signal,
+		formattedKeyId
+	};
+	const attempts = [];
+	try {
+		for (const url of requestUrls) {
+			if (signal.aborted) {
+				logger.debug("Ran out of time looking up the actor of key {keyId}; gateways from {url} on were not tried.", {
+					keyId: formattedKeyId,
+					url
+				});
+				attempts.push({
+					type: "indeterminate",
+					error: signal.reason
+				});
+				break;
+			}
+			const state = { processing: false };
+			let attempt;
+			try {
+				attempt = await raceAbort(attemptGateway(url, keyId, attemptOptions, state), signal);
+			} catch (error) {
+				if (!signal.aborted) throw error;
+				logger.debug("Ran out of time looking up the actor of key {keyId} at {url}.", {
+					keyId: formattedKeyId,
+					url
+				});
+				attempts.push({
+					type: state.processing ? "indeterminate" : "retrievalFailed",
+					error: signal.reason
+				});
+				continue;
+			}
+			if (attempt.type === "verified") return attempt;
+			attempts.push(attempt);
+		}
+	} finally {
+		clearTimeout(timer);
+	}
+	const rejections = attempts.flatMap((a) => a.type === "rejected" ? [a.reason] : []);
+	if (rejections.length === attempts.length) return reject(rejections.join(" "));
+	const errors = attempts.flatMap((a) => a.type === "rejected" ? [] : [a.error]);
+	const aggregate = errors.length === 1 ? errors[0] : new AggregateError(errors, `Failed to fetch the actor of key ${formattedKeyId} from any of its gateways: ${requestUrls.join(", ")}`);
+	if (attempts.every((a) => a.type === "retrievalFailed")) {
+		const statuses = errors.map((error) => error instanceof FetchError ? error.response?.status : void 0);
+		return {
+			type: "unavailable",
+			error: statuses[0] != null && statuses.every((status) => status === statuses[0]) ? errors[0] : aggregate,
+			cacheable: true
+		};
+	}
+	return {
+		type: "unavailable",
+		error: new Error(`Could not determine whether the actor of key ${formattedKeyId} vouches for it.`, { cause: aggregate }),
+		cacheable: false
+	};
+}
+/**
+* Fetches the actor's document of a key at an `ap:` or `ap+ef61:` key ID from
+* one gateway, and tells whether it vouches for the key.  It never rejects;
+* the caller races it against the lookup's timeout, and ignores what it
+* resolves to after the timeout.
+*/
+async function attemptGateway(url, keyId, options, state) {
+	const { documentLoader, contextLoader, signal, formattedKeyId } = options;
+	let remoteDocument;
+	try {
+		remoteDocument = await documentLoader(url);
+	} catch (error) {
+		logger.debug("Failed to fetch the actor of key {keyId} from {url}: {error}", {
+			keyId: formattedKeyId,
+			url,
+			error
+		});
+		return {
+			type: "retrievalFailed",
+			error
+		};
+	}
+	if (signal.aborted) return {
+		type: "indeterminate",
+		error: signal.reason
+	};
+	state.processing = true;
+	let resolution;
+	try {
+		const object = await Object$1.fromJsonLd(remoteDocument.document, {
+			documentLoader,
+			contextLoader,
+			tracerProvider: options.tracerProvider
+		});
+		signal.throwIfAborted();
+		resolution = isPortableActorDocument(object) ? await verifyPortableKeyDocument(remoteDocument.document, object, keyId, false, options) : {
+			type: "rejected",
+			reason: "The document is not a portable actor."
+		};
+	} catch (error) {
+		if (error instanceof TypeError && !signal.aborted) resolution = {
+			type: "rejected",
+			reason: `The document is malformed: ${error.message}`
+		};
+		else {
+			logger.debug("Failed to process the actor of key {keyId} served from {url}: {error}", {
+				keyId: formattedKeyId,
+				url,
+				error
+			});
+			return {
+				type: "indeterminate",
+				error
+			};
+		}
+	}
+	if (resolution.type === "verified") return resolution;
+	const reason = resolution.type === "rejected" ? resolution.reason : "The document is not a portable actor.";
+	logger.debug("The actor document served from {url} does not vouch for key {keyId}: {reason}", {
+		keyId: formattedKeyId,
+		url,
+		reason
+	});
+	return {
+		type: "rejected",
+		reason
+	};
+}
+/**
+* Wraps a document loader so that it gives up when the given signal aborts,
+* as well as when the signal in its own options does.  The wrapped loader is
+* passed a signal that aborts in either case, but in case it ignores that
+* signal, what it resolves to after the abort is ignored, and the wrapper
+* rejects with the reason of the abort at once.  After the abort, the wrapped
+* loader is not called at all.
+*/
+function withDeadline(loader, signal) {
+	return (url, options) => {
+		const combined = combineSignals(signal, options?.signal);
+		return raceAbort(combined.signal.aborted ? Promise.reject(combined.signal.reason) : new Promise((resolve) => resolve(loader(url, {
+			...options,
+			signal: combined.signal
+		}))), combined.signal).finally(combined.dispose);
+	};
+}
+/**
+* Makes a signal that aborts when either of the given signals does, with
+* the reason of the one that aborted first.  `AbortSignal.any()` is not
+* available on every supported runtime, e.g., Bun before 1.1.4.
+* @returns The signal, and a function that stops listening to the given
+*          signals.
+*/
+function combineSignals(signal, other) {
+	if (other == null || other === signal) return {
+		signal,
+		dispose() {}
+	};
+	const controller = new AbortController();
+	const sources = [signal, other];
+	const dispose = () => {
+		for (const source of sources) source.removeEventListener("abort", onAbort);
+	};
+	function onAbort() {
+		dispose();
+		controller.abort(this.reason);
+	}
+	const aborted = sources.find((source) => source.aborted);
+	if (aborted == null) for (const source of sources) source.addEventListener("abort", onAbort);
+	else controller.abort(aborted.reason);
+	return {
+		signal: controller.signal,
+		dispose
+	};
+}
+/**
+* Waits for the given promise unless the given signal aborts first, in which
+* case it rejects with the reason of the abort.  If the signal has aborted by
+* the time the promise settles, the abort wins as well, so that nothing that
+* settles after it counts.
+*/
+function raceAbort(promise, signal) {
+	return new Promise((resolve, reject) => {
+		const onAbort = () => reject(signal.reason);
+		const settle = (settled) => {
+			signal.removeEventListener("abort", onAbort);
+			if (signal.aborted) onAbort();
+			else settled();
+		};
+		promise.then((value) => settle(() => resolve(value)), (error) => settle(() => reject(error)));
+		if (signal.aborted) onAbort();
+		else signal.addEventListener("abort", onAbort, { once: true });
+	});
+}
+/**
+* Finds the nodes that stand for the key with the given canonical portable
+* ID.  A node whose ID is an `ap:` or `ap+ef61:` URI stands for the key
+* itself, e.g., Mitra lists the keys of portable actors that way while
+* signing requests with compatible key IDs.  A node whose ID is a compatible
+* identifier stands for a gateway's key, so it matches only a compatible key
+* ID on the same gateway; a key ID that names no gateway never selects
+* a gateway's key, even with the same fragment.
+* @param values The expanded values of a key property.
+* @param canonicalKeyId The canonical portable ID of the key ID.
+* @param gateway The origin of the gateway whose key the key ID names, or
+*                `null` if the key ID names no gateway.
+*/
+function findNodes(values, canonicalKeyId, gateway) {
+	if (!Array.isArray(values)) return [];
+	const nodes = [];
+	for (const value of values) {
+		if (value == null || typeof value !== "object" || Array.isArray(value)) continue;
+		const node = value;
+		const nodeId = node["@id"];
+		if (typeof nodeId !== "string") continue;
+		if (getRawCanonicalPortableId(nodeId) !== canonicalKeyId) continue;
+		const parsed = parseIri(nodeId);
+		if (isPortableUri(parsed) || parsed.origin === gateway) nodes.push(node);
+	}
+	return nodes;
+}
+/** A node with nothing but an `@id` is a reference, not an embedded key. */
+function isReference(node) {
+	return Object.keys(node).every((key) => key === "@id");
+}
+//#endregion
+export { resolvePortableActorKey as n, verifyPortableGatewayKeyDocument as r, fetchPortableGatewayKey as t };