@fedify/vocab 2.4.0-pr.936.41 → 2.4.0

package/dist-tests/lookup-IiNFWuXL.mjs

@@ -0,0 +1,480 @@
+import { Temporal } from "temporal-polyfill";
+globalThis.addEventListener = () => {};
+import { A as Object$1 } from "./vocab-COZcxf00.mjs";
+import { i as isActor, o as name, s as version } from "./actor-D7_iX4I4.mjs";
+import { t as getTypeId } from "./type-BMdjm4Eg.mjs";
+import { canonicalizePortableUri, formatIri, getDocumentLoader, haveSameFe34Origin, haveSameIriOrigin, parseIri } from "@fedify/vocab-runtime";
+import { lookupWebFinger } from "@fedify/webfinger";
+import { SpanStatusCode, trace } from "@opentelemetry/api";
+import { getLogger } from "@logtape/logtape";
+import { PortableObjectRejectedError, createSnapshotContextLoader, dereferencePortableIri, getPortableGatewayCandidates, getPortableResponseClaim, isPortableIri, parseCompatibleEf61Reference } from "@fedify/vocab-runtime/internal/portable-dereference";
+import { delay } from "es-toolkit";
+//#region src/handle.ts
+/**
+* Regular expression to match a fediverse handle in the format `@user@server`
+* or `user@server`.  The `user` part can contain alphanumeric characters and
+* some special characters except `@`.  The `server` part is all characters
+* after the `@` symbol in the middle.
+*/
+const handleRegexp = /^@?((?:[-A-Za-z0-9._~!$&'()*+,;=]|%[A-Fa-f0-9]{2})+)@([^@]+)$/;
+/**
+* Parses a fediverse handle in the format `@user@server` or `user@server`.
+* The `user` part can contain alphanumeric characters and some special
+* characters except `@`.  The `server` part is all characters after the `@`
+* symbol in the middle.
+*
+* @example
+* ```typescript
+* const handle = parseFediverseHandle("@username@example.com");
+* console.log(handle?.username); // "username"
+* console.log(handle?.host);     // "example.com"
+* ```
+*
+* @param handle - The fediverse handle string to parse.
+* @returns A {@link FediverseHandle} object with `username` and `host`
+*          if the input is valid; otherwise `null`.
+* @since 1.8.0
+*/
+function parseFediverseHandle(handle) {
+	const match = handleRegexp.exec(handle);
+	if (match) return {
+		username: match[1],
+		host: match[2]
+	};
+	return null;
+}
+/**
+* Converts a fediverse handle in the format `@user@server` or `user@server`
+* to an `acct:` URI, which is a URL-like identifier for ActivityPub actors.
+*
+* @example
+* ```typescript
+* const identifier = toAcctUrl("@username@example.com");
+* console.log(identifier?.href); // "acct:username@example.com"
+* ```
+*
+* @param handle - The fediverse handle string to convert.
+* @returns A `URL` object representing the `acct:` URI if conversion succeeds;
+*          otherwise `null`.
+* @since 1.8.0
+*/
+function toAcctUrl(handle) {
+	const parsed = parseFediverseHandle(handle);
+	if (!parsed) return null;
+	return new URL(`acct:${parsed.username}@${parsed.host}`);
+}
+//#endregion
+//#region src/lookup.ts
+const objectLookupCounters = /* @__PURE__ */ new WeakMap();
+function getObjectLookupCounter(meterProvider) {
+	let counter = objectLookupCounters.get(meterProvider);
+	if (counter == null) {
+		counter = meterProvider.getMeter(name, version).createCounter("activitypub.object.lookup", {
+			description: "ActivityStreams object lookups via lookupObject(), classified by whether the resolved value is an Actor.",
+			unit: "{lookup}"
+		});
+		objectLookupCounters.set(meterProvider, counter);
+	}
+	return counter;
+}
+function getLookupRemoteHost(identifier) {
+	let url;
+	if (identifier instanceof URL) url = identifier;
+	else if (PORTABLE_IRI_PATTERN.test(identifier)) return;
+	else try {
+		url = new URL(identifier);
+	} catch {
+		return extractHandleHost(identifier.startsWith("@") ? identifier.slice(1) : identifier);
+	}
+	if (isPortableIri(url)) return void 0;
+	if (url.host !== "") return url.host;
+	if (url.protocol === "acct:") return extractHandleHost(url.pathname);
+}
+function extractHandleHost(handle) {
+	const at = handle.lastIndexOf("@");
+	if (at < 0 || at >= handle.length - 1) return void 0;
+	const candidate = handle.slice(at + 1);
+	if (/[/?#\s]/.test(candidate)) return void 0;
+	try {
+		return new URL(`https://${candidate}`).host || void 0;
+	} catch {
+		return;
+	}
+}
+const logger = getLogger([
+	"fedify",
+	"vocab",
+	"lookup"
+]);
+/**
+* The maximum number of requests to FEP-ef61 gateways that a single
+* {@link lookupObject} call makes for portable objects.  Gateways come from
+* possibly untrusted WebFinger responses and location hints, so they are
+* bounded to keep a single lookup from fanning out to many servers.
+*/
+const MAX_PORTABLE_ATTEMPTS = 5;
+/**
+* Looks up an ActivityStreams object by its URI (including `acct:` URIs)
+* or a fediverse handle (e.g., `@user@server` or `user@server`).
+*
+* @example
+* ``` typescript
+* // Look up an actor by its fediverse handle:
+* await lookupObject("@hongminhee@fosstodon.org");
+* // returning a `Person` object.
+*
+* // A fediverse handle can omit the leading '@':
+* await lookupObject("hongminhee@fosstodon.org");
+* // returning a `Person` object.
+*
+* // A `acct:` URI can be used as well:
+* await lookupObject("acct:hongminhee@fosstodon.org");
+* // returning a `Person` object.
+*
+* // Look up an object by its URI:
+* await lookupObject("https://todon.eu/@hongminhee/112060633798771581");
+* // returning a `Note` object.
+*
+* // It can be a `URL` object as well:
+* await lookupObject(new URL("https://todon.eu/@hongminhee/112060633798771581"));
+* // returning a `Note` object.
+* ```
+*
+* [FEP-ef61] portable objects, including portable actors found through
+* WebFinger, are looked up only if the `verifyPortableObject` option is
+* given; see {@link LookupObjectOptions.verifyPortableObject}.  Pass
+* {@link LookupObjectOptions.gateways} to look up a portable ID without
+* `@gateway` location hints.
+*
+* [FEP-ef61]: https://w3id.org/fep/ef61
+*
+* @param identifier The URI or fediverse handle to look up.
+* @param options Lookup options.
+* @returns The object, or `null` if not found.
+* @since 0.2.0
+*/
+async function lookupObject(identifier, options = {}) {
+	return await (options.tracerProvider ?? trace.getTracerProvider()).getTracer(name, version).startActiveSpan("activitypub.lookup_object", async (span) => {
+		let kind = "other";
+		try {
+			const result = await lookupObjectInternal(identifier, options);
+			if (result != null) kind = isActor(result) ? "actor" : "object";
+			if (result == null) span.setStatus({ code: SpanStatusCode.ERROR });
+			else {
+				if (result.id != null) span.setAttribute("activitypub.object.id", result.id.href);
+				span.setAttribute("activitypub.object.type", getTypeId(result).href);
+				if (result.replyTargetIds.length > 0) span.setAttribute("activitypub.object.in_reply_to", result.replyTargetIds.map((id) => id.href));
+				span.addEvent("activitypub.object.fetched", {
+					"activitypub.object.type": getTypeId(result).href,
+					"activitypub.object.json": JSON.stringify(await result.toJsonLd(options))
+				});
+			}
+			return result;
+		} catch (error) {
+			span.recordException(error);
+			span.setStatus({
+				code: SpanStatusCode.ERROR,
+				message: String(error)
+			});
+			throw error;
+		} finally {
+			if (options.meterProvider != null) {
+				const attributes = { "activitypub.lookup.kind": kind };
+				const host = getLookupRemoteHost(identifier);
+				if (host != null) attributes["activitypub.remote.host"] = host;
+				getObjectLookupCounter(options.meterProvider).add(1, attributes);
+			}
+			span.end();
+		}
+	});
+}
+async function lookupObjectInternal(identifier, options = {}) {
+	const documentLoader = options.documentLoader ?? getDocumentLoader({ userAgent: options.userAgent });
+	const portable = {
+		options,
+		documentLoader,
+		attempted: /* @__PURE__ */ new Set(),
+		remaining: MAX_PORTABLE_ATTEMPTS
+	};
+	if (typeof identifier === "string") {
+		if (PORTABLE_IRI_PATTERN.test(identifier)) {
+			const candidate = parsePortableCandidate(identifier);
+			if (candidate == null) return null;
+			return await lookupPortableObject(portable, candidate, void 0);
+		}
+		if (options.verifyPortableObject != null && parseCompatibleEf61Reference(identifier) === null) return null;
+		identifier = toAcctUrl(identifier) ?? parseIri(identifier);
+	}
+	if (isPortableIri(identifier)) {
+		let candidate;
+		try {
+			candidate = parseIri(identifier);
+		} catch (error) {
+			if (error instanceof TypeError) return null;
+			throw error;
+		}
+		return await lookupPortableObject(portable, candidate, void 0);
+	}
+	let remoteDoc = null;
+	if (identifier.protocol === "http:" || identifier.protocol === "https:") {
+		const compatible = getCompatibleCandidate(identifier.href, options);
+		if (compatible !== void 0) {
+			if (compatible == null) return null;
+			return await lookupPortableObject(portable, compatible.id, [compatible.gateway]);
+		}
+		try {
+			remoteDoc = await documentLoader(identifier.href, { signal: options.signal });
+		} catch (error) {
+			logger.debug("Failed to fetch remote document:\n{error}", { error });
+		}
+	}
+	if (remoteDoc == null) {
+		const jrd = await lookupWebFinger(identifier, {
+			userAgent: options.userAgent,
+			tracerProvider: options.tracerProvider,
+			meterProvider: options.meterProvider,
+			allowPrivateAddress: "allowPrivateAddress" in options && options.allowPrivateAddress === true,
+			signal: options.signal
+		});
+		if (jrd?.links == null) return null;
+		const webFingerGateway = getWebFingerGateway(identifier);
+		for (const l of jrd.links) {
+			if (l.type !== "application/activity+json" && !l.type?.match(/application\/ld\+json;\s*profile="https:\/\/www.w3.org\/ns\/activitystreams"/) || l.rel !== "self" || l.href == null) continue;
+			if (PORTABLE_IRI_PATTERN.test(l.href)) {
+				if (options.verifyPortableObject == null) {
+					logger.debug("Skipping the portable self link {href}, as the verifyPortableObject option is not given.", { href: l.href });
+					continue;
+				}
+				const candidate = parsePortableCandidate(l.href);
+				if (candidate == null) continue;
+				const gateways = webFingerGateway == null ? [] : [webFingerGateway];
+				if (options.gateways == null) gateways.push(...getPortableGatewayCandidates(candidate));
+				const object = await lookupPortableObject(portable, candidate, gateways);
+				if (object != null) return object;
+				if (options.signal?.aborted) return null;
+				continue;
+			}
+			const compatible = getCompatibleCandidate(l.href, options);
+			if (compatible !== void 0) {
+				if (compatible == null) continue;
+				const object = await lookupPortableObject(portable, compatible.id, [compatible.gateway]);
+				if (object != null) return object;
+				if (options.signal?.aborted) return null;
+				continue;
+			}
+			try {
+				remoteDoc = await documentLoader(l.href, { signal: options.signal });
+				break;
+			} catch (error) {
+				logger.debug("Failed to fetch remote document:\n{error}", { error });
+				continue;
+			}
+		}
+	}
+	if (remoteDoc == null) return null;
+	const snapshot = options.verifyPortableObject == null ? null : createSnapshotContextLoader(options.contextLoader ?? getDocumentLoader({ userAgent: options.userAgent }));
+	try {
+		let object;
+		let documentUrl;
+		try {
+			documentUrl = parseIri(remoteDoc.documentUrl);
+			object = await Object$1.fromJsonLd(remoteDoc.document, {
+				documentLoader,
+				contextLoader: snapshot?.loader ?? options.contextLoader,
+				tracerProvider: options.tracerProvider,
+				verifyPortableObject: options.verifyPortableObject,
+				baseUrl: documentUrl
+			});
+		} catch (error) {
+			if (error instanceof TypeError) {
+				logger.debug("Failed to parse JSON-LD document: {error}\n{document}", {
+					...remoteDoc,
+					error
+				});
+				return null;
+			}
+			throw error;
+		}
+		if (snapshot != null) {
+			const claim = getPortableResponseClaim(remoteDoc.documentUrl, object.id);
+			if (claim === null) {
+				logger.debug("Refusing the document {documentUrl}, as it claims to be a portable object with a malformed compatible identifier.", { documentUrl: remoteDoc.documentUrl });
+				return null;
+			} else if (claim != null) {
+				const explicit = getExplicitGateways(portable, claim.id);
+				return await dereference(portable, claim.id, claim.inferredGateways, explicit, {
+					response: remoteDoc,
+					contextLoader: snapshot.loader
+				});
+			}
+		}
+		if (object.id != null && (options.crossOrigin !== "trust" || isPortableIri(object.id)) && !haveSameIriOrigin(object.id, documentUrl) && !haveSameFe34Origin(object.id, documentUrl)) {
+			if (options.crossOrigin === "throw") throw new Error(`The object's @id (${object.id.href}) has a different origin than the document URL (${remoteDoc.documentUrl}); refusing to return the object.  If you want to bypass this check and are aware of the security implications, set the crossOrigin option to "trust".`);
+			logger.warn("The object's @id ({objectId}) has a different origin than the document URL ({documentUrl}); refusing to return the object.  If you want to bypass this check and are aware of the security implications, set the crossOrigin option to \"trust\".", {
+				...remoteDoc,
+				objectId: object.id.href
+			});
+			return null;
+		}
+		return object;
+	} finally {
+		snapshot?.release();
+	}
+}
+const PORTABLE_IRI_PATTERN = /^ap(?:\+ef61)?:/i;
+function getExplicitGateways(lookup, id) {
+	if (lookup.options.gateways == null) return void 0;
+	return lookup.explicitGateways ??= getPortableGatewayCandidates(id, lookup.options.gateways);
+}
+/**
+* Parses a raw portable IRI.  URL parsing normalizes dot segments in the
+* opaque path, which would make the parsed IRI identify another portable
+* object, so such IRIs are refused.
+*/
+function parsePortableCandidate(iri) {
+	try {
+		const parsed = parseIri(iri);
+		if (canonicalizePortableUri(iri) !== canonicalizePortableUri(formatIri(parsed))) {
+			logger.debug("Refusing to look up the portable IRI {iri}, as its path cannot be represented without changing the identified object.", { iri });
+			return null;
+		}
+		return parsed;
+	} catch (error) {
+		if (error instanceof TypeError) {
+			logger.debug("Invalid portable IRI {iri}: {error}", {
+				iri,
+				error
+			});
+			return null;
+		}
+		throw error;
+	}
+}
+/**
+* Recognizes an FEP-ef61 compatible identifier to look up as a portable
+* object.
+* @returns `undefined` if the URL should be fetched as an ordinary HTTP(S)
+*          URL, i.e., it is not a compatible identifier, or the
+*          `verifyPortableObject` option is not given; `null` if it is
+*          a malformed compatible identifier; otherwise, the portable ID and
+*          the gateway to ask.
+*/
+function getCompatibleCandidate(href, options) {
+	if (options.verifyPortableObject == null) return void 0;
+	return parseCompatibleEf61Reference(href);
+}
+/**
+* Gets the origin of the WebFinger server that {@link lookupWebFinger} asks
+* for the identifier, which is also the first gateway of a portable actor.
+*/
+function getWebFingerGateway(identifier) {
+	let url;
+	if (identifier.protocol === "acct:") {
+		const host = extractHandleHost(identifier.pathname);
+		if (host == null) return void 0;
+		url = new URL(`https://${host}/`);
+	} else if (identifier.protocol === "http:" || identifier.protocol === "https:") url = new URL(identifier.origin);
+	else return;
+	return url.username === "" && url.password === "" ? url : void 0;
+}
+/**
+* Looks up a portable object through FEP-ef61 gateways.
+* @param inferredGateways Gateways inferred from a compatible identifier or
+*                         WebFinger.  If omitted, location hints in the IRI
+*                         are used unless explicit gateways were given.
+*/
+async function lookupPortableObject(lookup, id, inferredGateways) {
+	const { options } = lookup;
+	const iri = formatIri(id);
+	const explicitGateways = getExplicitGateways(lookup, id);
+	if (options.verifyPortableObject == null) {
+		logger.debug("Cannot look up the portable object {iri}, as the verifyPortableObject option is not given.", { iri });
+		return null;
+	}
+	const canonicalId = canonicalizePortableUri(iri);
+	const inferred = inferredGateways ?? (explicitGateways == null ? getPortableGatewayCandidates(id) : []);
+	const candidates = [...inferred];
+	for (const gateway of explicitGateways ?? []) if (!candidates.some((candidate) => candidate.href === gateway.href)) candidates.push(gateway);
+	if (candidates.length < 1 && inferredGateways == null) {
+		const key = `${canonicalId} `;
+		if (lookup.remaining < 1 || lookup.attempted.has(key)) return null;
+		lookup.attempted.add(key);
+		lookup.remaining--;
+		return await dereference(lookup, id, [], explicitGateways == null ? void 0 : []);
+	}
+	const selected = [];
+	for (const gateway of candidates) {
+		if (selected.length >= lookup.remaining) break;
+		const key = `${canonicalId} ${gateway.href}`;
+		if (lookup.attempted.has(key)) continue;
+		lookup.attempted.add(key);
+		selected.push(gateway);
+	}
+	if (selected.length < 1) return null;
+	lookup.remaining -= selected.length;
+	const selectedInferred = selected.filter((candidate) => inferred.some((gateway) => gateway.href === candidate.href));
+	const selectedExplicit = explicitGateways?.filter((gateway) => selected.some((candidate) => candidate.href === gateway.href));
+	return await dereference(lookup, id, selectedInferred, selectedExplicit);
+}
+async function dereference({ options, documentLoader }, id, inferredGateways, gateways, extra = {}) {
+	const tracerProvider = options.tracerProvider ?? trace.getTracerProvider();
+	try {
+		return await dereferencePortableIri(id, {
+			documentLoader,
+			contextLoader: extra.contextLoader ?? options.contextLoader ?? getDocumentLoader({ userAgent: options.userAgent }),
+			tracerProvider,
+			inferredGateways,
+			...gateways == null ? {} : { gateways },
+			response: extra.response,
+			verifyPortableObject: options.verifyPortableObject,
+			crossOrigin: options.crossOrigin === "throw" ? "throw" : "ignore",
+			signal: options.signal,
+			parse: (document, { contextLoader, baseUrl }) => Object$1.fromJsonLd(document, {
+				documentLoader,
+				contextLoader,
+				tracerProvider,
+				verifyPortableObject: options.verifyPortableObject,
+				baseUrl
+			})
+		});
+	} catch (error) {
+		if (error instanceof PortableObjectRejectedError) throw error;
+		logger.debug("Failed to look up the portable object {iri}:\n{error}", {
+			iri: formatIri(id),
+			error
+		});
+		return null;
+	}
+}
+/**
+* Traverses a collection, yielding each item in the collection.
+* If the collection is paginated, it will fetch the next page
+* automatically.
+*
+* @example
+* ``` typescript
+* const collection = await lookupObject(collectionUrl);
+* if (collection instanceof Collection) {
+*   for await (const item of traverseCollection(collection)) {
+*     console.log(item.id?.href);
+*   }
+* }
+* ```
+*
+* @param collection The collection to traverse.
+* @param options Options for traversing the collection.
+* @returns An async iterable of each item in the collection.
+* @since 1.1.0
+*/
+async function* traverseCollection(collection, options = {}) {
+	const interval = Temporal.Duration.from(options.interval ?? { seconds: 0 }).total("millisecond");
+	let page = await collection.getFirst(options);
+	if (page == null) for await (const item of collection.getItems(options)) yield item;
+	else while (page != null) {
+		for await (const item of page.getItems(options)) yield item;
+		if (interval > 0) await delay(interval);
+		page = await page.getNext(options);
+	}
+}
+//#endregion
+export { traverseCollection as n, lookupObject as t };