@fedify/vocab-runtime 2.4.0-dev.2228 → 2.4.0-dev.2240

package/deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/vocab-runtime",
-  "version": "2.4.0-dev.2228+6d017d55",
+  "version": "2.4.0-dev.2240+79613fa6",
   "license": "MIT",
   "exports": {
     ".": "./src/mod.ts",
@@ -36,6 +36,6 @@
   },
   "tasks": {
     "check": "deno fmt --check && deno lint && deno check src/*.ts",
-    "test": "deno test"
+    "test": "deno test --allow-net --allow-env=LOG"
   }
 }

package/dist/internal/jsonld-cache.cjs

@@ -1,6 +1,6 @@
 
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_url = require("../url-CHAbe3hE.cjs");
+const require_url = require("../url-BJMXv2kE.cjs");
 const require_jsonld = require("../jsonld.cjs");
 //#region src/internal/jsonld-cache.ts
 const noJsonLdContext = Symbol("noJsonLdContext");

package/dist/internal/jsonld-cache.js

@@ -1,5 +1,5 @@
 
-import { a as formatIri, c as haveSameFe34Origin, l as haveSameIriOrigin } from "../url-BfguNa6K.js";
+import { d as haveSameIriOrigin, o as formatIri, u as haveSameFe34Origin } from "../url-CZm2-7ZO.js";
 import jsonld_default from "../jsonld.js";
 //#region src/internal/jsonld-cache.ts
 const noJsonLdContext = Symbol("noJsonLdContext");

package/dist/internal/portable-dereference.cjs

@@ -1,7 +1,7 @@
 
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_contexts = require("../contexts-BK1CqBR5.cjs");
-const require_url = require("../url-CHAbe3hE.cjs");
+const require_url = require("../url-BJMXv2kE.cjs");
 const require_jsonld = require("../jsonld.cjs");
 const require_internal_jsonld_cache = require("./jsonld-cache.cjs");
 let _logtape_logtape = require("@logtape/logtape");
@@ -18,7 +18,6 @@ const logger = (0, _logtape_logtape.getLogger)([
 * 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",
@@ -138,13 +137,10 @@ function copyPortableProvenance(from, to) {
 * 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;
+		if (typeof url === "string") url = new URL(url);
 		return {
 			id,
 			gateway: new URL(url.origin)
@@ -152,7 +148,7 @@ function parseCompatibleEf61Reference(url) {
 	} catch (error) {
 		if (error instanceof TypeError) {
 			logger.debug("Invalid FEP-ef61 compatible identifier {url}: {error}", {
-				url: url.href,
+				url: typeof url === "string" ? url : url.href,
 				error
 			});
 			return null;
@@ -359,15 +355,15 @@ function getPortableGatewayCandidates(url, gateways) {
 	};
 	if (gateways != null) {
 		for (const gateway of gateways) {
-			const parsed = parseGatewayOrigin(gateway);
+			const parsed = require_url.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)) {
+	for (const hint of new URLSearchParams(url.search).getAll(require_url.GATEWAY_HINT_PARAMETER)) {
 		if (candidates.length >= MAX_GATEWAY_HINTS) break;
-		const parsed = parseGatewayOrigin(hint);
+		const parsed = require_url.parseGatewayOrigin(hint);
 		if (parsed == null) {
 			logger.debug("Ignoring an invalid FEP-ef61 gateway hint {hint} in {url}.", {
 				hint,
@@ -379,14 +375,6 @@ function getPortableGatewayCandidates(url, gateways) {
 	}
 	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 (!require_url.isGatewayUrl(url)) 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

package/dist/internal/portable-dereference.js

@@ -1,6 +1,6 @@
 
 import { t as preloadedContexts } from "../contexts-DPuJ4UYL.js";
-import { a as formatIri, c as haveSameFe34Origin, g as toCompatibleEf61Id, m as parseIri, o as fromCompatibleEf61Id, r as canonicalizePortableUri, u as isGatewayUrl } from "../url-BfguNa6K.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-CZm2-7ZO.js";
 import jsonld_default from "../jsonld.js";
 import { createScopedContextLoader, registerDocumentLoaderWrapper, unwrapReleasedDocumentLoader } from "./jsonld-cache.js";
 import { getLogger } from "@logtape/logtape";
@@ -17,7 +17,6 @@ const logger = getLogger([
 * 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",
@@ -137,13 +136,10 @@ function copyPortableProvenance(from, to) {
 * Semantic Versioning decisions.
 */
 function parseCompatibleEf61Reference(url) {
-	if (typeof url === "string") {
-		if (!URL.canParse(url)) return void 0;
-		url = new URL(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)
@@ -151,7 +147,7 @@ function parseCompatibleEf61Reference(url) {
 	} catch (error) {
 		if (error instanceof TypeError) {
 			logger.debug("Invalid FEP-ef61 compatible identifier {url}: {error}", {
-				url: url.href,
+				url: typeof url === "string" ? url : url.href,
 				error
 			});
 			return null;
@@ -364,7 +360,7 @@ function getPortableGatewayCandidates(url, gateways) {
 		}
 		return candidates;
 	}
-	for (const hint of new URLSearchParams(url.search).getAll(LOCATION_HINT_PARAMETER)) {
+	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) {
@@ -378,14 +374,6 @@ function getPortableGatewayCandidates(url, gateways) {
 	}
 	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 (!isGatewayUrl(url)) 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

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-BK1CqBR5.cjs");
-const require_url = require("./url-CHAbe3hE.cjs");
+const require_url = require("./url-BJMXv2kE.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.2228+6d017d55";
+var version = "2.4.0-dev.2240+79613fa6";
 //#endregion
 //#region src/request.ts
 /**
@@ -1745,6 +1745,7 @@ exports.formatIri = require_url.formatIri;
 exports.fromCompatibleEf61Id = require_url.fromCompatibleEf61Id;
 exports.getDocumentLoader = getDocumentLoader;
 exports.getFe34Origin = require_url.getFe34Origin;
+exports.getGatewayHints = require_url.getGatewayHints;
 exports.getRemoteDocument = getRemoteDocument;
 exports.getUserAgent = getUserAgent;
 exports.haveSameFe34Origin = require_url.haveSameFe34Origin;
@@ -1773,3 +1774,5 @@ exports.validatePublicUrl = require_url.validatePublicUrl;
 exports.verifyDigestMultibase = verifyDigestMultibase;
 exports.verifyHashlink = verifyHashlink;
 exports.withDocumentLoaderTimeout = withDocumentLoaderTimeout;
+exports.withGatewayHints = require_url.withGatewayHints;
+exports.withoutGatewayHints = require_url.withoutGatewayHints;

package/dist/mod.d.cts

@@ -467,10 +467,19 @@ declare class UrlError extends Error {
 declare function parseJsonLdId(id: string | undefined, base?: string | URL): URL | undefined;
 /**
 * Parses an IRI as a URL, including FEP-ef61 portable ActivityPub IRIs.
+* Portable URI and FEP-ef61 compatible identifier strings whose path contains
+* a `.` or `..` segment, including percent-encoded spellings, throw a
+* `TypeError`: JavaScript `URL` would otherwise identify a different object.
+* This also applies to compatible identifier strings used as relative bases.
+* A `URL` argument may already have lost such segments before this function
+* receives it.
 */
 declare function parseIri(iri: string | URL, base?: string | URL): URL;
 /**
 * Formats a URL as an IRI, including FEP-ef61 portable ActivityPub IRIs.
+* Portable URI and FEP-ef61 compatible identifier strings with dot segments
+* throw a `TypeError` because their paths cannot be represented by JavaScript
+* `URL` without normalization.
 */
 declare function formatIri(iri: string | URL): string;
 /**
@@ -570,8 +579,9 @@ declare function parseGatewayUrl(url: string): URL;
 *                     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.
+*                     `gateways` parameter), or its raw string path would
+*                     change during URL parsing.  Already-parsed `URL`
+*                     arguments cannot reveal segments lost by their parser.
 * @since 2.4.0
 */
 declare function fromCompatibleEf61Id(input: string | URL): URL | null;
@@ -603,13 +613,106 @@ declare function fromCompatibleEf61Id(input: string | URL): URL | null;
 * @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
+*                     HTTP(S) URLs cannot represent without changing the
+*                     identified object), 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;
 /**
+* Returns a copy of an [FEP-ef61] portable ActivityPub URI with `@gateway`
+* location hints for the given gateways, which tell consumers where they can
+* retrieve the object.  Put hints on *references* to portable actors, e.g.,
+* in `actor`, `attributedTo`, `to`, or `cc`, when constructing an object, as
+* FEP-ef61 recommends:
+*
+* ~~~~ typescript
+* withGatewayHints("ap://did:key:z6Mk.../actor", [
+*   "https://server1.example",
+*   "https://server2.example",
+* ]);
+* // ap+ef61://did:key:z6Mk.../actor?@gateway=https%3A%2F%2Fserver1.example&@gateway=https%3A%2F%2Fserver2.example
+* ~~~~
+*
+* Do not put hints on an object's own `id`.  Hints do not change the
+* identity of a portable URI, since FEP-ef61 drops the query when comparing
+* portable URIs, but implementations that do not canonicalize portable URIs
+* would take a hinted ID for another object.  Add hints before signing the
+* object, since its Object Integrity Proof covers its references too.
+*
+* The hints that the URI already has, including the legacy `gateways`
+* parameter, are replaced.  Each gateway becomes a `@gateway` query
+* parameter whose value is its URI-encoded origin, e.g.,
+* `@gateway=https%3A%2F%2Fserver1.example`, in the given order after the
+* other query parameters.  Duplicate gateways are dropped, and an empty list
+* removes the hints as {@link withoutGatewayHints} does.  The other query
+* parameters, their order, and the fragment are kept, but percent-encoding
+* is normalized the same way as {@link canonicalizePortableUri} does it.
+*
+* Fedify follows at most five hints when dereferencing a portable URI
+* (three for the key ID of an HTTP Signature), so list the preferred
+* gateways first; there is no limit on the number of hints added here.
+*
+* [FEP-ef61]: https://w3id.org/fep/ef61
+*
+* @param portableId The `ap:` or `ap+ef61:` URI.  Pass the raw string rather
+*                   than a `URL` if its path may have `.` or `..` segments,
+*                   because the `URL` class resolves them.
+* @param gateways The gateways, e.g., the `gateways` of the actor that the
+*                 URI refers to.  Each has to be an HTTP(S) origin with no
+*                 credentials, path, query, or fragment.
+* @returns The portable URI with the hints, in the same internal `URL` form
+*          as {@link parseIri} returns.  Use {@link formatIri} to get its
+*          canonical string.
+* @throws {TypeError} If the portable ID is not a valid `ap:` or `ap+ef61:`
+*                     URI, e.g., it is a compatible identifier, which must
+*                     not have location hints; if its path has `.` or `..`
+*                     segments, which the `URL` class cannot represent; or
+*                     if a gateway is invalid.
+* @since 2.4.0
+*/
+declare function withGatewayHints(portableId: string | URL, gateways: Iterable<string | URL>): URL;
+/**
+* Returns a copy of an [FEP-ef61] portable ActivityPub URI without its
+* location hints, i.e., `@gateway` query parameters and the legacy
+* `gateways` parameter.  The other query parameters, their order, and the
+* fragment are kept, but percent-encoding is normalized the same way as
+* {@link canonicalizePortableUri} does it.
+*
+* [FEP-ef61]: https://w3id.org/fep/ef61
+*
+* @param portableId The `ap:` or `ap+ef61:` URI.  Pass the raw string rather
+*                   than a `URL` if its path may have `.` or `..` segments,
+*                   because the `URL` class resolves them.
+* @returns The portable URI without the hints, in the same internal `URL`
+*          form as {@link parseIri} returns.
+* @throws {TypeError} If the portable ID is not a valid `ap:` or `ap+ef61:`
+*                     URI, or if its path has `.` or `..` segments, which
+*                     the `URL` class cannot represent.
+* @since 2.4.0
+*/
+declare function withoutGatewayHints(portableId: string | URL): URL;
+/**
+* Gets the gateways in the `@gateway` location hints of an [FEP-ef61]
+* portable ActivityPub URI, in order.  Hints that are not valid gateways,
+* i.e., HTTP(S) origins with no credentials, path, query, or fragment, are
+* skipped, and so are duplicates.  The legacy `gateways` parameter is not
+* read.
+*
+* Unlike Fedify's dereferencing, which follows at most five hints, this
+* returns all of them.
+*
+* [FEP-ef61]: https://w3id.org/fep/ef61
+*
+* @param portableId The `ap:` or `ap+ef61:` URI.
+* @returns The gateways, e.g., `https://server1.example/`.
+* @throws {TypeError} If the portable ID is not a valid `ap:` or `ap+ef61:`
+*                     URI.
+* @since 2.4.0
+*/
+declare function getGatewayHints(portableId: string | URL): URL[];
+/**
 * Validates a URL to prevent SSRF attacks.
 */
 declare function validatePublicUrl(url: string): Promise<void>;
@@ -617,4 +720,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 FetchPortableMediaOptions, type GetDocumentLoaderOptions, type GetUserAgentOptions, type Json, LanguageString, type ParsedDigestMultibase, type ParsedHashlink, type PortableMedia, type PortableObjectReferrer, type PortableObjectVerification, type PortableObjectVerifier, type PortableObjectVerifierOptions, type PropertyPreprocessor, type PropertyPreprocessorContext, type RemoteDocument, UrlError, arePortableUrisEqual, canParseDecimal, canonicalizePortableUri, computeDigestMultibase, createActivityPubRequest, createHashlink, decodeMultibase, encodeMultibase, encodingFromBaseData, expandIPv6Address, exportDidKey, exportMultibaseKey, exportSpki, fetchPortableMedia, 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, resolveDocumentLoaderTimeout, toCompatibleEf61Id, validatePublicUrl, verifyDigestMultibase, verifyHashlink, withDocumentLoaderTimeout };
+export { type AuthenticatedDocumentLoaderFactory, type CreateRequestOptions, type Decimal, type DidKeyVerificationMethod, type DocumentLoader, type DocumentLoaderFactory, type DocumentLoaderFactoryOptions, type DocumentLoaderOptions, FetchError, type FetchPortableMediaOptions, type GetDocumentLoaderOptions, type GetUserAgentOptions, type Json, LanguageString, type ParsedDigestMultibase, type ParsedHashlink, type PortableMedia, type PortableObjectReferrer, type PortableObjectVerification, type PortableObjectVerifier, type PortableObjectVerifierOptions, type PropertyPreprocessor, type PropertyPreprocessorContext, type RemoteDocument, UrlError, arePortableUrisEqual, canParseDecimal, canonicalizePortableUri, computeDigestMultibase, createActivityPubRequest, createHashlink, decodeMultibase, encodeMultibase, encodingFromBaseData, expandIPv6Address, exportDidKey, exportMultibaseKey, exportSpki, fetchPortableMedia, formatIri, fromCompatibleEf61Id, getDocumentLoader, getFe34Origin, getGatewayHints, getRemoteDocument, getUserAgent, haveSameFe34Origin, haveSameIriOrigin, importDidKey, importMultibaseKey, importPem, importPkcs1, importSpki, isDecimal, isGatewayUrl, isValidPublicIPv4Address, isValidPublicIPv6Address, logRequest, parseDecimal, parseDidKeyVerificationMethod, parseDigestMultibase, parseGatewayUrl, parseHashlink, parseIri, parseJsonLdId, preloadedContexts, resolveDocumentLoaderTimeout, toCompatibleEf61Id, validatePublicUrl, verifyDigestMultibase, verifyHashlink, withDocumentLoaderTimeout, withGatewayHints, withoutGatewayHints };

package/dist/mod.d.ts

@@ -466,10 +466,19 @@ declare class UrlError extends Error {
 declare function parseJsonLdId(id: string | undefined, base?: string | URL): URL | undefined;
 /**
 * Parses an IRI as a URL, including FEP-ef61 portable ActivityPub IRIs.
+* Portable URI and FEP-ef61 compatible identifier strings whose path contains
+* a `.` or `..` segment, including percent-encoded spellings, throw a
+* `TypeError`: JavaScript `URL` would otherwise identify a different object.
+* This also applies to compatible identifier strings used as relative bases.
+* A `URL` argument may already have lost such segments before this function
+* receives it.
 */
 declare function parseIri(iri: string | URL, base?: string | URL): URL;
 /**
 * Formats a URL as an IRI, including FEP-ef61 portable ActivityPub IRIs.
+* Portable URI and FEP-ef61 compatible identifier strings with dot segments
+* throw a `TypeError` because their paths cannot be represented by JavaScript
+* `URL` without normalization.
 */
 declare function formatIri(iri: string | URL): string;
 /**
@@ -569,8 +578,9 @@ declare function parseGatewayUrl(url: string): URL;
 *                     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.
+*                     `gateways` parameter), or its raw string path would
+*                     change during URL parsing.  Already-parsed `URL`
+*                     arguments cannot reveal segments lost by their parser.
 * @since 2.4.0
 */
 declare function fromCompatibleEf61Id(input: string | URL): URL | null;
@@ -602,13 +612,106 @@ declare function fromCompatibleEf61Id(input: string | URL): URL | null;
 * @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
+*                     HTTP(S) URLs cannot represent without changing the
+*                     identified object), 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;
 /**
+* Returns a copy of an [FEP-ef61] portable ActivityPub URI with `@gateway`
+* location hints for the given gateways, which tell consumers where they can
+* retrieve the object.  Put hints on *references* to portable actors, e.g.,
+* in `actor`, `attributedTo`, `to`, or `cc`, when constructing an object, as
+* FEP-ef61 recommends:
+*
+* ~~~~ typescript
+* withGatewayHints("ap://did:key:z6Mk.../actor", [
+*   "https://server1.example",
+*   "https://server2.example",
+* ]);
+* // ap+ef61://did:key:z6Mk.../actor?@gateway=https%3A%2F%2Fserver1.example&@gateway=https%3A%2F%2Fserver2.example
+* ~~~~
+*
+* Do not put hints on an object's own `id`.  Hints do not change the
+* identity of a portable URI, since FEP-ef61 drops the query when comparing
+* portable URIs, but implementations that do not canonicalize portable URIs
+* would take a hinted ID for another object.  Add hints before signing the
+* object, since its Object Integrity Proof covers its references too.
+*
+* The hints that the URI already has, including the legacy `gateways`
+* parameter, are replaced.  Each gateway becomes a `@gateway` query
+* parameter whose value is its URI-encoded origin, e.g.,
+* `@gateway=https%3A%2F%2Fserver1.example`, in the given order after the
+* other query parameters.  Duplicate gateways are dropped, and an empty list
+* removes the hints as {@link withoutGatewayHints} does.  The other query
+* parameters, their order, and the fragment are kept, but percent-encoding
+* is normalized the same way as {@link canonicalizePortableUri} does it.
+*
+* Fedify follows at most five hints when dereferencing a portable URI
+* (three for the key ID of an HTTP Signature), so list the preferred
+* gateways first; there is no limit on the number of hints added here.
+*
+* [FEP-ef61]: https://w3id.org/fep/ef61
+*
+* @param portableId The `ap:` or `ap+ef61:` URI.  Pass the raw string rather
+*                   than a `URL` if its path may have `.` or `..` segments,
+*                   because the `URL` class resolves them.
+* @param gateways The gateways, e.g., the `gateways` of the actor that the
+*                 URI refers to.  Each has to be an HTTP(S) origin with no
+*                 credentials, path, query, or fragment.
+* @returns The portable URI with the hints, in the same internal `URL` form
+*          as {@link parseIri} returns.  Use {@link formatIri} to get its
+*          canonical string.
+* @throws {TypeError} If the portable ID is not a valid `ap:` or `ap+ef61:`
+*                     URI, e.g., it is a compatible identifier, which must
+*                     not have location hints; if its path has `.` or `..`
+*                     segments, which the `URL` class cannot represent; or
+*                     if a gateway is invalid.
+* @since 2.4.0
+*/
+declare function withGatewayHints(portableId: string | URL, gateways: Iterable<string | URL>): URL;
+/**
+* Returns a copy of an [FEP-ef61] portable ActivityPub URI without its
+* location hints, i.e., `@gateway` query parameters and the legacy
+* `gateways` parameter.  The other query parameters, their order, and the
+* fragment are kept, but percent-encoding is normalized the same way as
+* {@link canonicalizePortableUri} does it.
+*
+* [FEP-ef61]: https://w3id.org/fep/ef61
+*
+* @param portableId The `ap:` or `ap+ef61:` URI.  Pass the raw string rather
+*                   than a `URL` if its path may have `.` or `..` segments,
+*                   because the `URL` class resolves them.
+* @returns The portable URI without the hints, in the same internal `URL`
+*          form as {@link parseIri} returns.
+* @throws {TypeError} If the portable ID is not a valid `ap:` or `ap+ef61:`
+*                     URI, or if its path has `.` or `..` segments, which
+*                     the `URL` class cannot represent.
+* @since 2.4.0
+*/
+declare function withoutGatewayHints(portableId: string | URL): URL;
+/**
+* Gets the gateways in the `@gateway` location hints of an [FEP-ef61]
+* portable ActivityPub URI, in order.  Hints that are not valid gateways,
+* i.e., HTTP(S) origins with no credentials, path, query, or fragment, are
+* skipped, and so are duplicates.  The legacy `gateways` parameter is not
+* read.
+*
+* Unlike Fedify's dereferencing, which follows at most five hints, this
+* returns all of them.
+*
+* [FEP-ef61]: https://w3id.org/fep/ef61
+*
+* @param portableId The `ap:` or `ap+ef61:` URI.
+* @returns The gateways, e.g., `https://server1.example/`.
+* @throws {TypeError} If the portable ID is not a valid `ap:` or `ap+ef61:`
+*                     URI.
+* @since 2.4.0
+*/
+declare function getGatewayHints(portableId: string | URL): URL[];
+/**
 * Validates a URL to prevent SSRF attacks.
 */
 declare function validatePublicUrl(url: string): Promise<void>;
@@ -616,4 +719,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 FetchPortableMediaOptions, type GetDocumentLoaderOptions, type GetUserAgentOptions, type Json, LanguageString, type ParsedDigestMultibase, type ParsedHashlink, type PortableMedia, type PortableObjectReferrer, type PortableObjectVerification, type PortableObjectVerifier, type PortableObjectVerifierOptions, type PropertyPreprocessor, type PropertyPreprocessorContext, type RemoteDocument, UrlError, arePortableUrisEqual, canParseDecimal, canonicalizePortableUri, computeDigestMultibase, createActivityPubRequest, createHashlink, decodeMultibase, encodeMultibase, encodingFromBaseData, expandIPv6Address, exportDidKey, exportMultibaseKey, exportSpki, fetchPortableMedia, 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, resolveDocumentLoaderTimeout, toCompatibleEf61Id, validatePublicUrl, verifyDigestMultibase, verifyHashlink, withDocumentLoaderTimeout };
+export { type AuthenticatedDocumentLoaderFactory, type CreateRequestOptions, type Decimal, type DidKeyVerificationMethod, type DocumentLoader, type DocumentLoaderFactory, type DocumentLoaderFactoryOptions, type DocumentLoaderOptions, FetchError, type FetchPortableMediaOptions, type GetDocumentLoaderOptions, type GetUserAgentOptions, type Json, LanguageString, type ParsedDigestMultibase, type ParsedHashlink, type PortableMedia, type PortableObjectReferrer, type PortableObjectVerification, type PortableObjectVerifier, type PortableObjectVerifierOptions, type PropertyPreprocessor, type PropertyPreprocessorContext, type RemoteDocument, UrlError, arePortableUrisEqual, canParseDecimal, canonicalizePortableUri, computeDigestMultibase, createActivityPubRequest, createHashlink, decodeMultibase, encodeMultibase, encodingFromBaseData, expandIPv6Address, exportDidKey, exportMultibaseKey, exportSpki, fetchPortableMedia, formatIri, fromCompatibleEf61Id, getDocumentLoader, getFe34Origin, getGatewayHints, getRemoteDocument, getUserAgent, haveSameFe34Origin, haveSameIriOrigin, importDidKey, importMultibaseKey, importPem, importPkcs1, importSpki, isDecimal, isGatewayUrl, isValidPublicIPv4Address, isValidPublicIPv6Address, logRequest, parseDecimal, parseDidKeyVerificationMethod, parseDigestMultibase, parseGatewayUrl, parseHashlink, parseIri, parseJsonLdId, preloadedContexts, resolveDocumentLoaderTimeout, toCompatibleEf61Id, validatePublicUrl, verifyDigestMultibase, verifyHashlink, withDocumentLoaderTimeout, withGatewayHints, withoutGatewayHints };

package/dist/mod.js

@@ -1,6 +1,6 @@
 
 import { t as preloadedContexts } from "./contexts-DPuJ4UYL.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-BfguNa6K.js";
+import { S as withoutGatewayHints, _ as parseIri, a as expandIPv6Address, b as validatePublicUrl, c as getFe34Origin, d as haveSameIriOrigin, f as isGatewayUrl, g as parseGatewayUrl, i as canonicalizePortableUri, l as getGatewayHints, m as isValidPublicIPv6Address, n as UrlError, o as formatIri, p as isValidPublicIPv4Address, r as arePortableUrisEqual, s as fromCompatibleEf61Id, u as haveSameFe34Origin, v as parseJsonLdId, x as withGatewayHints, y as toCompatibleEf61Id } from "./url-CZm2-7ZO.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.2228+6d017d55";
+var version = "2.4.0-dev.2240+79613fa6";
 //#endregion
 //#region src/request.ts
 /**
@@ -1720,4 +1720,4 @@ async function fetchPortableMedia(media, options = {}) {
 	}, options.signal, timeout);
 }
 //#endregion
-export { FetchError, LanguageString, UrlError, arePortableUrisEqual, canParseDecimal, canonicalizePortableUri, computeDigestMultibase, createActivityPubRequest, createHashlink, decodeMultibase, encodeMultibase, encodingFromBaseData, expandIPv6Address, exportDidKey, exportMultibaseKey, exportSpki, fetchPortableMedia, 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, resolveDocumentLoaderTimeout, toCompatibleEf61Id, validatePublicUrl, verifyDigestMultibase, verifyHashlink, withDocumentLoaderTimeout };
+export { FetchError, LanguageString, UrlError, arePortableUrisEqual, canParseDecimal, canonicalizePortableUri, computeDigestMultibase, createActivityPubRequest, createHashlink, decodeMultibase, encodeMultibase, encodingFromBaseData, expandIPv6Address, exportDidKey, exportMultibaseKey, exportSpki, fetchPortableMedia, formatIri, fromCompatibleEf61Id, getDocumentLoader, getFe34Origin, getGatewayHints, getRemoteDocument, getUserAgent, haveSameFe34Origin, haveSameIriOrigin, importDidKey, importMultibaseKey, importPem, importPkcs1, importSpki, isDecimal, isGatewayUrl, isValidPublicIPv4Address, isValidPublicIPv6Address, logRequest, parseDecimal, parseDidKeyVerificationMethod, parseDigestMultibase, parseGatewayUrl, parseHashlink, parseIri, parseJsonLdId, preloadedContexts, resolveDocumentLoaderTimeout, toCompatibleEf61Id, validatePublicUrl, verifyDigestMultibase, verifyHashlink, withDocumentLoaderTimeout, withGatewayHints, withoutGatewayHints };

package/dist/tests/{body-BmNV5g5S.mjs → body-C00dWiYW.mjs}

@@ -1,4 +1,4 @@
-import { t as FetchError } from "./request-2GDEEJng.mjs";
+import { t as FetchError } from "./request-BRPiDcmG.mjs";
 import { getLogger } from "@logtape/logtape";
 //#region src/body.ts
 /** Decoded JSON body limit: 16 MiB.  @internal */

package/dist/tests/{body-BQZL1aJ1.cjs → body-DHk-vT0I.cjs}

@@ -1,4 +1,4 @@
-const require_request = require("./request-Cme6ShRu.cjs");
+const require_request = require("./request-fo2l2yJS.cjs");
 let _logtape_logtape = require("@logtape/logtape");
 //#region src/body.ts
 /** Decoded JSON body limit: 16 MiB.  @internal */

package/dist/tests/body.test.cjs

@@ -1,4 +1,4 @@
-const require_body = require("./body-BQZL1aJ1.cjs");
+const require_body = require("./body-DHk-vT0I.cjs");
 let node_assert_strict = require("node:assert/strict");
 let node_test = require("node:test");
 let node_zlib = require("node:zlib");

package/dist/tests/body.test.mjs

@@ -1,4 +1,4 @@
-import { i as readBoundedText, t as BodyTooLargeError } from "./body-BmNV5g5S.mjs";
+import { i as readBoundedText, t as BodyTooLargeError } from "./body-C00dWiYW.mjs";
 import { deepStrictEqual, ok, rejects } from "node:assert/strict";
 import { test } from "node:test";
 import { gunzipSync, gzipSync } from "node:zlib";

package/dist/tests/decimal.test.cjs

@@ -1,10 +1,10 @@
-require("./url-B6WlNhra.cjs");
-require("./docloader-BnuGCXLg.cjs");
+require("./url-DsMBGqCc.cjs");
+require("./docloader-gX-8knd3.cjs");
 require("./key-C-AYkdJJ.cjs");
 require("./multibase-B5Mea7Ip.cjs");
 require("./digest-3FeH2Y-Q.cjs");
 require("./langstr-C4Fl80ae.cjs");
-require("./portable-media-CFrGpz-3.cjs");
+require("./portable-media-B39cvJGK.cjs");
 let node_test = require("node:test");
 let node_assert = require("node:assert");
 //#region src/decimal.ts

package/dist/tests/decimal.test.mjs

@@ -1,10 +1,10 @@
-import "./url-R9TTZ67B.mjs";
-import "./docloader-ButlYQxr.mjs";
+import "./url-CWC-NI3a.mjs";
+import "./docloader-Bi982uOa.mjs";
 import "./key-C2Db_TAJ.mjs";
 import "./multibase-BPnF_L4e.mjs";
 import "./digest-COC7xDiQ.mjs";
 import "./langstr-CQ26J_L7.mjs";
-import "./portable-media-xFDDMte7.mjs";
+import "./portable-media-l0ET9Pq8.mjs";
 import { test } from "node:test";
 import { deepStrictEqual, throws } from "node:assert";
 //#region src/decimal.ts

package/dist/tests/{docloader-ButlYQxr.mjs → docloader-Bi982uOa.mjs}

@@ -1,8 +1,8 @@
-import { a as name, i as logRequest, n as createActivityPubRequest, o as version, t as FetchError } from "./request-2GDEEJng.mjs";
-import { i as readBoundedText, n as MAX_BODY_SIZE, r as readBoundedBytes, t as BodyTooLargeError } from "./body-BmNV5g5S.mjs";
+import { a as name, i as logRequest, n as createActivityPubRequest, o as version, t as FetchError } from "./request-BRPiDcmG.mjs";
+import { i as readBoundedText, n as MAX_BODY_SIZE, r as readBoundedBytes, t as BodyTooLargeError } from "./body-C00dWiYW.mjs";
 import { t as preloadedContexts } from "./contexts-CIKsin4e.mjs";
 import { t as HttpHeaderLink } from "./link-Cevmc87v.mjs";
-import { t as UrlError, v as validatePublicUrl } from "./url-R9TTZ67B.mjs";
+import { n as UrlError, x as validatePublicUrl } from "./url-CWC-NI3a.mjs";
 import { getLogger } from "@logtape/logtape";
 import { SpanKind, SpanStatusCode, trace } from "@opentelemetry/api";
 //#region src/docloader.ts

package/dist/tests/{docloader-BnuGCXLg.cjs → docloader-gX-8knd3.cjs}

@@ -1,8 +1,8 @@
-const require_request = require("./request-Cme6ShRu.cjs");
-const require_body = require("./body-BQZL1aJ1.cjs");
+const require_request = require("./request-fo2l2yJS.cjs");
+const require_body = require("./body-DHk-vT0I.cjs");
 const require_contexts = require("./contexts-DizzBjz4.cjs");
 const require_link = require("./link-DlKm8bEr.cjs");
-const require_url = require("./url-B6WlNhra.cjs");
+const require_url = require("./url-DsMBGqCc.cjs");
 let _logtape_logtape = require("@logtape/logtape");
 let _opentelemetry_api = require("@opentelemetry/api");
 //#region src/docloader.ts