@fedify/vocab-runtime 2.4.0-dev.2056 → 2.4.0-dev.2065

package/deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/vocab-runtime",
-  "version": "2.4.0-dev.2056+e6394f3b",
+  "version": "2.4.0-dev.2065+b09fdd33",
   "license": "MIT",
   "exports": {
     ".": "./src/mod.ts",

package/dist/internal/portable-dereference.cjs

@@ -25,6 +25,301 @@ const BASELINE_CONTEXT_URLS = /* @__PURE__ */ new Set([
 	"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 or was obtained from a portable object.
+*
+* @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);
+}
+/**
+* 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 require_url.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) {
+	if (typeof url === "string") {
+		if (!URL.canParse(url)) return void 0;
+		url = new URL(url);
+	}
+	try {
+		const id = require_url.fromCompatibleEf61Id(url);
+		if (id == null) return void 0;
+		return {
+			id,
+			gateway: new URL(url.origin)
+		};
+	} catch (error) {
+		if (error instanceof TypeError) {
+			logger.debug("Invalid FEP-ef61 compatible identifier {url}: {error}", {
+				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) || !require_url.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 = require_url.parseIri(documentUrl);
+			if (require_url.canonicalizePortableUri(documentUrl) !== require_url.canonicalizePortableUri(require_url.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
@@ -93,12 +388,18 @@ function parseGatewayOrigin(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) {
+	for (let wrapped = snapshotLoaders.get(contextLoader); wrapped?.released; wrapped = snapshotLoaders.get(contextLoader)) contextLoader = wrapped.base;
 	const cache = /* @__PURE__ */ new Map();
 	let released = false;
 	const release = () => {
 		released = true;
+		state.released = true;
 		cache.clear();
 	};
 	const loader = async (url, options) => {
@@ -120,11 +421,17 @@ function createSnapshotContextLoader(contextLoader) {
 		}
 		return structuredClone(await promise);
 	};
+	const state = {
+		base: contextLoader,
+		released: false
+	};
+	snapshotLoaders.set(loader, state);
 	return {
 		loader,
 		release
 	};
 }
+const snapshotLoaders = /* @__PURE__ */ new WeakMap();
 /**
 * The error thrown by {@link dereferencePortableIri} under
 * `crossOrigin: "throw"` when gateways returned objects but none of them
@@ -151,9 +458,10 @@ var PortableObjectRejection = class {
 *
 * 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.
+* 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
@@ -169,7 +477,10 @@ async function dereferencePortableIri(url, options) {
 	url = require_url.parseIri(url);
 	const lookupUrl = require_url.formatIri(url);
 	const { span } = options;
-	const gateways = getPortableGatewayCandidates(url, options.gateways);
+	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: _opentelemetry_api.SpanStatusCode.ERROR,
@@ -190,7 +501,12 @@ async function dereferencePortableIri(url, options) {
 	let expectedId;
 	try {
 		expectedId = require_url.canonicalizePortableUri(lookupUrl);
-		for (const gateway of gateways) requestUrls.push({
+		if (options.response != null) requestUrls.push({
+			url: options.response.documentUrl,
+			gateway: null,
+			response: options.response
+		});
+		else for (const gateway of gateways) requestUrls.push({
 			url: require_url.toCompatibleEf61Id(url, gateway).href,
 			gateway
 		});
@@ -205,12 +521,14 @@ async function dereferencePortableIri(url, options) {
 	const contextLoader = snapshot.loader;
 	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 } of requestUrls) {
+		for (const { url: requestUrl, gateway, response } of requestUrls) {
 			signal?.throwIfAborted();
 			let remoteDocument;
 			try {
-				remoteDocument = await options.documentLoader(requestUrl, signal == null ? void 0 : { signal });
+				remoteDocument = response ?? await options.documentLoader(requestUrl, signal == null ? void 0 : { signal });
 			} catch (error) {
 				signal?.throwIfAborted();
 				logger.debug("Failed to fetch {url} from {requestUrl}: {error}", {
@@ -227,12 +545,22 @@ async function dereferencePortableIri(url, options) {
 			const { document } = remoteDocument;
 			try {
 				await checkPortableObjectId(document, expectedId, contextLoader);
+				let documentUrl;
+				try {
+					documentUrl = require_url.parseIri(remoteDocument.documentUrl);
+				} catch {
+					documentUrl = void 0;
+				}
 				let result;
 				try {
 					result = await verify(document, {
 						documentLoader: options.documentLoader,
 						contextLoader,
-						tracerProvider: options.tracerProvider
+						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 });
@@ -243,6 +571,11 @@ async function dereferencePortableIri(url, options) {
 					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) {
@@ -310,6 +643,20 @@ async function checkPortableObjectId(document, expectedId, contextLoader) {
 }
 //#endregion
 exports.PortableObjectRejectedError = PortableObjectRejectedError;
+exports.copyPortableProvenance = copyPortableProvenance;
+exports.createSnapshotContextLoader = createSnapshotContextLoader;
 exports.dereferencePortableIri = dereferencePortableIri;
 exports.getPortableGatewayCandidates = getPortableGatewayCandidates;
+exports.getPortableResponseClaim = getPortableResponseClaim;
+exports.isCompatibleEf61Iri = isCompatibleEf61Iri;
+exports.isInPortableChain = isInPortableChain;
 exports.isPortableIri = isPortableIri;
+exports.isPortableMode = isPortableMode;
+exports.isUnsecuredPortableObject = isUnsecuredPortableObject;
+exports.isUnverifiedPortableClaim = isUnverifiedPortableClaim;
+exports.markUnverifiedPortableClaim = markUnverifiedPortableClaim;
+exports.mustDereferencePortableObject = mustDereferencePortableObject;
+exports.parseCompatibleEf61Reference = parseCompatibleEf61Reference;
+exports.recordPortableReferrer = recordPortableReferrer;
+exports.rejectMalformedCompatibleReference = rejectMalformedCompatibleReference;
+exports.warnUnverifiableEmbeddedObject = warnUnverifiableEmbeddedObject;