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

package/dist/tests/{url-B6WlNhra.cjs → url-DsMBGqCc.cjs}

@@ -21,6 +21,26 @@ const INVALID_PERCENT_ENCODING_PATTERN = /%(?![0-9A-Fa-f]{2})/;
 const PERCENT_ENCODING_PATTERN = /%[0-9A-Fa-f]{2}/g;
 const DID_SCHEME_PATTERN = /^did:/i;
 const DID_PATTERN = /^did:[a-z0-9]+:[-A-Za-z0-9._%]+(?::[-A-Za-z0-9._%]+)*$/i;
+const DOT_SEGMENT_PATTERN = /(?:^|\/)(?:\.|%2e){1,2}(?=\/|$)/i;
+function prepareUrlInput(iri) {
+	let prepared = iri.replace(/[\t\n\r]/g, "");
+	while (prepared.length > 0 && prepared.charCodeAt(0) <= 32) prepared = prepared.slice(1);
+	while (prepared.length > 0 && prepared.charCodeAt(prepared.length - 1) <= 32) prepared = prepared.slice(0, -1);
+	return prepared;
+}
+function assertPortablePathCanBeParsed(iri) {
+	const match = prepareUrlInput(iri).match(PORTABLE_IRI_PATTERN);
+	if (match != null && DOT_SEGMENT_PATTERN.test(match[3])) throw new TypeError("Portable ActivityPub IRI paths with dot segments cannot be represented as URLs.");
+}
+function assertCompatiblePathCanBeParsed(raw, parsed) {
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return;
+	const match = prepareUrlInput(raw).match(/^https?:[\/\\]*[^/?#\\]*([^?#]*)/i);
+	if (match == null) return;
+	const rawPath = match[1].replace(/\\/g, "/");
+	const compatiblePath = parsed.pathname.startsWith(COMPATIBLE_ID_PATH_PREFIX) && COMPATIBLE_ID_DID_PATTERN.test(parsed.pathname.slice(COMPATIBLE_ID_PATH_PREFIX.length));
+	const rawCompatiblePath = rawPath.startsWith(COMPATIBLE_ID_PATH_PREFIX) && COMPATIBLE_ID_DID_PATTERN.test(rawPath.slice(COMPATIBLE_ID_PATH_PREFIX.length));
+	if ((compatiblePath || rawCompatiblePath) && DOT_SEGMENT_PATTERN.test(rawPath)) throw new TypeError("FEP-ef61 compatible identifier paths with dot segments cannot be represented as URLs.");
+}
 /**
 * Parses a JSON-LD `@id` value as an IRI.
 */
@@ -34,22 +54,40 @@ function parseJsonLdId(id, base) {
 }
 /**
 * 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.
 */
 function parseIri(iri, base) {
 	if (iri instanceof URL) return normalizePortableUrl(iri) ?? new URL(iri.href);
+	assertPortablePathCanBeParsed(iri);
 	const portable = parsePortableIri(iri);
 	if (portable != null) return portable;
 	base = normalizeBaseIri(base);
 	if (!URL.canParse(iri, base) && iri.startsWith("at://")) return parseAtUri(iri);
 	const parsed = new URL(iri, base);
+	assertCompatiblePathCanBeParsed(iri, parsed);
 	return normalizePortableUrl(parsed) ?? parsed;
 }
 /**
 * 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.
 */
 function formatIri(iri) {
+	if (typeof iri === "string") assertPortablePathCanBeParsed(iri);
 	const parsed = parsePortableIri(iri instanceof URL ? iri.href : iri);
-	if (parsed == null) return iri instanceof URL ? iri.href : URL.canParse(iri) ? new URL(iri).href : iri;
+	if (parsed == null) {
+		if (iri instanceof URL) return iri.href;
+		if (!URL.canParse(iri)) return iri;
+		const url = new URL(iri);
+		assertCompatiblePathCanBeParsed(iri, url);
+		return url.href;
+	}
 	return `ap+ef61://${decodePortableAuthority(parsed.host)}${parsed.pathname}${parsed.search}${parsed.hash}`;
 }
 /**
@@ -169,11 +207,15 @@ function parsePortableIri(iri) {
 }
 function normalizePortableUrl(iri) {
 	if (iri.protocol !== "ap:" && iri.protocol !== "ap+ef61:") return null;
-	return parsePortableIri(`ap+ef61://${iri.host}${iri.pathname}${iri.search}${iri.hash}`);
+	const raw = `ap+ef61://${iri.host}${iri.pathname}${iri.search}${iri.hash}`;
+	assertPortablePathCanBeParsed(raw);
+	return parsePortableIri(raw);
 }
 function normalizeBaseIri(base) {
 	if (base == null) return void 0;
 	if (base instanceof URL) return normalizePortableUrl(base) ?? base;
+	assertPortablePathCanBeParsed(base);
+	if (URL.canParse(base)) assertCompatiblePathCanBeParsed(base, new URL(base));
 	return parsePortableIri(base) ?? (base.startsWith("at://") && !URL.canParse(".", base) ? parseAtUri(base) : base);
 }
 function decodePortableAuthority(authority) {
@@ -240,6 +282,7 @@ function parseGatewayUrl(url) {
 }
 const COMPATIBLE_ID_PATH_PREFIX = "/.well-known/apgateway/";
 const COMPATIBLE_ID_DID_PATTERN = /^did(?::|%3A)/i;
+const RAW_COMPATIBLE_ID_PREFIX_PATTERN = /^(?:[hH][tT][tT][pP][sS]?):\/\/[^/?#]*\/\.well-known\/apgateway\/(?=[dD][iI][dD](?::|%3[aA]))/;
 const LOCATION_HINT_PARAMETERS = /* @__PURE__ */ new Set(["@gateway", "gateways"]);
 /**
 * Converts an [FEP-ef61] compatible identifier into a portable ActivityPub
@@ -275,8 +318,9 @@ const LOCATION_HINT_PARAMETERS = /* @__PURE__ */ new Set(["@gateway", "gateways"
 *                     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
 */
 function fromCompatibleEf61Id(input) {
@@ -284,18 +328,29 @@ function fromCompatibleEf61Id(input) {
 }
 function convertCompatibleEf61Id(input) {
 	let url;
+	const rawPrefix = typeof input === "string" ? input.match(RAW_COMPATIBLE_ID_PREFIX_PATTERN) : null;
 	if (input instanceof URL) url = input;
 	else if (typeof input === "string" && URL.canParse(input)) url = new URL(input);
 	else return null;
 	if (url.protocol !== "http:" && url.protocol !== "https:") return null;
-	if (!url.pathname.startsWith(COMPATIBLE_ID_PATH_PREFIX)) return null;
+	if (typeof input === "string" && rawPrefix == null) {
+		if (url.pathname.startsWith(COMPATIBLE_ID_PATH_PREFIX) && COMPATIBLE_ID_DID_PATTERN.test(url.pathname.slice(23))) throw new TypeError("Invalid FEP-ef61 compatible identifier.");
+	}
+	if (!url.pathname.startsWith(COMPATIBLE_ID_PATH_PREFIX)) {
+		if (rawPrefix != null) throw new TypeError("Invalid FEP-ef61 compatible identifier.");
+		return null;
+	}
 	const tail = url.pathname.slice(23);
-	if (!COMPATIBLE_ID_DID_PATTERN.test(tail)) return null;
+	if (!COMPATIBLE_ID_DID_PATTERN.test(tail)) {
+		if (rawPrefix != null) throw new TypeError("Invalid FEP-ef61 compatible identifier.");
+		return null;
+	}
 	if (url.username !== "" || url.password !== "") throw new TypeError("Invalid FEP-ef61 compatible identifier: credentials are not allowed.");
 	const iri = "ap+ef61://" + url.href.slice(url.origin.length + 23);
 	try {
 		const parsed = parsePortableIri(iri);
 		if (parsed == null) throw new TypeError("Not a portable IRI.");
+		if (typeof input === "string" && rawPrefix != null && canonicalizePortableUri("ap://" + input.slice(rawPrefix[0].length)) !== canonicalizePortableUri(iri)) throw new TypeError("URL parsing changed the portable identifier.");
 		canonicalizePortableUri(iri);
 		if ((url.search === "" ? [] : normalizePortableComponent(url.search.slice(1)).split("&")).some(isLocationHint)) throw new TypeError("Location hints are not allowed.");
 		return {
@@ -335,7 +390,8 @@ function convertCompatibleEf61Id(input) {
 * @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
@@ -385,6 +441,166 @@ function isLocationHint(pair) {
 	}
 }
 /**
+* The name of the FEP-ef61 location hint query parameter.
+* @internal
+*/
+const GATEWAY_HINT_PARAMETER = "@gateway";
+/**
+* Parses an FEP-ef61 gateway, which has to be an HTTP(S) origin with no
+* credentials, path, query, or fragment.
+* @returns The gateway, or `null` if it is not a valid gateway.
+* @internal
+*/
+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;
+	return isGatewayUrl(url) ? url : null;
+}
+/**
+* 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
+*/
+function withGatewayHints(portableId, gateways) {
+	const parts = splitPortableIri(portableId);
+	if (typeof gateways === "string") throw new TypeError("The gateways must be an iterable of gateways, not a string.");
+	const hints = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const gateway of gateways) {
+		const url = parseGatewayOrigin(gateway);
+		if (url == null) throw new TypeError("FEP-ef61 gateways must be HTTP(S) origins with no credentials, path, query, or fragment: " + String(gateway));
+		if (seen.has(url.href)) continue;
+		seen.add(url.href);
+		hints.push(url);
+	}
+	return replaceGatewayHints(parts, hints);
+}
+/**
+* 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
+*/
+function withoutGatewayHints(portableId) {
+	return replaceGatewayHints(splitPortableIri(portableId), []);
+}
+/**
+* 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
+*/
+function getGatewayHints(portableId) {
+	const { query } = splitPortableIri(portableId);
+	return query == null ? [] : parseGatewayHints(query);
+}
+function splitPortableIri(portableId) {
+	const raw = getRawPortableIri(portableId);
+	const match = raw.match(PORTABLE_IRI_PATTERN);
+	const parsed = parsePortableIri(raw);
+	if (match == null || parsed == null) throw new TypeError("Invalid portable ActivityPub IRI.");
+	return {
+		raw,
+		parsed,
+		path: normalizePortableComponent(match[3]),
+		query: match[4] == null ? null : normalizePortableComponent(match[4].slice(1)),
+		fragment: match[5] == null ? "" : normalizePortableComponent(match[5])
+	};
+}
+function parseGatewayHints(query) {
+	const hints = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const hint of new URLSearchParams(`?${query}`).getAll(GATEWAY_HINT_PARAMETER)) {
+		const url = parseGatewayOrigin(hint);
+		if (url == null || seen.has(url.href)) continue;
+		seen.add(url.href);
+		hints.push(url);
+	}
+	return hints;
+}
+function replaceGatewayHints(parts, hints) {
+	const pairs = parts.query == null ? [] : parts.query.split("&").filter((pair) => pair !== "" && !isLocationHint(pair));
+	for (const hint of hints) pairs.push(`${GATEWAY_HINT_PARAMETER}=${encodeURIComponent(hint.origin)}`);
+	const query = pairs.length < 1 ? "" : `?${pairs.join("&")}`;
+	const result = parsePortableIri(`ap+ef61://${parts.parsed.host}${parts.path}${query}${parts.fragment}`);
+	if (result == null || canonicalizePortableUri(result.href) !== canonicalizePortableUri(parts.raw) || parseGatewayHints(result.search.slice(1)).map((url) => url.href).join(" ") !== hints.map((url) => url.href).join(" ")) throw new TypeError("The portable ActivityPub IRI cannot be represented as a URL without changing the object it refers to.");
+	return result;
+}
+/**
 * Validates a URL to prevent SSRF attacks.
 */
 async function validatePublicUrl(url) {
@@ -580,6 +796,12 @@ function matchesIPv6Prefix(address, prefixWords, prefixLength) {
 	return true;
 }
 //#endregion
+Object.defineProperty(exports, "GATEWAY_HINT_PARAMETER", {
+	enumerable: true,
+	get: function() {
+		return GATEWAY_HINT_PARAMETER;
+	}
+});
 Object.defineProperty(exports, "UrlError", {
 	enumerable: true,
 	get: function() {
@@ -622,6 +844,12 @@ Object.defineProperty(exports, "getFe34Origin", {
 		return getFe34Origin;
 	}
 });
+Object.defineProperty(exports, "getGatewayHints", {
+	enumerable: true,
+	get: function() {
+		return getGatewayHints;
+	}
+});
 Object.defineProperty(exports, "haveSameFe34Origin", {
 	enumerable: true,
 	get: function() {
@@ -652,6 +880,12 @@ Object.defineProperty(exports, "isValidPublicIPv6Address", {
 		return isValidPublicIPv6Address;
 	}
 });
+Object.defineProperty(exports, "parseGatewayOrigin", {
+	enumerable: true,
+	get: function() {
+		return parseGatewayOrigin;
+	}
+});
 Object.defineProperty(exports, "parseGatewayUrl", {
 	enumerable: true,
 	get: function() {
@@ -688,3 +922,15 @@ Object.defineProperty(exports, "validatePublicUrl", {
 		return validatePublicUrl;
 	}
 });
+Object.defineProperty(exports, "withGatewayHints", {
+	enumerable: true,
+	get: function() {
+		return withGatewayHints;
+	}
+});
+Object.defineProperty(exports, "withoutGatewayHints", {
+	enumerable: true,
+	get: function() {
+		return withoutGatewayHints;
+	}
+});

package/dist/tests/url.test.cjs

@@ -1,4 +1,4 @@
-const require_url = require("./url-B6WlNhra.cjs");
+const require_url = require("./url-DsMBGqCc.cjs");
 let node_test = require("node:test");
 let node_assert = require("node:assert");
 //#region src/url.test.ts
@@ -11,6 +11,39 @@ let node_assert = require("node:assert");
 		"AP+EF61://did:key:z6Mkabc/actor"
 	]) (0, node_assert.deepStrictEqual)(require_url.parseIri(iri), new URL("ap+ef61://did%3Akey%3Az6Mkabc/actor"));
 });
+(0, node_test.test)("portable URI parsing refuses dot segments before URL normalization", () => {
+	const base = "ap://did:key:z6Mkabc";
+	for (const segment of [
+		".",
+		"..",
+		"%2e",
+		".%2E",
+		"%2e.",
+		"%2E%2e"
+	]) for (const path of [
+		`/${segment}`,
+		`/a/${segment}/b`,
+		`/a/${segment}`
+	]) {
+		const iri = base + path;
+		(0, node_assert.throws)(() => require_url.parseIri(iri), TypeError, iri);
+		(0, node_assert.throws)(() => require_url.parseJsonLdId(iri), TypeError, iri);
+		(0, node_assert.throws)(() => require_url.formatIri(iri), TypeError, iri);
+	}
+	for (const iri of [
+		`${base}/a/.\t./b`,
+		`${base}/a/..\n/b`,
+		` ${base}/a/../b`,
+		`${base}/a/.. `
+	]) (0, node_assert.throws)(() => require_url.parseIri(iri), TypeError, iri);
+	for (const path of [
+		"/a/.../b",
+		"/a/.x/b",
+		"/a/x.y/b",
+		"/a/%252e/b"
+	]) (0, node_assert.deepStrictEqual)(require_url.formatIri(require_url.parseIri(base + path)), `ap+ef61://did:key:z6Mkabc${path}`);
+	(0, node_assert.throws)(() => require_url.parseIri("child", `${base}/a/../b`), TypeError);
+});
 (0, node_test.test)("parseIri() normalizes DID scheme and method casing", () => {
 	for (const iri of [
 		"ap://DID:key:z6Mkabc/actor",
@@ -44,6 +77,20 @@ let node_assert = require("node:assert");
 	(0, node_assert.deepStrictEqual)(require_url.parseIri("attachments/1", "ap://did:key:z6Mkabc/objects/1"), new URL("ap+ef61://did%3Akey%3Az6Mkabc/objects/attachments/1"));
 	(0, node_assert.throws)(() => require_url.parseIri("//example.com/outbox", "ap://did:key:z6Mkabc/objects/1"), TypeError);
 });
+(0, node_test.test)("parseIri() rejects lossy compatible ID string bases", () => {
+	const base = "https://server.example/.well-known/apgateway/did:key:z6MkAlice";
+	for (const segment of [
+		".",
+		"..",
+		"%2e",
+		"%2e%2e"
+	]) {
+		const rawBase = `${base}/a/${segment}/b`;
+		(0, node_assert.throws)(() => require_url.parseIri("child", rawBase), TypeError, rawBase);
+		(0, node_assert.throws)(() => require_url.parseJsonLdId("child", rawBase), TypeError, rawBase);
+	}
+	(0, node_assert.deepStrictEqual)(require_url.parseIri("child", "https://server.example/a/../b"), new URL("https://server.example/child"));
+});
 (0, node_test.test)("parseIri() resolves relative IRIs against at:// string bases", () => {
 	(0, node_assert.deepStrictEqual)(require_url.parseIri("/record", "at://did:plc:example/collection/item"), new URL("at://did%3Aplc%3Aexample/record"));
 	(0, node_assert.deepStrictEqual)(require_url.parseIri("reply", "at://did:plc:example/collection/item"), new URL("at://did%3Aplc%3Aexample/collection/reply"));
@@ -316,6 +363,32 @@ let node_assert = require("node:assert");
 		"https://user@server.example/.well-known/apgateway/did:key:z6MkAlice/a"
 	]) (0, node_assert.throws)(() => require_url.fromCompatibleEf61Id(input), TypeError, input);
 });
+(0, node_test.test)("fromCompatibleEf61Id() refuses raw paths changed by URL parsing", () => {
+	const base = "https://server.example/.well-known/apgateway/did:key:z6MkAlice";
+	for (const path of [
+		"/a/../b",
+		"/a/%2e%2E/b",
+		"/a/.	./b",
+		"/a/.. "
+	]) {
+		(0, node_assert.throws)(() => require_url.fromCompatibleEf61Id(base + path), TypeError, path);
+		(0, node_assert.throws)(() => require_url.parseIri(base + path), TypeError, path);
+		(0, node_assert.throws)(() => require_url.formatIri(base + path), TypeError, path);
+	}
+	for (const input of [
+		"https:/server.example/.well-known/apgateway/did:key:z6MkAlice/a/../b",
+		"https:server.example/.well-known/apgateway/did:key:z6MkAlice/a/../b",
+		"https:\\\\server.example\\.well-known\\apgateway\\did:key:z6MkAlice\\a\\..\\b",
+		` ${base}/../../other`
+	]) {
+		(0, node_assert.throws)(() => require_url.parseIri(input), TypeError, input);
+		(0, node_assert.throws)(() => require_url.formatIri(input), TypeError, input);
+	}
+	(0, node_assert.throws)(() => require_url.fromCompatibleEf61Id(` ${base}/actor`), TypeError);
+	(0, node_assert.throws)(() => require_url.fromCompatibleEf61Id(`https://server.example/foo/../.well-known/apgateway/did:key:z6MkAlice/actor`), TypeError);
+	(0, node_assert.deepStrictEqual)(require_url.fromCompatibleEf61Id(`${base}/a/%252e/b`)?.pathname, "/a/%252e/b");
+	(0, node_assert.deepStrictEqual)(require_url.fromCompatibleEf61Id("https://server.example/.WELL-KNOWN/apgateway/did:key:z6MkAlice/actor"), null);
+});
 (0, node_test.test)("toCompatibleEf61Id() converts portable URIs", () => {
 	const cases = [
 		[
@@ -620,4 +693,122 @@ let node_assert = require("node:assert");
 	(0, node_assert.deepStrictEqual)(require_url.expandIPv6Address("2001:db8::1"), "2001:0db8:0000:0000:0000:0000:0000:0001");
 	(0, node_assert.deepStrictEqual)(require_url.expandIPv6Address("64:ff9b::8.8.8.8"), "0064:ff9b:0000:0000:0000:0000:0808:0808");
 });
+(0, node_test.test)("withGatewayHints() adds @gateway location hints", () => {
+	const expected = "ap+ef61://did:key:z6Mkabc/actor?@gateway=https%3A%2F%2Fserver1.example&@gateway=https%3A%2F%2Fserver2.example";
+	for (const id of [
+		"ap://did:key:z6Mkabc/actor",
+		"ap+ef61://did:key:z6Mkabc/actor",
+		"ap://did%3Akey%3Az6Mkabc/actor",
+		require_url.parseIri("ap://did:key:z6Mkabc/actor"),
+		new URL("ap://did%3Akey%3Az6Mkabc/actor")
+	]) {
+		const hinted = require_url.withGatewayHints(id, ["https://server1.example", new URL("https://server2.example/")]);
+		(0, node_assert.ok)(hinted instanceof URL);
+		(0, node_assert.strictEqual)(hinted.href, "ap+ef61://did%3Akey%3Az6Mkabc/actor?@gateway=https%3A%2F%2Fserver1.example&@gateway=https%3A%2F%2Fserver2.example");
+		(0, node_assert.strictEqual)(require_url.formatIri(hinted), expected);
+		(0, node_assert.deepStrictEqual)(require_url.parseIri(require_url.formatIri(hinted)), hinted);
+	}
+});
+(0, node_test.test)("withGatewayHints() encodes and deduplicates gateway origins", () => {
+	function* gateways() {
+		yield "https://A.example:443";
+		yield "https://a.example/";
+		yield new URL("https://a.example");
+		yield "https://b.example:8443";
+		yield "http://c.example:80/";
+		yield "https://例え.jp";
+	}
+	(0, node_assert.strictEqual)(require_url.formatIri(require_url.withGatewayHints("ap://did:key:z6Mkabc/actor", gateways())), "ap+ef61://did:key:z6Mkabc/actor?@gateway=https%3A%2F%2Fa.example&@gateway=https%3A%2F%2Fb.example%3A8443&@gateway=http%3A%2F%2Fc.example&@gateway=https%3A%2F%2Fxn--r8jz45g.jp");
+	(0, node_assert.strictEqual)(require_url.formatIri(require_url.withGatewayHints("ap://did:key:z6Mkabc/actor", /* @__PURE__ */ new Set(["https://b.example", "https://a.example"]))), "ap+ef61://did:key:z6Mkabc/actor?@gateway=https%3A%2F%2Fb.example&@gateway=https%3A%2F%2Fa.example");
+	const many = Array.from({ length: 7 }, (_, i) => `https://server${i}.example`);
+	(0, node_assert.deepStrictEqual)(require_url.getGatewayHints(require_url.withGatewayHints("ap://did:key:z6Mkabc/actor", many)).map((url) => url.origin), many);
+});
+(0, node_test.test)("withGatewayHints() keeps other query parameters and fragments", () => {
+	(0, node_assert.strictEqual)(require_url.formatIri(require_url.withGatewayHints("ap://did:key:z6Mkabc/collection?page=3&maxItems=20&q=a+b%20c%2b", ["https://server.example"])), "ap+ef61://did:key:z6Mkabc/collection?page=3&maxItems=20&q=a+b%20c%2B&@gateway=https%3A%2F%2Fserver.example");
+	(0, node_assert.strictEqual)(require_url.formatIri(require_url.withGatewayHints("ap://did:key:z6Mkabc/actor?x=%26%3D#main-key", ["https://server.example"])), "ap+ef61://did:key:z6Mkabc/actor?x=%26%3D&@gateway=https%3A%2F%2Fserver.example#main-key");
+	(0, node_assert.strictEqual)(require_url.withGatewayHints("ap://did:key:z6Mkabc/actor#", ["https://s.example"]).href, "ap+ef61://did%3Akey%3Az6Mkabc/actor?@gateway=https%3A%2F%2Fs.example#");
+});
+(0, node_test.test)("withGatewayHints() replaces existing location hints", () => {
+	(0, node_assert.strictEqual)(require_url.formatIri(require_url.withGatewayHints("ap://did:key:z6Mkabc/collection?@gateway=https%3A%2F%2Fold.example&page=2&%40gateway=https%3A%2F%2Fold2.example&@gateway&gateways=https%3A%2F%2Flegacy.example&%2540gateway=kept", ["https://new.example"])), "ap+ef61://did:key:z6Mkabc/collection?page=2&%2540gateway=kept&@gateway=https%3A%2F%2Fnew.example");
+	for (const char of [
+		"	",
+		"\n",
+		"\r"
+	]) (0, node_assert.deepStrictEqual)(require_url.getGatewayHints(require_url.withGatewayHints(`ap://did:key:z6Mkabc/actor?@gate${char}way=https%3A%2F%2Fevil.example`, ["https://new.example"])).map((url) => url.href), ["https://new.example/"]);
+});
+(0, node_test.test)("withGatewayHints() with no gateways removes location hints", () => {
+	for (const [input, expected] of [
+		["ap://did:key:z6Mkabc/actor?@gateway=https%3A%2F%2Fa.example", "ap+ef61://did%3Akey%3Az6Mkabc/actor"],
+		["ap://did:key:z6Mkabc/actor?&@gateway=https%3A%2F%2Fa.example&&p=1&", "ap+ef61://did%3Akey%3Az6Mkabc/actor?p=1"],
+		["ap://did:key:z6Mkabc/actor?", "ap+ef61://did%3Akey%3Az6Mkabc/actor"],
+		["ap://did:key:z6Mkabc/actor?gateways=https%3A%2F%2Fa.example#k", "ap+ef61://did%3Akey%3Az6Mkabc/actor#k"]
+	]) {
+		(0, node_assert.strictEqual)(require_url.withGatewayHints(input, []).href, expected, input);
+		(0, node_assert.strictEqual)(require_url.withoutGatewayHints(input).href, expected, input);
+	}
+	const input = require_url.parseIri("ap://did:key:z6Mkabc/actor?@gateway=https%3A%2F%2Fa.example");
+	const href = input.href;
+	require_url.withoutGatewayHints(input);
+	(0, node_assert.strictEqual)(input.href, href);
+});
+(0, node_test.test)("withGatewayHints() rejects non-portable IDs", () => {
+	for (const id of [
+		"https://server.example/.well-known/apgateway/did:key:z6Mkabc/actor",
+		"https://example.com/actor",
+		"did:key:z6Mkabc#z6Mkabc",
+		"ap://did:key:z6Mkabc",
+		"ap://example.com/actor",
+		"ap://did:key:z6Mkabc/actor%zz",
+		new URL("https://example.com/actor"),
+		new URL("ap://did%3Akey%3Az6Mkabc:8080/actor"),
+		new URL("ap://user@did%3Akey%3Az6Mkabc/actor")
+	]) {
+		(0, node_assert.throws)(() => require_url.withGatewayHints(id, ["https://server.example"]), TypeError, String(id));
+		(0, node_assert.throws)(() => require_url.withoutGatewayHints(id), TypeError, String(id));
+		(0, node_assert.throws)(() => require_url.getGatewayHints(id), TypeError, String(id));
+	}
+});
+(0, node_test.test)("withGatewayHints() rejects paths that URLs cannot represent", () => {
+	for (const id of [
+		"ap://did:key:z6Mkabc/a/../actor",
+		"ap://did:key:z6Mkabc/a/./actor",
+		"ap://did:key:z6Mkabc/a/%2e%2e/actor",
+		"ap://did:key:z6Mkabc/a/%2E/actor"
+	]) {
+		(0, node_assert.throws)(() => require_url.withGatewayHints(id, ["https://server.example"]), TypeError, id);
+		(0, node_assert.throws)(() => require_url.withoutGatewayHints(id), TypeError, id);
+	}
+	(0, node_assert.strictEqual)(require_url.withoutGatewayHints("ap://did:key:z6Mkabc/a	b").href, "ap+ef61://did%3Akey%3Az6Mkabc/a%09b");
+});
+(0, node_test.test)("withGatewayHints() rejects invalid gateways", () => {
+	for (const gateway of [
+		"https://server.example/path",
+		"https://server.example/?",
+		"https://server.example/#",
+		"https://server.example/?q=1",
+		"https://user:pass@server.example",
+		"ftp://server.example",
+		"ap://did:key:z6Mkabc/actor",
+		"server.example",
+		new URL("https://server.example/path")
+	]) (0, node_assert.throws)(() => require_url.withGatewayHints("ap://did:key:z6Mkabc/actor", [gateway]), TypeError, String(gateway));
+	(0, node_assert.throws)(() => require_url.withGatewayHints("ap://did:key:z6Mkabc/actor", "https://server.example"), TypeError);
+});
+(0, node_test.test)("getGatewayHints() reads @gateway location hints", () => {
+	(0, node_assert.deepStrictEqual)(require_url.getGatewayHints("ap://did:key:z6Mkabc/actor?@gateway=https%3A%2F%2Fa.example&@gateway=invalid&%40gateway=https%3A%2F%2Fb.example%2F&@gateway=https%3A%2F%2Fa.example%2F&@gateway=https%3A%2F%2Fc.example%2Fpath&gateways=https%3A%2F%2Flegacy.example&page=1#k").map((url) => url.href), ["https://a.example/", "https://b.example/"]);
+	(0, node_assert.deepStrictEqual)(require_url.getGatewayHints("ap://did:key:z6Mkabc/actor"), []);
+	const questioned = "ap://did:key:z6Mkabc/actor??@gateway=https%3A%2F%2Fa.example";
+	(0, node_assert.deepStrictEqual)(require_url.getGatewayHints(questioned), []);
+	(0, node_assert.strictEqual)(require_url.withoutGatewayHints(questioned).href, "ap+ef61://did%3Akey%3Az6Mkabc/actor??@gateway=https%3A%2F%2Fa.example");
+	(0, node_assert.deepStrictEqual)(require_url.getGatewayHints(require_url.withGatewayHints(questioned, ["https://b.example"])).map((url) => url.href), ["https://b.example/"]);
+	(0, node_assert.deepStrictEqual)(require_url.getGatewayHints("ap://did:key:z6Mkabc/actor?@gate%09way=https%3A%2F%2Fa.example"), []);
+	(0, node_assert.deepStrictEqual)(require_url.getGatewayHints("ap://did:key:z6Mkabc/actor?@gate	way=https%3A%2F%2Fa.example"), []);
+});
+(0, node_test.test)("withGatewayHints() round-trips with other portable ID helpers", () => {
+	const hinted = require_url.withGatewayHints("ap://did:key:z6Mkabc/objects/1#frag", ["https://server1.example", "https://server2.example"]);
+	(0, node_assert.strictEqual)(require_url.canonicalizePortableUri(require_url.formatIri(hinted)), "ap+ef61://did:key:z6Mkabc/objects/1#frag");
+	(0, node_assert.ok)(require_url.arePortableUrisEqual(require_url.formatIri(hinted), "ap://did:key:z6Mkabc/objects/1#frag"));
+	(0, node_assert.strictEqual)(require_url.toCompatibleEf61Id(hinted, "https://server1.example").href, "https://server1.example/.well-known/apgateway/did:key:z6Mkabc/objects/1#frag");
+	(0, node_assert.strictEqual)(require_url.formatIri(require_url.withoutGatewayHints(hinted)), "ap+ef61://did:key:z6Mkabc/objects/1#frag");
+});
 //#endregion