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

package/deno.json

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

package/dist/internal/portable-dereference.cjs

@@ -25,6 +25,156 @@ 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" } : {}
+	});
+}
+/**
+* Rejects a reference from a portable object that would be dereferenced as
+* an ordinary HTTP(S) object although it stands for a portable object, i.e.,
+* an FEP-ef61 compatible identifier, or a document whose final URL or `@id`
+* is a compatible identifier or a portable IRI.  Such a document would skip
+* the portable object policy, so it is rejected regardless of the
+* `crossOrigin` option, except that `crossOrigin: "throw"` makes it throw.
+*
+* @param url The rejected URL, for the log message.
+* @param crossOrigin The `crossOrigin` option of the accessor.
+* @returns Always `null`.
+* @throws {Error} If `crossOrigin` is `"throw"`.
+* @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 rejectPortableChainReference(url, crossOrigin) {
+	const message = "Refusing to dereference {url} from a portable object as an ordinary HTTP(S) object, because it stands for an FEP-ef61 portable object that is not verified this way.";
+	if (crossOrigin === "throw") throw new Error(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
@@ -205,6 +355,9 @@ async function dereferencePortableIri(url, options) {
 	const contextLoader = snapshot.loader;
 	const attempts = [];
 	const { signal } = options;
+	const explicitGateways = options.gateways == null ? void 0 : gateways;
+	const gatewayHints = options.gateways == null && gateways.length > 0 ? gateways : void 0;
+	const referrer = buildReferrerChain(options.referrer);
 	try {
 		for (const { url: requestUrl, gateway } of requestUrls) {
 			signal?.throwIfAborted();
@@ -227,12 +380,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 +406,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 +478,13 @@ async function checkPortableObjectId(document, expectedId, contextLoader) {
 }
 //#endregion
 exports.PortableObjectRejectedError = PortableObjectRejectedError;
+exports.copyPortableProvenance = copyPortableProvenance;
 exports.dereferencePortableIri = dereferencePortableIri;
 exports.getPortableGatewayCandidates = getPortableGatewayCandidates;
+exports.isCompatibleEf61Iri = isCompatibleEf61Iri;
+exports.isInPortableChain = isInPortableChain;
 exports.isPortableIri = isPortableIri;
+exports.isUnsecuredPortableObject = isUnsecuredPortableObject;
+exports.recordPortableReferrer = recordPortableReferrer;
+exports.rejectPortableChainReference = rejectPortableChainReference;
+exports.warnUnverifiableEmbeddedObject = warnUnverifiableEmbeddedObject;

package/dist/internal/portable-dereference.d.cts

@@ -1,10 +1,101 @@
 /// <reference lib="esnext.temporal" />
 import { n as DocumentLoader } from "../docloader-Dr8wEkif.cjs";
-import { t as PortableObjectVerifier } from "../portable-DxF2Ut-Z.cjs";
+import { r as PortableObjectVerifier } from "../portable-BykOD45s.cjs";
 import { Span, TracerProvider } from "@opentelemetry/api";
 
 //#region src/internal/portable-dereference.d.ts
 /**
+* A reference from a vocabulary object's property, which generated
+* accessors pass to {@link dereferencePortableIri}.
+*
+* @internal
+*/
+interface PortableReferrerLink {
+  readonly object: object;
+  readonly property: string;
+}
+/**
+* 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.
+*/
+declare function isInPortableChain(object: object): boolean;
+/**
+* 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.
+*/
+declare function isUnsecuredPortableObject(object: object): boolean;
+/**
+* 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.
+*/
+declare function isCompatibleEf61Iri(url: URL | string): boolean;
+/**
+* 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.
+*/
+declare function recordPortableReferrer(parent: object, child: unknown, property: string): void;
+/**
+* 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.
+*/
+declare function copyPortableProvenance(from: object, to: object): void;
+/**
+* Rejects a reference from a portable object that would be dereferenced as
+* an ordinary HTTP(S) object although it stands for a portable object, i.e.,
+* an FEP-ef61 compatible identifier, or a document whose final URL or `@id`
+* is a compatible identifier or a portable IRI.  Such a document would skip
+* the portable object policy, so it is rejected regardless of the
+* `crossOrigin` option, except that `crossOrigin: "throw"` makes it throw.
+*
+* @param url The rejected URL, for the log message.
+* @param crossOrigin The `crossOrigin` option of the accessor.
+* @returns Always `null`.
+* @throws {Error} If `crossOrigin` is `"throw"`.
+* @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.
+*/
+declare function rejectPortableChainReference(url: string, crossOrigin: "ignore" | "throw" | "trust" | undefined): 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.
+*/
+declare function warnUnverifiableEmbeddedObject(parent: object, property: string): void;
+/**
 * Checks whether a URL is an FEP-ef61 portable ActivityPub IRI.
 *
 * @internal Technically exported for generated vocabulary classes, but not
@@ -37,6 +128,7 @@ interface DereferencePortableIriOptions<T> {
   tracerProvider: TracerProvider;
   gateways?: readonly (string | URL)[];
   verifyPortableObject?: PortableObjectVerifier;
+  referrer?: PortableReferrerLink;
   suppressError?: boolean;
   crossOrigin?: "ignore" | "throw" | "trust";
   /**
@@ -84,4 +176,4 @@ declare function dereferencePortableIri<T extends {
   id: URL | null;
 }>(url: URL, options: DereferencePortableIriOptions<T>): Promise<T | null>;
 //#endregion
-export { DereferencePortableIriOptions, PortableObjectRejectedError, dereferencePortableIri, getPortableGatewayCandidates, isPortableIri };
+export { DereferencePortableIriOptions, PortableObjectRejectedError, PortableReferrerLink, copyPortableProvenance, dereferencePortableIri, getPortableGatewayCandidates, isCompatibleEf61Iri, isInPortableChain, isPortableIri, isUnsecuredPortableObject, recordPortableReferrer, rejectPortableChainReference, warnUnverifiableEmbeddedObject };

package/dist/internal/portable-dereference.d.ts

@@ -1,10 +1,101 @@
 /// <reference lib="esnext.temporal" />
 import { n as DocumentLoader } from "../docloader-Dr8wEkif.js";
-import { t as PortableObjectVerifier } from "../portable-CduElToy.js";
+import { r as PortableObjectVerifier } from "../portable--NcyA1R_.js";
 import { Span, TracerProvider } from "@opentelemetry/api";
 
 //#region src/internal/portable-dereference.d.ts
 /**
+* A reference from a vocabulary object's property, which generated
+* accessors pass to {@link dereferencePortableIri}.
+*
+* @internal
+*/
+interface PortableReferrerLink {
+  readonly object: object;
+  readonly property: string;
+}
+/**
+* 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.
+*/
+declare function isInPortableChain(object: object): boolean;
+/**
+* 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.
+*/
+declare function isUnsecuredPortableObject(object: object): boolean;
+/**
+* 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.
+*/
+declare function isCompatibleEf61Iri(url: URL | string): boolean;
+/**
+* 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.
+*/
+declare function recordPortableReferrer(parent: object, child: unknown, property: string): void;
+/**
+* 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.
+*/
+declare function copyPortableProvenance(from: object, to: object): void;
+/**
+* Rejects a reference from a portable object that would be dereferenced as
+* an ordinary HTTP(S) object although it stands for a portable object, i.e.,
+* an FEP-ef61 compatible identifier, or a document whose final URL or `@id`
+* is a compatible identifier or a portable IRI.  Such a document would skip
+* the portable object policy, so it is rejected regardless of the
+* `crossOrigin` option, except that `crossOrigin: "throw"` makes it throw.
+*
+* @param url The rejected URL, for the log message.
+* @param crossOrigin The `crossOrigin` option of the accessor.
+* @returns Always `null`.
+* @throws {Error} If `crossOrigin` is `"throw"`.
+* @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.
+*/
+declare function rejectPortableChainReference(url: string, crossOrigin: "ignore" | "throw" | "trust" | undefined): 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.
+*/
+declare function warnUnverifiableEmbeddedObject(parent: object, property: string): void;
+/**
 * Checks whether a URL is an FEP-ef61 portable ActivityPub IRI.
 *
 * @internal Technically exported for generated vocabulary classes, but not
@@ -37,6 +128,7 @@ interface DereferencePortableIriOptions<T> {
   tracerProvider: TracerProvider;
   gateways?: readonly (string | URL)[];
   verifyPortableObject?: PortableObjectVerifier;
+  referrer?: PortableReferrerLink;
   suppressError?: boolean;
   crossOrigin?: "ignore" | "throw" | "trust";
   /**
@@ -84,4 +176,4 @@ declare function dereferencePortableIri<T extends {
   id: URL | null;
 }>(url: URL, options: DereferencePortableIriOptions<T>): Promise<T | null>;
 //#endregion
-export { DereferencePortableIriOptions, PortableObjectRejectedError, dereferencePortableIri, getPortableGatewayCandidates, isPortableIri };
+export { DereferencePortableIriOptions, PortableObjectRejectedError, PortableReferrerLink, copyPortableProvenance, dereferencePortableIri, getPortableGatewayCandidates, isCompatibleEf61Iri, isInPortableChain, isPortableIri, isUnsecuredPortableObject, recordPortableReferrer, rejectPortableChainReference, warnUnverifiableEmbeddedObject };

package/dist/internal/portable-dereference.js

@@ -1,6 +1,6 @@
 
 import { t as preloadedContexts } from "../contexts-DoZUIW7y.js";
-import { a as formatIri, g as toCompatibleEf61Id, m as parseIri, r as canonicalizePortableUri } from "../url-CEhi4hb4.js";
+import { a as formatIri, g as toCompatibleEf61Id, m as parseIri, o as fromCompatibleEf61Id, r as canonicalizePortableUri } from "../url-CEhi4hb4.js";
 import jsonld_default from "../jsonld.js";
 import { getLogger } from "@logtape/logtape";
 import { SpanStatusCode } from "@opentelemetry/api";
@@ -24,6 +24,156 @@ 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 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" } : {}
+	});
+}
+/**
+* Rejects a reference from a portable object that would be dereferenced as
+* an ordinary HTTP(S) object although it stands for a portable object, i.e.,
+* an FEP-ef61 compatible identifier, or a document whose final URL or `@id`
+* is a compatible identifier or a portable IRI.  Such a document would skip
+* the portable object policy, so it is rejected regardless of the
+* `crossOrigin` option, except that `crossOrigin: "throw"` makes it throw.
+*
+* @param url The rejected URL, for the log message.
+* @param crossOrigin The `crossOrigin` option of the accessor.
+* @returns Always `null`.
+* @throws {Error} If `crossOrigin` is `"throw"`.
+* @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 rejectPortableChainReference(url, crossOrigin) {
+	const message = "Refusing to dereference {url} from a portable object as an ordinary HTTP(S) object, because it stands for an FEP-ef61 portable object that is not verified this way.";
+	if (crossOrigin === "throw") throw new Error(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
@@ -204,6 +354,9 @@ async function dereferencePortableIri(url, options) {
 	const contextLoader = snapshot.loader;
 	const attempts = [];
 	const { signal } = options;
+	const explicitGateways = options.gateways == null ? void 0 : gateways;
+	const gatewayHints = options.gateways == null && gateways.length > 0 ? gateways : void 0;
+	const referrer = buildReferrerChain(options.referrer);
 	try {
 		for (const { url: requestUrl, gateway } of requestUrls) {
 			signal?.throwIfAborted();
@@ -226,12 +379,22 @@ async function dereferencePortableIri(url, options) {
 			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: 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 });
@@ -242,6 +405,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) {
@@ -308,4 +476,4 @@ async function checkPortableObjectId(document, expectedId, contextLoader) {
 	if (actualId !== expectedId) throw new PortableObjectRejection("its @id ({objectId}) does not match the requested portable ID", { objectId: id });
 }
 //#endregion
-export { PortableObjectRejectedError, dereferencePortableIri, getPortableGatewayCandidates, isPortableIri };
+export { PortableObjectRejectedError, copyPortableProvenance, dereferencePortableIri, getPortableGatewayCandidates, isCompatibleEf61Iri, isInPortableChain, isPortableIri, isUnsecuredPortableObject, recordPortableReferrer, rejectPortableChainReference, warnUnverifiableEmbeddedObject };

package/dist/mod.cjs

@@ -16,7 +16,7 @@ let _multiformats_base_x = require("@multiformats/base-x");
 _multiformats_base_x = require_rolldown_runtime.__toESM(_multiformats_base_x, 1);
 //#region deno.json
 var name = "@fedify/vocab-runtime";
-var version = "2.4.0-dev.2056+e6394f3b";
+var version = "2.4.0-dev.2063+366c0362";
 //#endregion
 //#region src/request.ts
 /**