@fedify/vocab-runtime 2.4.0-dev.2030 → 2.4.0-dev.2047

package/dist/internal/portable-dereference.js

@@ -0,0 +1,311 @@
+
+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 jsonld_default from "../jsonld.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 LOCATION_HINT_PARAMETER = "@gateway";
+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"
+]);
+/**
+* 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(LOCATION_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;
+}
+function parseGatewayOrigin(gateway) {
+	let url;
+	if (gateway instanceof URL) url = new URL(gateway.href);
+	else if (typeof gateway === "string" && URL.canParse(gateway)) url = new URL(gateway);
+	else return null;
+	if (url.protocol !== "http:" && url.protocol !== "https:" || url.href !== `${url.origin}/`) return null;
+	return url;
+}
+/**
+* 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.
+*/
+function createSnapshotContextLoader(contextLoader) {
+	const cache = /* @__PURE__ */ new Map();
+	let released = false;
+	const release = () => {
+		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, 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);
+	};
+	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.
+*
+* @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 gateways = getPortableGatewayCandidates(url, options.gateways);
+	const fail = (error) => {
+		span?.setStatus({
+			code: SpanStatusCode.ERROR,
+			message: String(error)
+		});
+		if (options.suppressError) {
+			logger.error("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., verifyPortableObjectProof() from @fedify/fedify."));
+	const requestUrls = [];
+	let expectedId;
+	try {
+		expectedId = canonicalizePortableUri(lookupUrl);
+		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);
+	const contextLoader = snapshot.loader;
+	const attempts = [];
+	const { signal } = options;
+	try {
+		for (const { url: requestUrl, gateway } of requestUrls) {
+			signal?.throwIfAborted();
+			let remoteDocument;
+			try {
+				remoteDocument = await options.documentLoader(requestUrl, signal == null ? void 0 : { signal });
+			} 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 result;
+				try {
+					result = await verify(document, {
+						documentLoader: options.documentLoader,
+						contextLoader,
+						tracerProvider: options.tracerProvider
+					});
+				} 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 (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 {
+		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 {
+		actualId = canonicalizePortableUri(id);
+	} 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, dereferencePortableIri, getPortableGatewayCandidates, isPortableIri };

package/dist/mod.cjs

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_rolldown_runtime = require("./rolldown-runtime-B7lfambq.cjs");
 const require_contexts = require("./contexts-2hEbs3Qk.cjs");
-const require_url = require("./url-i33c0US6.cjs");
+const require_url = require("./url-Cke4irYD.cjs");
 let _logtape_logtape = require("@logtape/logtape");
 let _opentelemetry_api = require("@opentelemetry/api");
 let node_process = require("node:process");
@@ -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.2030+e6b3de3d";
+var version = "2.4.0-dev.2047+140b94db";
 //#endregion
 //#region src/request.ts
 /**
@@ -46,6 +46,12 @@ var FetchError = class extends Error {
 	}
 };
 /**
+* The `Accept` header value for fetching ActivityPub objects.  ActivityPub
+* and FEP-ef61 gateways require the ActivityStreams profile on the JSON-LD
+* media type.
+*/
+const ACTIVITYPUB_ACCEPT = "application/activity+json, application/ld+json; profile=\"https://www.w3.org/ns/activitystreams\"";
+/**
 * Creates a request for the given URL.
 * @param url The URL to create the request for.
 * @param options The options for the request.
@@ -55,7 +61,7 @@ var FetchError = class extends Error {
 function createActivityPubRequest(url, options = {}) {
 	return new Request(url, {
 		headers: {
-			Accept: "application/activity+json, application/ld+json",
+			Accept: ACTIVITYPUB_ACCEPT,
 			"User-Agent": typeof options.userAgent === "string" ? options.userAgent : getUserAgent(options.userAgent)
 		},
 		redirect: "manual"
@@ -1379,6 +1385,7 @@ exports.exportDidKey = exportDidKey;
 exports.exportMultibaseKey = exportMultibaseKey;
 exports.exportSpki = exportSpki;
 exports.formatIri = require_url.formatIri;
+exports.fromCompatibleEf61Id = require_url.fromCompatibleEf61Id;
 exports.getDocumentLoader = getDocumentLoader;
 exports.getFe34Origin = require_url.getFe34Origin;
 exports.getRemoteDocument = getRemoteDocument;
@@ -1403,6 +1410,7 @@ exports.parseHashlink = parseHashlink;
 exports.parseIri = require_url.parseIri;
 exports.parseJsonLdId = require_url.parseJsonLdId;
 exports.preloadedContexts = require_contexts.preloadedContexts;
+exports.toCompatibleEf61Id = require_url.toCompatibleEf61Id;
 exports.validatePublicUrl = require_url.validatePublicUrl;
 exports.verifyDigestMultibase = verifyDigestMultibase;
 exports.verifyHashlink = verifyHashlink;

package/dist/mod.d.cts

@@ -1,5 +1,6 @@
 /// <reference lib="esnext.temporal" />
 import { a as DocumentLoaderOptions, c as getDocumentLoader, d as FetchError, f as GetUserAgentOptions, h as logRequest, i as DocumentLoaderFactoryOptions, l as getRemoteDocument, m as getUserAgent, n as DocumentLoader, o as GetDocumentLoaderOptions, p as createActivityPubRequest, r as DocumentLoaderFactory, s as RemoteDocument, t as AuthenticatedDocumentLoaderFactory, u as CreateRequestOptions } from "./docloader-Dr8wEkif.cjs";
+import { n as PortableObjectVerifierOptions, t as PortableObjectVerifier } from "./portable-DxF2Ut-Z.cjs";
 import { TracerProvider } from "@opentelemetry/api";
 
 //#region src/contexts.d.ts
@@ -466,6 +467,79 @@ declare function isGatewayUrl(url: URL): boolean;
 */
 declare function parseGatewayUrl(url: string): URL;
 /**
+* Converts an [FEP-ef61] compatible identifier into a portable ActivityPub
+* URI.
+*
+* A compatible identifier is an HTTP(S) URL under a gateway's fixed
+* `/.well-known/apgateway/` path, such as
+* `https://server.example/.well-known/apgateway/did:key:z6Mk.../objects/1`.
+* This function removes the gateway part and returns the corresponding
+* portable URI, e.g., `ap+ef61://did:key:z6Mk.../objects/1`, in the same
+* internal `URL` form that {@link parseIri} produces.  The path, query, and
+* fragment are preserved, so the result is a portable URI, not a comparison
+* form; pass its `href` to {@link canonicalizePortableUri} or
+* {@link arePortableUrisEqual} to compare it with other portable URIs.
+*
+* The conversion only reveals the *claimed* portable identifier.  Anyone can
+* publish a compatible identifier for any DID on their own server, so the
+* gateway that served it is neither the object's origin nor authorized to act
+* for the DID.  Callers must still verify the retrieved document's Object
+* Integrity Proof against the DID, as FEP-ef61 requires, and should keep the
+* original URL if they need the gateway as a retrieval hint.
+*
+* Arbitrary gateway paths are not supported.
+*
+* [FEP-ef61]: https://w3id.org/fep/ef61
+*
+* @param input The URL to convert.
+* @returns The portable ActivityPub URI, or `null` if the input is not an
+*          HTTP(S) URL whose path starts with `/.well-known/apgateway/did:`.
+*          Other gateway routes, such as the gateway discovery endpoint and
+*          hashlink media URLs, also yield `null`.
+* @throws {TypeError} If the input looks like a compatible identifier but is
+*                     malformed, e.g., it has an invalid DID, no object path,
+*                     invalid percent-encoding, credentials, or location
+*                     hints (`@gateway` query parameters, or the legacy
+*                     `gateways` parameter), which FEP-ef61 forbids in
+*                     compatible identifiers.
+* @since 2.4.0
+*/
+declare function fromCompatibleEf61Id(input: string | URL): URL | null;
+/**
+* Converts a portable ActivityPub URI into an [FEP-ef61] compatible
+* identifier, which is an HTTP(S) URL under the gateway's fixed
+* `/.well-known/apgateway/` path.
+*
+* For example, `ap+ef61://did:key:z6Mk.../objects/1` and
+* `https://server.example` yield
+* `https://server.example/.well-known/apgateway/did:key:z6Mk.../objects/1`.
+* Both `ap:` and `ap+ef61:` URIs with decoded or percent-encoded DID
+* authorities are accepted.  Publishers should use the first gateway in the
+* actor's `gateways` list, as FEP-ef61 requires.
+*
+* The path and fragment are preserved, with characters that are not allowed
+* in HTTP(S) URLs percent-encoded the same way as
+* {@link canonicalizePortableUri} does.  FEP-ef61 location hints (`@gateway`
+* query parameters, and the legacy `gateways` parameter) are removed, since
+* compatible identifiers must not have them; other query parameters are kept
+* in order.
+*
+* Arbitrary gateway paths are not supported.
+*
+* [FEP-ef61]: https://w3id.org/fep/ef61
+*
+* @param portableId The `ap:` or `ap+ef61:` URI to convert.
+* @param gateway The gateway's HTTP(S) origin, e.g., `https://server.example`.
+* @returns The compatible identifier.
+* @throws {TypeError} If the portable ID is not a valid `ap:` or `ap+ef61:`
+*                     URI, if its path has `.` or `..` segments (which
+*                     HTTP(S) URLs cannot represent), or if the gateway is
+*                     not an HTTP(S) origin with no credentials, path, query,
+*                     or fragment.
+* @since 2.4.0
+*/
+declare function toCompatibleEf61Id(portableId: string | URL, gateway: string | URL): URL;
+/**
 * Validates a URL to prevent SSRF attacks.
 */
 declare function validatePublicUrl(url: string): Promise<void>;
@@ -473,4 +547,4 @@ declare function isValidPublicIPv4Address(address: string): boolean;
 declare function isValidPublicIPv6Address(address: string): boolean;
 declare function expandIPv6Address(address: string): string;
 //#endregion
-export { type AuthenticatedDocumentLoaderFactory, type CreateRequestOptions, type Decimal, type DidKeyVerificationMethod, type DocumentLoader, type DocumentLoaderFactory, type DocumentLoaderFactoryOptions, type DocumentLoaderOptions, FetchError, type GetDocumentLoaderOptions, type GetUserAgentOptions, type Json, LanguageString, type ParsedDigestMultibase, type ParsedHashlink, type PropertyPreprocessor, type PropertyPreprocessorContext, type RemoteDocument, UrlError, arePortableUrisEqual, canParseDecimal, canonicalizePortableUri, computeDigestMultibase, createActivityPubRequest, createHashlink, decodeMultibase, encodeMultibase, encodingFromBaseData, expandIPv6Address, exportDidKey, exportMultibaseKey, exportSpki, formatIri, getDocumentLoader, getFe34Origin, getRemoteDocument, getUserAgent, haveSameFe34Origin, haveSameIriOrigin, importDidKey, importMultibaseKey, importPem, importPkcs1, importSpki, isDecimal, isGatewayUrl, isValidPublicIPv4Address, isValidPublicIPv6Address, logRequest, parseDecimal, parseDidKeyVerificationMethod, parseDigestMultibase, parseGatewayUrl, parseHashlink, parseIri, parseJsonLdId, preloadedContexts, validatePublicUrl, verifyDigestMultibase, verifyHashlink };
+export { type AuthenticatedDocumentLoaderFactory, type CreateRequestOptions, type Decimal, type DidKeyVerificationMethod, type DocumentLoader, type DocumentLoaderFactory, type DocumentLoaderFactoryOptions, type DocumentLoaderOptions, FetchError, type GetDocumentLoaderOptions, type GetUserAgentOptions, type Json, LanguageString, type ParsedDigestMultibase, type ParsedHashlink, type PortableObjectVerifier, type PortableObjectVerifierOptions, type PropertyPreprocessor, type PropertyPreprocessorContext, type RemoteDocument, UrlError, arePortableUrisEqual, canParseDecimal, canonicalizePortableUri, computeDigestMultibase, createActivityPubRequest, createHashlink, decodeMultibase, encodeMultibase, encodingFromBaseData, expandIPv6Address, exportDidKey, exportMultibaseKey, exportSpki, formatIri, fromCompatibleEf61Id, getDocumentLoader, getFe34Origin, getRemoteDocument, getUserAgent, haveSameFe34Origin, haveSameIriOrigin, importDidKey, importMultibaseKey, importPem, importPkcs1, importSpki, isDecimal, isGatewayUrl, isValidPublicIPv4Address, isValidPublicIPv6Address, logRequest, parseDecimal, parseDidKeyVerificationMethod, parseDigestMultibase, parseGatewayUrl, parseHashlink, parseIri, parseJsonLdId, preloadedContexts, toCompatibleEf61Id, validatePublicUrl, verifyDigestMultibase, verifyHashlink };

package/dist/mod.d.ts

@@ -1,5 +1,6 @@
 /// <reference lib="esnext.temporal" />
 import { a as DocumentLoaderOptions, c as getDocumentLoader, d as FetchError, f as GetUserAgentOptions, h as logRequest, i as DocumentLoaderFactoryOptions, l as getRemoteDocument, m as getUserAgent, n as DocumentLoader, o as GetDocumentLoaderOptions, p as createActivityPubRequest, r as DocumentLoaderFactory, s as RemoteDocument, t as AuthenticatedDocumentLoaderFactory, u as CreateRequestOptions } from "./docloader-Dr8wEkif.js";
+import { n as PortableObjectVerifierOptions, t as PortableObjectVerifier } from "./portable-CduElToy.js";
 import { TracerProvider } from "@opentelemetry/api";
 //#region src/contexts.d.ts
 declare const preloadedContexts: Record<string, unknown>;
@@ -465,6 +466,79 @@ declare function isGatewayUrl(url: URL): boolean;
 */
 declare function parseGatewayUrl(url: string): URL;
 /**
+* Converts an [FEP-ef61] compatible identifier into a portable ActivityPub
+* URI.
+*
+* A compatible identifier is an HTTP(S) URL under a gateway's fixed
+* `/.well-known/apgateway/` path, such as
+* `https://server.example/.well-known/apgateway/did:key:z6Mk.../objects/1`.
+* This function removes the gateway part and returns the corresponding
+* portable URI, e.g., `ap+ef61://did:key:z6Mk.../objects/1`, in the same
+* internal `URL` form that {@link parseIri} produces.  The path, query, and
+* fragment are preserved, so the result is a portable URI, not a comparison
+* form; pass its `href` to {@link canonicalizePortableUri} or
+* {@link arePortableUrisEqual} to compare it with other portable URIs.
+*
+* The conversion only reveals the *claimed* portable identifier.  Anyone can
+* publish a compatible identifier for any DID on their own server, so the
+* gateway that served it is neither the object's origin nor authorized to act
+* for the DID.  Callers must still verify the retrieved document's Object
+* Integrity Proof against the DID, as FEP-ef61 requires, and should keep the
+* original URL if they need the gateway as a retrieval hint.
+*
+* Arbitrary gateway paths are not supported.
+*
+* [FEP-ef61]: https://w3id.org/fep/ef61
+*
+* @param input The URL to convert.
+* @returns The portable ActivityPub URI, or `null` if the input is not an
+*          HTTP(S) URL whose path starts with `/.well-known/apgateway/did:`.
+*          Other gateway routes, such as the gateway discovery endpoint and
+*          hashlink media URLs, also yield `null`.
+* @throws {TypeError} If the input looks like a compatible identifier but is
+*                     malformed, e.g., it has an invalid DID, no object path,
+*                     invalid percent-encoding, credentials, or location
+*                     hints (`@gateway` query parameters, or the legacy
+*                     `gateways` parameter), which FEP-ef61 forbids in
+*                     compatible identifiers.
+* @since 2.4.0
+*/
+declare function fromCompatibleEf61Id(input: string | URL): URL | null;
+/**
+* Converts a portable ActivityPub URI into an [FEP-ef61] compatible
+* identifier, which is an HTTP(S) URL under the gateway's fixed
+* `/.well-known/apgateway/` path.
+*
+* For example, `ap+ef61://did:key:z6Mk.../objects/1` and
+* `https://server.example` yield
+* `https://server.example/.well-known/apgateway/did:key:z6Mk.../objects/1`.
+* Both `ap:` and `ap+ef61:` URIs with decoded or percent-encoded DID
+* authorities are accepted.  Publishers should use the first gateway in the
+* actor's `gateways` list, as FEP-ef61 requires.
+*
+* The path and fragment are preserved, with characters that are not allowed
+* in HTTP(S) URLs percent-encoded the same way as
+* {@link canonicalizePortableUri} does.  FEP-ef61 location hints (`@gateway`
+* query parameters, and the legacy `gateways` parameter) are removed, since
+* compatible identifiers must not have them; other query parameters are kept
+* in order.
+*
+* Arbitrary gateway paths are not supported.
+*
+* [FEP-ef61]: https://w3id.org/fep/ef61
+*
+* @param portableId The `ap:` or `ap+ef61:` URI to convert.
+* @param gateway The gateway's HTTP(S) origin, e.g., `https://server.example`.
+* @returns The compatible identifier.
+* @throws {TypeError} If the portable ID is not a valid `ap:` or `ap+ef61:`
+*                     URI, if its path has `.` or `..` segments (which
+*                     HTTP(S) URLs cannot represent), or if the gateway is
+*                     not an HTTP(S) origin with no credentials, path, query,
+*                     or fragment.
+* @since 2.4.0
+*/
+declare function toCompatibleEf61Id(portableId: string | URL, gateway: string | URL): URL;
+/**
 * Validates a URL to prevent SSRF attacks.
 */
 declare function validatePublicUrl(url: string): Promise<void>;
@@ -472,4 +546,4 @@ declare function isValidPublicIPv4Address(address: string): boolean;
 declare function isValidPublicIPv6Address(address: string): boolean;
 declare function expandIPv6Address(address: string): string;
 //#endregion
-export { type AuthenticatedDocumentLoaderFactory, type CreateRequestOptions, type Decimal, type DidKeyVerificationMethod, type DocumentLoader, type DocumentLoaderFactory, type DocumentLoaderFactoryOptions, type DocumentLoaderOptions, FetchError, type GetDocumentLoaderOptions, type GetUserAgentOptions, type Json, LanguageString, type ParsedDigestMultibase, type ParsedHashlink, type PropertyPreprocessor, type PropertyPreprocessorContext, type RemoteDocument, UrlError, arePortableUrisEqual, canParseDecimal, canonicalizePortableUri, computeDigestMultibase, createActivityPubRequest, createHashlink, decodeMultibase, encodeMultibase, encodingFromBaseData, expandIPv6Address, exportDidKey, exportMultibaseKey, exportSpki, formatIri, getDocumentLoader, getFe34Origin, getRemoteDocument, getUserAgent, haveSameFe34Origin, haveSameIriOrigin, importDidKey, importMultibaseKey, importPem, importPkcs1, importSpki, isDecimal, isGatewayUrl, isValidPublicIPv4Address, isValidPublicIPv6Address, logRequest, parseDecimal, parseDidKeyVerificationMethod, parseDigestMultibase, parseGatewayUrl, parseHashlink, parseIri, parseJsonLdId, preloadedContexts, validatePublicUrl, verifyDigestMultibase, verifyHashlink };
+export { type AuthenticatedDocumentLoaderFactory, type CreateRequestOptions, type Decimal, type DidKeyVerificationMethod, type DocumentLoader, type DocumentLoaderFactory, type DocumentLoaderFactoryOptions, type DocumentLoaderOptions, FetchError, type GetDocumentLoaderOptions, type GetUserAgentOptions, type Json, LanguageString, type ParsedDigestMultibase, type ParsedHashlink, type PortableObjectVerifier, type PortableObjectVerifierOptions, type PropertyPreprocessor, type PropertyPreprocessorContext, type RemoteDocument, UrlError, arePortableUrisEqual, canParseDecimal, canonicalizePortableUri, computeDigestMultibase, createActivityPubRequest, createHashlink, decodeMultibase, encodeMultibase, encodingFromBaseData, expandIPv6Address, exportDidKey, exportMultibaseKey, exportSpki, formatIri, fromCompatibleEf61Id, getDocumentLoader, getFe34Origin, getRemoteDocument, getUserAgent, haveSameFe34Origin, haveSameIriOrigin, importDidKey, importMultibaseKey, importPem, importPkcs1, importSpki, isDecimal, isGatewayUrl, isValidPublicIPv4Address, isValidPublicIPv6Address, logRequest, parseDecimal, parseDidKeyVerificationMethod, parseDigestMultibase, parseGatewayUrl, parseHashlink, parseIri, parseJsonLdId, preloadedContexts, toCompatibleEf61Id, validatePublicUrl, verifyDigestMultibase, verifyHashlink };

package/dist/mod.js

@@ -1,6 +1,6 @@
 
 import { t as preloadedContexts } from "./contexts-DoZUIW7y.js";
-import { a as formatIri, c as haveSameIriOrigin, d as isValidPublicIPv6Address, f as parseGatewayUrl, h as validatePublicUrl, i as expandIPv6Address, l as isGatewayUrl, m as parseJsonLdId, n as arePortableUrisEqual, o as getFe34Origin, p as parseIri, r as canonicalizePortableUri, s as haveSameFe34Origin, t as UrlError, u as isValidPublicIPv4Address } from "./url-BHAShw9J.js";
+import { _ as validatePublicUrl, a as formatIri, c as haveSameFe34Origin, d as isValidPublicIPv4Address, f as isValidPublicIPv6Address, g as toCompatibleEf61Id, h as parseJsonLdId, i as expandIPv6Address, l as haveSameIriOrigin, m as parseIri, n as arePortableUrisEqual, o as fromCompatibleEf61Id, p as parseGatewayUrl, r as canonicalizePortableUri, s as getFe34Origin, t as UrlError, u as isGatewayUrl } from "./url-CEhi4hb4.js";
 import { getLogger } from "@logtape/logtape";
 import { SpanKind, SpanStatusCode, trace } from "@opentelemetry/api";
 import process from "node:process";
@@ -12,7 +12,7 @@ import { PublicKeyInfo } from "pkijs";
 import baseX from "@multiformats/base-x";
 //#region deno.json
 var name = "@fedify/vocab-runtime";
-var version = "2.4.0-dev.2030+e6b3de3d";
+var version = "2.4.0-dev.2047+140b94db";
 //#endregion
 //#region src/request.ts
 /**
@@ -42,6 +42,12 @@ var FetchError = class extends Error {
 	}
 };
 /**
+* The `Accept` header value for fetching ActivityPub objects.  ActivityPub
+* and FEP-ef61 gateways require the ActivityStreams profile on the JSON-LD
+* media type.
+*/
+const ACTIVITYPUB_ACCEPT = "application/activity+json, application/ld+json; profile=\"https://www.w3.org/ns/activitystreams\"";
+/**
 * Creates a request for the given URL.
 * @param url The URL to create the request for.
 * @param options The options for the request.
@@ -51,7 +57,7 @@ var FetchError = class extends Error {
 function createActivityPubRequest(url, options = {}) {
 	return new Request(url, {
 		headers: {
-			Accept: "application/activity+json, application/ld+json",
+			Accept: ACTIVITYPUB_ACCEPT,
 			"User-Agent": typeof options.userAgent === "string" ? options.userAgent : getUserAgent(options.userAgent)
 		},
 		redirect: "manual"
@@ -1358,4 +1364,4 @@ LanguageString.prototype[Symbol.for("nodejs.util.inspect.custom")] = function(_d
 	return `<${this.locale.baseName}> ${inspect(this.toString(), options)}`;
 };
 //#endregion
-export { FetchError, LanguageString, UrlError, arePortableUrisEqual, canParseDecimal, canonicalizePortableUri, computeDigestMultibase, createActivityPubRequest, createHashlink, decodeMultibase, encodeMultibase, encodingFromBaseData, expandIPv6Address, exportDidKey, exportMultibaseKey, exportSpki, formatIri, getDocumentLoader, getFe34Origin, getRemoteDocument, getUserAgent, haveSameFe34Origin, haveSameIriOrigin, importDidKey, importMultibaseKey, importPem, importPkcs1, importSpki, isDecimal, isGatewayUrl, isValidPublicIPv4Address, isValidPublicIPv6Address, logRequest, parseDecimal, parseDidKeyVerificationMethod, parseDigestMultibase, parseGatewayUrl, parseHashlink, parseIri, parseJsonLdId, preloadedContexts, validatePublicUrl, verifyDigestMultibase, verifyHashlink };
+export { FetchError, LanguageString, UrlError, arePortableUrisEqual, canParseDecimal, canonicalizePortableUri, computeDigestMultibase, createActivityPubRequest, createHashlink, decodeMultibase, encodeMultibase, encodingFromBaseData, expandIPv6Address, exportDidKey, exportMultibaseKey, exportSpki, formatIri, fromCompatibleEf61Id, getDocumentLoader, getFe34Origin, getRemoteDocument, getUserAgent, haveSameFe34Origin, haveSameIriOrigin, importDidKey, importMultibaseKey, importPem, importPkcs1, importSpki, isDecimal, isGatewayUrl, isValidPublicIPv4Address, isValidPublicIPv6Address, logRequest, parseDecimal, parseDidKeyVerificationMethod, parseDigestMultibase, parseGatewayUrl, parseHashlink, parseIri, parseJsonLdId, preloadedContexts, toCompatibleEf61Id, validatePublicUrl, verifyDigestMultibase, verifyHashlink };

package/dist/portable-CduElToy.d.ts

@@ -0,0 +1,52 @@
+/// <reference lib="esnext.temporal" />
+import { n as DocumentLoader } from "./docloader-Dr8wEkif.js";
+import { TracerProvider } from "@opentelemetry/api";
+
+//#region src/portable.d.ts
+/**
+* Options passed to a {@link PortableObjectVerifier}.
+* @since 2.4.0
+*/
+interface PortableObjectVerifierOptions {
+  /**
+  * The document loader for fetching remote documents, such as verification
+  * methods that are not `did:key` URLs.
+  */
+  readonly documentLoader?: DocumentLoader;
+  /**
+  * The document loader for fetching remote JSON-LD contexts.  During
+  * gateway dereferencing, this loader returns the same context documents
+  * that the vocabulary parser sees.
+  */
+  readonly contextLoader?: DocumentLoader;
+  /**
+  * The OpenTelemetry tracer provider.
+  */
+  readonly tracerProvider?: TracerProvider;
+}
+/**
+* A function that applies the [FEP-ef61] proof policy to a portable object
+* fetched through a gateway.
+*
+* It receives the fetched JSON-LD document as is, and resolves to an object
+* whose `verified` property tells whether the document carries a valid
+* [FEP-8b32] Object Integrity Proof made by the DID in its portable ID.
+* `verifyPortableObjectProof()` from `@fedify/fedify` satisfies this type, so
+* it can be passed as the `verifyPortableObject` option of generated
+* vocabulary accessors such as `Activity.getObject()`.
+*
+* [FEP-ef61]: https://w3id.org/fep/ef61
+* [FEP-8b32]: https://w3id.org/fep/8b32
+*
+* @param document The fetched JSON-LD document.
+* @param options Loaders and tracing options for verification.
+* @returns An object whose `verified` property is `true` if and only if the
+*          document satisfies the proof policy.  Other properties, such as
+*          a failure reason, are logged when verification fails.
+* @since 2.4.0
+*/
+type PortableObjectVerifier = (document: unknown, options: PortableObjectVerifierOptions) => Promise<{
+  readonly verified: boolean;
+}>;
+//#endregion
+export { PortableObjectVerifierOptions as n, PortableObjectVerifier as t };