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

package/deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/vocab-runtime",
-  "version": "2.4.0-dev.2228+6d017d55",
+  "version": "2.4.0-dev.2233+abb4a6b2",
   "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"
   }
 }

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-BHfQuRdy.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-DqqDZY9i.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-BHfQuRdy.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",
@@ -359,15 +358,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 +378,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-DqqDZY9i.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",
@@ -364,7 +363,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 +377,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-BHfQuRdy.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.2233+abb4a6b2";
 //#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

@@ -610,6 +610,98 @@ declare function fromCompatibleEf61Id(input: string | URL): URL | null;
 */
 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 +709,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

@@ -609,6 +609,98 @@ declare function fromCompatibleEf61Id(input: string | URL): URL | null;
 */
 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 +708,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-DqqDZY9i.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.2233+abb4a6b2";
 //#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-BEYUpKvX.mjs}

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

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

@@ -1,4 +1,4 @@
-const require_request = require("./request-Cme6ShRu.cjs");
+const require_request = require("./request-BQlkB8du.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-DQKTFMsH.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-BEYUpKvX.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-CtHyzMR4.cjs");
+require("./docloader-DHCYdBXf.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-DHaAEpaQ.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-Cdu4ASgJ.mjs";
+import "./docloader-ra1lbBfP.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-1NjUQari.mjs";
 import { test } from "node:test";
 import { deepStrictEqual, throws } from "node:assert";
 //#region src/decimal.ts

package/dist/tests/{docloader-BnuGCXLg.cjs → docloader-DHCYdBXf.cjs}

@@ -1,8 +1,8 @@
-const require_request = require("./request-Cme6ShRu.cjs");
-const require_body = require("./body-BQZL1aJ1.cjs");
+const require_request = require("./request-BQlkB8du.cjs");
+const require_body = require("./body-DQKTFMsH.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-CtHyzMR4.cjs");
 let _logtape_logtape = require("@logtape/logtape");
 let _opentelemetry_api = require("@opentelemetry/api");
 //#region src/docloader.ts

package/dist/tests/{docloader-ButlYQxr.mjs → docloader-ra1lbBfP.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-D3elVRyB.mjs";
+import { i as readBoundedText, n as MAX_BODY_SIZE, r as readBoundedBytes, t as BodyTooLargeError } from "./body-BEYUpKvX.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-Cdu4ASgJ.mjs";
 import { getLogger } from "@logtape/logtape";
 import { SpanKind, SpanStatusCode, trace } from "@opentelemetry/api";
 //#region src/docloader.ts

package/dist/tests/docloader.test.cjs

@@ -1,8 +1,8 @@
 const require_rolldown_runtime = require("./rolldown-runtime-emK7D4bc.cjs");
-const require_request = require("./request-Cme6ShRu.cjs");
+const require_request = require("./request-BQlkB8du.cjs");
 const require_contexts = require("./contexts-DizzBjz4.cjs");
-const require_url = require("./url-B6WlNhra.cjs");
-const require_docloader = require("./docloader-BnuGCXLg.cjs");
+const require_url = require("./url-CtHyzMR4.cjs");
+const require_docloader = require("./docloader-DHCYdBXf.cjs");
 let node_test = require("node:test");
 let node_zlib = require("node:zlib");
 let _logtape_logtape = require("@logtape/logtape");

package/dist/tests/docloader.test.mjs

@@ -1,7 +1,7 @@
-import { t as FetchError } from "./request-2GDEEJng.mjs";
+import { t as FetchError } from "./request-D3elVRyB.mjs";
 import { n as cid_v1_default, t as preloadedContexts } from "./contexts-CIKsin4e.mjs";
-import { t as UrlError } from "./url-R9TTZ67B.mjs";
-import { i as withDocumentLoaderTimeout, n as getRemoteDocument, r as resolveDocumentLoaderTimeout, t as getDocumentLoader } from "./docloader-ButlYQxr.mjs";
+import { n as UrlError } from "./url-Cdu4ASgJ.mjs";
+import { i as withDocumentLoaderTimeout, n as getRemoteDocument, r as resolveDocumentLoaderTimeout, t as getDocumentLoader } from "./docloader-ra1lbBfP.mjs";
 import { test } from "node:test";
 import { gzipSync } from "node:zlib";
 import { configure, reset } from "@logtape/logtape";

package/dist/tests/internal/portable-dereference.test.cjs

@@ -1,6 +1,6 @@
 const require_contexts = require("../contexts-DizzBjz4.cjs");
-const require_url = require("../url-B6WlNhra.cjs");
-const require_jsonld_cache = require("../jsonld-cache-CXA76Xi6.cjs");
+const require_url = require("../url-CtHyzMR4.cjs");
+const require_jsonld_cache = require("../jsonld-cache-BTgizq9A.cjs");
 let node_assert_strict = require("node:assert/strict");
 let node_test = require("node:test");
 let _logtape_logtape = require("@logtape/logtape");
@@ -17,7 +17,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",
@@ -55,15 +54,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,
@@ -75,14 +74,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
@@ -183,6 +174,16 @@ const hrefs = (urls) => urls.map((url) => url.href);
 		4
 	].map((i) => `https://g${i}.example/`));
 });
+(0, node_test.test)("getPortableGatewayCandidates() reads hints from withGatewayHints()", () => {
+	const gateways = Array.from({ length: 7 }, (_, i) => `https://g${i}.example`);
+	(0, node_assert_strict.deepStrictEqual)(hrefs(getPortableGatewayCandidates(require_url.withGatewayHints("ap://did:key:z6Mkabc/actor?page=1", gateways))), [
+		0,
+		1,
+		2,
+		3,
+		4
+	].map((i) => `https://g${i}.example/`));
+});
 (0, node_test.test)("createSnapshotContextLoader() does not nest released snapshots", async () => {
 	const calls = [];
 	const base = (url) => {

package/dist/tests/internal/portable-dereference.test.mjs

@@ -1,6 +1,6 @@
 import { t as preloadedContexts } from "../contexts-CIKsin4e.mjs";
-import { a as formatIri, m as parseIri, u as isGatewayUrl } from "../url-R9TTZ67B.mjs";
-import { n as createScopedContextLoader, o as registerDocumentLoaderWrapper, s as unwrapReleasedDocumentLoader } from "../jsonld-cache-C7mkqjiE.mjs";
+import { S as withGatewayHints, _ as parseIri, h as parseGatewayOrigin, o as formatIri, t as GATEWAY_HINT_PARAMETER } from "../url-Cdu4ASgJ.mjs";
+import { n as createScopedContextLoader, o as registerDocumentLoaderWrapper, s as unwrapReleasedDocumentLoader } from "../jsonld-cache-BKrsWPCQ.mjs";
 import { deepStrictEqual, ok, throws } from "node:assert/strict";
 import { test } from "node:test";
 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",
@@ -61,7 +60,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) {
@@ -75,14 +74,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
@@ -183,6 +174,16 @@ test("getPortableGatewayCandidates() reads @gateway hints", () => {
 		4
 	].map((i) => `https://g${i}.example/`));
 });
+test("getPortableGatewayCandidates() reads hints from withGatewayHints()", () => {
+	const gateways = Array.from({ length: 7 }, (_, i) => `https://g${i}.example`);
+	deepStrictEqual(hrefs(getPortableGatewayCandidates(withGatewayHints("ap://did:key:z6Mkabc/actor?page=1", gateways))), [
+		0,
+		1,
+		2,
+		3,
+		4
+	].map((i) => `https://g${i}.example/`));
+});
 test("createSnapshotContextLoader() does not nest released snapshots", async () => {
 	const calls = [];
 	const base = (url) => {