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

package/dist/internal/portable-dereference.js

@@ -0,0 +1,702 @@
+
+import { t as preloadedContexts } from "../contexts-DPuJ4UYL.js";
+import { _ as parseIri, h as parseGatewayOrigin, i as canonicalizePortableUri, o as formatIri, s as fromCompatibleEf61Id, t as GATEWAY_HINT_PARAMETER, u as haveSameFe34Origin, y as toCompatibleEf61Id } from "../url-Dzyp-NsC.js";
+import jsonld_default from "../jsonld.js";
+import { createScopedContextLoader, registerDocumentLoaderWrapper, unwrapReleasedDocumentLoader } from "./jsonld-cache.js";
+import { getLogger } from "@logtape/logtape";
+import { SpanStatusCode } from "@opentelemetry/api";
+//#region src/internal/portable-dereference.ts
+const logger = getLogger([
+	"fedify",
+	"vocab",
+	"gateway"
+]);
+/**
+* The maximum number of `@gateway` location hints to try for one reference.
+* Hints come from possibly untrusted documents, so they are bounded to keep
+* a single accessor call from fanning out to many servers.
+*/
+const MAX_GATEWAY_HINTS = 5;
+const BASELINE_CONTEXT_URLS = /* @__PURE__ */ new Set([
+	"https://w3id.org/identity/v1",
+	"https://www.w3.org/ns/activitystreams",
+	"https://w3id.org/security/v1",
+	"https://w3id.org/security/data-integrity/v1"
+]);
+/**
+* The maximum number of links in a referrer chain passed to a
+* {@link PortableObjectVerifier}.  Longer chains are cut off and marked as
+* truncated.
+*/
+const MAX_REFERRER_CHAIN_LENGTH = 32;
+const provenances = /* @__PURE__ */ new WeakMap();
+function getObjectId(object) {
+	if (object == null || typeof object !== "object" || !("id" in object)) return null;
+	const id = object.id;
+	return id instanceof URL ? id : null;
+}
+/**
+* Checks whether a vocabulary object is part of a chain of portable objects,
+* i.e., whether it has a portable ID, has an FEP-ef61 compatible identifier
+* as its ID (even a malformed one, so that it fails closed), or was obtained
+* from a portable object.  Accessors of such objects dereference references
+* as portable objects.
+*
+* Being part of a chain does not mean that the object itself is verified:
+* an object parsed from arbitrary JSON-LD is in a chain just because of its
+* ID.  Only {@link dereferencePortableIri} records that an object was
+* accepted by a verifier.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+function isInPortableChain(object) {
+	if (provenances.has(object)) return true;
+	const id = getObjectId(object);
+	return id != null && (isPortableIri(id) || isCompatibleEf61Iri(id));
+}
+/**
+* Checks whether a vocabulary object was accepted without an integrity
+* proof, e.g., as an unsecured portable collection served by a trusted
+* gateway.  Objects embedded in such an object must not be trusted because
+* of their origin.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+function isUnsecuredPortableObject(object) {
+	return provenances.get(object)?.acceptance === "unsecured";
+}
+/**
+* Checks whether a URL is an FEP-ef61 compatible identifier, i.e., an HTTP(S)
+* URL under a gateway's `/.well-known/apgateway/` path that stands for
+* a portable object.  Malformed compatible identifiers count as compatible
+* identifiers too.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+function isCompatibleEf61Iri(url) {
+	try {
+		return fromCompatibleEf61Id(url) != null;
+	} catch (error) {
+		if (error instanceof TypeError) return true;
+		throw error;
+	}
+}
+/**
+* Records that a vocabulary object returned by a property accessor was
+* obtained through the given property of a portable object, so that later
+* dereferences from it can tell where it came from.  Nothing is recorded if
+* the parent is not in a portable chain, or if the child already has its
+* provenance.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+function recordPortableReferrer(parent, child, property) {
+	if (child == null || typeof child !== "object") return;
+	if (provenances.has(child) || !isInPortableChain(parent)) return;
+	provenances.set(child, { referrer: {
+		object: parent,
+		property
+	} });
+}
+/**
+* Copies the provenance of a vocabulary object to its clone.  The clone
+* keeps where the original came from and the restriction on unsecured
+* objects, but not a positive verification status nor a collection context,
+* since the clone may have different property values.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+function copyPortableProvenance(from, to) {
+	const provenance = provenances.get(from);
+	if (provenance == null) return;
+	provenances.set(to, {
+		referrer: provenance.referrer,
+		...provenance.acceptance === "unsecured" ? { acceptance: "unsecured" } : {}
+	});
+}
+/**
+* Recognizes an FEP-ef61 compatible identifier to dereference as a portable
+* object.
+*
+* @returns `undefined` if the URL is not a compatible identifier; `null` if
+*          it is a malformed compatible identifier; otherwise, the portable
+*          ID it stands for and the gateway it names.
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+function parseCompatibleEf61Reference(url) {
+	try {
+		const id = fromCompatibleEf61Id(url);
+		if (id == null) return void 0;
+		if (typeof url === "string") url = new URL(url);
+		return {
+			id,
+			gateway: new URL(url.origin)
+		};
+	} catch (error) {
+		if (error instanceof TypeError) {
+			logger.debug("Invalid FEP-ef61 compatible identifier {url}: {error}", {
+				url: typeof url === "string" ? url : url.href,
+				error
+			});
+			return null;
+		}
+		throw error;
+	}
+}
+/**
+* Checks whether a property accessor call on a vocabulary object applies the
+* FEP-ef61 portable object policy, i.e., whether the `verifyPortableObject`
+* option is given or the object is part of a chain of portable objects.
+* In this mode, compatible identifiers are dereferenced as portable objects,
+* and fetched documents that turn out to stand for portable objects are
+* verified as such.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+function isPortableMode(object, options) {
+	return options.verifyPortableObject != null || isInPortableChain(object);
+}
+/**
+* Checks whether an object embedded in a property of a vocabulary object has
+* to be dereferenced by its `@id` and verified as a portable object rather
+* than trusted as embedded, even with `crossOrigin: "trust"`.  This is the
+* case in {@link isPortableMode | portable mode} if its `@id` is an FEP-ef61
+* compatible identifier, or a portable IRI whose DID differs from the
+* owner's portable ID.
+*
+* @param parent The object whose property embeds the object.
+* @param ownerId The ID of the object that vouches for embedded objects, or
+*                `null` if embedded objects are not trusted by their owner.
+* @param id The `@id` of the embedded object.
+* @param options The options of the accessor.
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+function mustDereferencePortableObject(parent, ownerId, id, options) {
+	if (!isPortableMode(parent, options)) return false;
+	if (isCompatibleEf61Iri(id)) return true;
+	if (!isPortableIri(id)) return false;
+	return ownerId == null || !isPortableIri(ownerId) || !haveSameFe34Origin(ownerId, id);
+}
+const PORTABLE_IRI_PATTERN = /^ap(?:\+ef61)?:/i;
+/**
+* Finds out whether a document fetched as an ordinary HTTP(S) document
+* claims to be a portable object: its final URL is a portable IRI or an
+* FEP-ef61 compatible identifier, or else its `@id` is.  The final URL takes
+* precedence, so a document whose `@id` claims another object fails the
+* identity check against the final URL.
+*
+* @param documentUrl The final URL of the document.
+* @param objectId The `@id` of the parsed document.
+* @returns `undefined` if the document does not claim to be a portable
+*          object; `null` if the claim is malformed; otherwise, the claim.
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+function getPortableResponseClaim(documentUrl, objectId) {
+	if (PORTABLE_IRI_PATTERN.test(documentUrl)) {
+		let id;
+		try {
+			id = parseIri(documentUrl);
+			if (canonicalizePortableUri(documentUrl) !== canonicalizePortableUri(formatIri(id))) return null;
+		} catch (error) {
+			if (error instanceof TypeError) return null;
+			throw error;
+		}
+		return {
+			id,
+			inferredGateways: getPortableGatewayCandidates(id)
+		};
+	}
+	for (const url of [documentUrl, objectId]) {
+		if (url == null) continue;
+		const compatible = parseCompatibleEf61Reference(url);
+		if (compatible === null) return null;
+		if (compatible != null) return {
+			id: compatible.id,
+			inferredGateways: [compatible.gateway]
+		};
+		if (url instanceof URL && isPortableIri(url)) return {
+			id: url,
+			inferredGateways: getPortableGatewayCandidates(url)
+		};
+	}
+}
+const unverifiedPortableClaims = /* @__PURE__ */ new WeakSet();
+/**
+* Records that an object fetched as an ordinary HTTP(S) object stands for
+* a portable object if its reference, its final URL, or its `@id` is
+* a portable IRI or an FEP-ef61 compatible identifier.  Accessors do not
+* cache such objects in their parents, so that a later call with the
+* `verifyPortableObject` option dereferences and verifies them.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+function markUnverifiedPortableClaim(object, reference, documentUrl) {
+	const objectId = getObjectId(object);
+	if (isPortableIri(reference) || isCompatibleEf61Iri(reference) || PORTABLE_IRI_PATTERN.test(documentUrl) || isCompatibleEf61Iri(documentUrl) || objectId != null && (isPortableIri(objectId) || isCompatibleEf61Iri(objectId))) unverifiedPortableClaims.add(object);
+}
+/**
+* Checks whether an object was fetched as an ordinary HTTP(S) object although
+* it stands for a portable object.  See {@link markUnverifiedPortableClaim}.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+function isUnverifiedPortableClaim(object) {
+	return unverifiedPortableClaims.has(object);
+}
+/**
+* Rejects a malformed FEP-ef61 compatible identifier found in a reference,
+* the final URL of a fetched document, or its `@id`, when it would be
+* dereferenced as a portable object.  It is rejected without a request (or
+* without returning the fetched document), since it cannot be verified as
+* a portable object, and fetching it as an ordinary HTTP(S) object would
+* skip the portable object policy.
+*
+* @param url The rejected URL, for the log message.
+* @param options The options of the accessor.
+* @returns Always `null`.
+* @throws {Error} If `crossOrigin` is `"throw"` and `suppressError` is not
+*                 set.
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+function rejectMalformedCompatibleReference(url, options) {
+	const message = "Refusing to dereference {url}, because it is a malformed FEP-ef61 compatible identifier, which cannot be verified as a portable object.";
+	if (options.crossOrigin === "throw" && !options.suppressError) throw new PortableObjectRejectedError(message.replace("{url}", url));
+	logger.warn(message, { url });
+	return null;
+}
+/**
+* Logs that an embedded object without `@id` in an object accepted without
+* an integrity proof is dropped, because it cannot be dereferenced and
+* verified on its own.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+function warnUnverifiableEmbeddedObject(parent, property) {
+	logger.warn("Dropping an embedded object without @id in the {property} property of {parentId}, because the parent was accepted without an integrity proof and the embedded object cannot be verified on its own.", {
+		property,
+		parentId: getObjectId(parent)?.href ?? null
+	});
+}
+function buildReferrerChain(link, depth = 0) {
+	if (link == null) return void 0;
+	const provenance = provenances.get(link.object);
+	const base = {
+		object: link.object,
+		id: getObjectId(link.object),
+		property: link.property,
+		...provenance?.acceptance == null ? {} : { acceptance: provenance.acceptance },
+		...provenance?.collectionContext === void 0 ? {} : { collectionContext: provenance.collectionContext }
+	};
+	if (provenance?.referrer == null) return base;
+	if (depth + 1 >= MAX_REFERRER_CHAIN_LENGTH) return {
+		...base,
+		truncated: true
+	};
+	return {
+		...base,
+		referrer: buildReferrerChain(provenance.referrer, depth + 1)
+	};
+}
+/**
+* Checks whether a URL is an FEP-ef61 portable ActivityPub IRI.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+function isPortableIri(url) {
+	return url.protocol === "ap+ef61:" || url.protocol === "ap:";
+}
+/**
+* Picks the ordered list of FEP-ef61 gateways to fetch a portable IRI from.
+*
+* If `gateways` is given, it is used as is (even when empty), and `@gateway`
+* location hints in the IRI are ignored.  Otherwise, up to
+* {@link MAX_GATEWAY_HINTS} valid `@gateway` hints are used.  Duplicate
+* gateways are dropped in both cases.
+*
+* @throws {TypeError} If an explicit gateway is not an HTTP(S) origin.
+* @internal
+*/
+function getPortableGatewayCandidates(url, gateways) {
+	const candidates = [];
+	const seen = /* @__PURE__ */ new Set();
+	const add = (gateway) => {
+		if (seen.has(gateway.href)) return;
+		seen.add(gateway.href);
+		candidates.push(gateway);
+	};
+	if (gateways != null) {
+		for (const gateway of gateways) {
+			const parsed = parseGatewayOrigin(gateway);
+			if (parsed == null) throw new TypeError("FEP-ef61 gateways must be HTTP(S) origins with no credentials, path, query, or fragment: " + String(gateway));
+			add(parsed);
+		}
+		return candidates;
+	}
+	for (const hint of new URLSearchParams(url.search).getAll(GATEWAY_HINT_PARAMETER)) {
+		if (candidates.length >= MAX_GATEWAY_HINTS) break;
+		const parsed = parseGatewayOrigin(hint);
+		if (parsed == null) {
+			logger.debug("Ignoring an invalid FEP-ef61 gateway hint {hint} in {url}.", {
+				hint,
+				url: formatIri(url)
+			});
+			continue;
+		}
+		add(parsed);
+	}
+	return candidates;
+}
+/**
+* Gets the gateways through which a portable reference without location hints
+* can be dereferenced, from the portable actor that the reference belongs to.
+*
+* The references in a portable actor's own document, such as its `outbox`,
+* usually have no `@gateway` hints, as they are not needed there, since
+* the actor's `gateways` already tells where to retrieve them.  So this walks
+* from the object whose property is being dereferenced up through the objects
+* it was obtained from, e.g., from a collection page to the collection and
+* then to the actor, and returns the `gateways` of the first object that has
+* any, but only if that object has the same DID as the reference.  The
+* gateways only tell where to look; whatever they serve is still verified.
+*
+* @param object The object whose property is being dereferenced.
+* @param url The portable IRI to dereference.
+* @returns Up to {@link MAX_GATEWAY_HINTS} valid gateways, or `undefined` if
+*          the IRI has valid `@gateway` hints or no such object is found.
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+function getReferrerGateways(object, url) {
+	if (getPortableGatewayCandidates(url).length > 0) return void 0;
+	const visited = /* @__PURE__ */ new Set();
+	let current = object;
+	while (current != null && !visited.has(current)) {
+		visited.add(current);
+		const gateways = "gateways" in current ? current.gateways : void 0;
+		if (Array.isArray(gateways) && gateways.length > 0) {
+			const id = getObjectId(current);
+			const portableId = id == null ? null : isPortableIri(id) ? id : getCompatibleEf61Target(id);
+			if (portableId == null || !haveSameFe34Origin(portableId, url)) return;
+			const candidates = [];
+			for (const gateway of gateways) {
+				if (candidates.length >= MAX_GATEWAY_HINTS) break;
+				if (typeof gateway !== "string" && !(gateway instanceof URL)) continue;
+				const parsed = parseGatewayOrigin(gateway);
+				if (parsed == null) continue;
+				if (candidates.some((c) => c.href === parsed.href)) continue;
+				candidates.push(parsed);
+			}
+			return candidates.length > 0 ? candidates : void 0;
+		}
+		current = provenances.get(current)?.referrer?.object;
+	}
+}
+function getCompatibleEf61Target(id) {
+	try {
+		return fromCompatibleEf61Id(id);
+	} catch {
+		return null;
+	}
+}
+/**
+* Creates a context loader that returns the same context documents for the
+* whole dereference operation, so that the identity check, the proof
+* verifier, and the parser interpret the fetched document identically even
+* if the underlying loader is nondeterministic.  Failed loads are not
+* remembered, so a transient failure does not affect the next gateway.
+*
+* The parsed object keeps the loader for its own later dereferences, so
+* `release()` turns it into a plain pass-through to the underlying loader
+* once the operation is over.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+function createSnapshotContextLoader(contextLoader, suppressError) {
+	contextLoader = unwrapReleasedDocumentLoader(contextLoader);
+	const cache = /* @__PURE__ */ new Map();
+	let released = false;
+	const release = () => {
+		released = true;
+		state.released = true;
+		cache.clear();
+	};
+	const loader = async (url, options) => {
+		if (released) return await contextLoader(url, options);
+		const key = URL.canParse(url) ? new URL(url).href : url;
+		if (BASELINE_CONTEXT_URLS.has(key)) return {
+			contextUrl: null,
+			document: structuredClone(preloadedContexts[key]),
+			documentUrl: key
+		};
+		let promise = cache.get(key);
+		if (promise == null) {
+			const loading = contextLoader(url, suppressError ? {
+				...options,
+				suppressError: true
+			} : options).then((document) => structuredClone(document));
+			promise = loading;
+			cache.set(key, loading);
+			loading.catch(() => {
+				if (cache.get(key) === loading) cache.delete(key);
+			});
+		}
+		return structuredClone(await promise);
+	};
+	const state = {
+		base: contextLoader,
+		released: false
+	};
+	registerDocumentLoaderWrapper(loader, state);
+	return {
+		loader,
+		release
+	};
+}
+/**
+* The error thrown by {@link dereferencePortableIri} under
+* `crossOrigin: "throw"` when gateways returned objects but none of them
+* satisfied the identity and proof checks.
+*
+* @internal Not part of the public API contract.
+*/
+var PortableObjectRejectedError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "PortableObjectRejectedError";
+	}
+};
+var PortableObjectRejection = class {
+	message;
+	values;
+	constructor(message, values = {}) {
+		this.message = message;
+		this.values = values;
+	}
+};
+/**
+* Dereferences an FEP-ef61 portable IRI through its gateways.
+*
+* Gateways are tried one by one until one of them returns a single-node
+* document whose `@id`, if any, canonically matches the requested IRI and
+* which passes `verifyPortableObject`.  When there is no gateway to try, the
+* document loader is asked for the portable IRI itself, and its result is
+* validated the same way.  If the `response` option is given, only that
+* document is validated, and nothing is fetched.
+*
+* @returns The parsed object, or `null` if no valid object was retrieved and
+*          `suppressError` is set or the failure was a rejected object
+*          (unless `crossOrigin` is `"throw"`).
+* @throws {TypeError} If `gateways` has an invalid entry (always), if no
+*                     verifier is given, or if the IRI cannot be turned into
+*                     a gateway URL (unless `suppressError` is set).
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+async function dereferencePortableIri(url, options) {
+	url = parseIri(url);
+	const lookupUrl = formatIri(url);
+	const { span } = options;
+	const explicitGateways = options.gateways == null ? void 0 : getPortableGatewayCandidates(url, options.gateways);
+	const inferredGateways = options.inferredGateways ?? (explicitGateways == null ? getPortableGatewayCandidates(url) : []);
+	const gateways = [...inferredGateways];
+	for (const gateway of explicitGateways ?? []) if (!gateways.some((g) => g.href === gateway.href)) gateways.push(gateway);
+	const fail = (error) => {
+		span?.setStatus({
+			code: SpanStatusCode.ERROR,
+			message: String(error)
+		});
+		if (options.suppressError) {
+			logger.warn("Failed to dereference {url}: {error}", {
+				url: lookupUrl,
+				error
+			});
+			return null;
+		}
+		throw error;
+	};
+	const verify = options.verifyPortableObject;
+	if (verify == null) return fail(/* @__PURE__ */ new TypeError("Dereferencing the portable object " + lookupUrl + " requires the verifyPortableObject option, e.g., verifyPortableObject() from @fedify/fedify.  Passing a Fedify Context as the options gives it, and objects parsed with the option use it by default."));
+	const requestUrls = [];
+	let expectedId;
+	try {
+		expectedId = canonicalizePortableUri(lookupUrl);
+		if (options.response != null) requestUrls.push({
+			url: options.response.documentUrl,
+			gateway: null,
+			response: options.response
+		});
+		else for (const gateway of gateways) requestUrls.push({
+			url: toCompatibleEf61Id(url, gateway).href,
+			gateway
+		});
+	} catch (error) {
+		return fail(error);
+	}
+	if (requestUrls.length < 1) requestUrls.push({
+		url: lookupUrl,
+		gateway: null
+	});
+	const snapshot = createSnapshotContextLoader(options.contextLoader, options.suppressError);
+	const contextLoader = snapshot.loader;
+	const scopedDocument = createScopedContextLoader(options.documentLoader, options.suppressError);
+	const attempts = [];
+	const { signal } = options;
+	const gatewayHints = explicitGateways == null && inferredGateways.length > 0 ? inferredGateways : void 0;
+	const referrer = buildReferrerChain(options.referrer);
+	try {
+		for (const { url: requestUrl, gateway, response } of requestUrls) {
+			signal?.throwIfAborted();
+			let remoteDocument;
+			try {
+				remoteDocument = response ?? await options.documentLoader(requestUrl, {
+					signal,
+					suppressError: options.suppressError
+				});
+			} catch (error) {
+				signal?.throwIfAborted();
+				logger.debug("Failed to fetch {url} from {requestUrl}: {error}", {
+					url: lookupUrl,
+					requestUrl,
+					error
+				});
+				attempts.push({
+					type: "error",
+					error
+				});
+				continue;
+			}
+			const { document } = remoteDocument;
+			try {
+				await checkPortableObjectId(document, expectedId, contextLoader);
+				let documentUrl;
+				try {
+					documentUrl = parseIri(remoteDocument.documentUrl);
+				} catch {
+					documentUrl = void 0;
+				}
+				let result;
+				try {
+					result = await verify(document, {
+						documentLoader: scopedDocument.loader,
+						contextLoader,
+						tracerProvider: options.tracerProvider,
+						...documentUrl == null ? {} : { documentUrl },
+						...explicitGateways == null ? {} : { gateways: explicitGateways },
+						...gatewayHints == null ? {} : { gatewayHints },
+						...referrer == null ? {} : { referrer }
+					});
+				} catch (error) {
+					throw new PortableObjectRejection("the proof verifier failed: {error}", { error });
+				}
+				if (!result.verified) throw new PortableObjectRejection("it does not satisfy the FEP-ef61 proof policy: {result}", { result });
+				const object = await options.parse(document, {
+					contextLoader,
+					baseUrl: url
+				});
+				signal?.throwIfAborted();
+				if (object != null && typeof object === "object") provenances.set(object, {
+					acceptance: result.unsecured === true ? "unsecured" : "verified",
+					...result.collectionContext === void 0 ? {} : { collectionContext: result.collectionContext },
+					...options.referrer == null ? {} : { referrer: options.referrer }
+				});
+				if (gateway != null) span?.setAttribute("activitypub.gateway", gateway.href);
+				return object;
+			} catch (error) {
+				signal?.throwIfAborted();
+				if (error instanceof PortableObjectRejection) {
+					logger.warn("Rejected the portable object {url} served from {requestUrl}, because " + error.message, {
+						...error.values,
+						url: lookupUrl,
+						requestUrl
+					});
+					attempts.push({
+						type: "rejected",
+						source: requestUrl
+					});
+					continue;
+				}
+				logger.debug("Failed to parse {url} from {requestUrl}: {error}", {
+					url: lookupUrl,
+					requestUrl,
+					error
+				});
+				attempts.push({
+					type: "error",
+					error
+				});
+			}
+		}
+	} finally {
+		scopedDocument.release();
+		snapshot.release();
+	}
+	const rejected = attempts.filter((a) => a.type === "rejected");
+	if (rejected.length > 0) {
+		const message = "No gateway returned a valid portable object for " + lookupUrl + "; refusing to return the object.  Objects retrieved from: " + rejected.map((a) => a.source).join(", ") + ".";
+		if (options.suppressError || options.crossOrigin !== "throw") {
+			span?.setStatus({
+				code: SpanStatusCode.ERROR,
+				message
+			});
+			logger.warn(message);
+			return null;
+		}
+		throw new PortableObjectRejectedError(message);
+	}
+	const errors = attempts.flatMap((a) => a.type === "error" ? [a.error] : []);
+	return fail(errors.length === 1 ? errors[0] : new AggregateError(errors, "Failed to dereference " + lookupUrl + " through any of its gateways: " + requestUrls.map((r) => r.url).join(", ")));
+}
+async function checkPortableObjectId(document, expectedId, contextLoader) {
+	if (document == null || typeof document !== "object" || Array.isArray(document)) throw new PortableObjectRejection("it is not a single JSON object");
+	const expanded = await jsonld_default.expand(document, {
+		documentLoader: contextLoader,
+		keepFreeFloatingNodes: true
+	});
+	if (expanded.length !== 1) throw new PortableObjectRejection("it does not have exactly one top-level node");
+	const id = expanded[0]["@id"];
+	if (id == null) return;
+	if (typeof id !== "string") throw new PortableObjectRejection("it has an invalid @id");
+	let actualId;
+	try {
+		const portable = fromCompatibleEf61Id(id);
+		actualId = canonicalizePortableUri(portable == null ? id : formatIri(portable));
+	} catch (error) {
+		if (!(error instanceof TypeError)) throw error;
+		actualId = null;
+	}
+	if (actualId !== expectedId) throw new PortableObjectRejection("its @id ({objectId}) does not match the requested portable ID", { objectId: id });
+}
+//#endregion
+export { PortableObjectRejectedError, copyPortableProvenance, createSnapshotContextLoader, dereferencePortableIri, getPortableGatewayCandidates, getPortableResponseClaim, getReferrerGateways, isCompatibleEf61Iri, isInPortableChain, isPortableIri, isPortableMode, isUnsecuredPortableObject, isUnverifiedPortableClaim, markUnverifiedPortableClaim, mustDereferencePortableObject, parseCompatibleEf61Reference, recordPortableReferrer, rejectMalformedCompatibleReference, warnUnverifiableEmbeddedObject };