@fedify/vocab-runtime 2.4.0-pr.936.41 → 2.4.1

package/dist/tests/url.test.cjs

@@ -1,7 +1,6 @@
-require("./chunk-C2EiDwsr.cjs");
-const require_url = require("./url-CsOV_B_P.cjs");
-let node_assert = require("node:assert");
+const require_url = require("./url-BNakuZ8k.cjs");
 let node_test = require("node:test");
+let node_assert = require("node:assert");
 //#region src/url.test.ts
 (0, node_test.test)("parseIri() accepts portable ActivityPub URI schemes", () => {
 	for (const iri of [
@@ -12,6 +11,39 @@ let node_test = require("node:test");
 		"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",
@@ -45,6 +77,20 @@ let node_test = require("node:test");
 	(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"));
@@ -229,7 +275,11 @@ let node_test = require("node:test");
 	(0, node_assert.deepStrictEqual)(require_url.formatIri(parsed), "ap+ef61://did:web:example.com%00/u/1");
 });
 (0, node_test.test)("parseGatewayUrl() accepts only HTTP(S) base URIs", () => {
-	for (const url of ["https://server.example/", "http://server.example/"]) {
+	for (const url of [
+		"https://server.example",
+		"https://server.example/",
+		"http://server.example/"
+	]) {
 		(0, node_assert.deepStrictEqual)(require_url.parseGatewayUrl(url), new URL(url));
 		(0, node_assert.ok)(require_url.isGatewayUrl(new URL(url)));
 	}
@@ -239,11 +289,287 @@ let node_test = require("node:test");
 		"https://user@server.example/",
 		"https://server.example/path",
 		"https://server.example/?x=1",
-		"https://server.example/#fragment"
+		"https://server.example/?",
+		"https://server.example/#fragment",
+		"https://server.example/#"
 	]) {
-		(0, node_assert.throws)(() => require_url.parseGatewayUrl(url), TypeError);
+		(0, node_assert.throws)(() => require_url.parseGatewayUrl(url), (error) => error instanceof TypeError && error.message.startsWith("Invalid FEP-ef61 gateway: "));
 		(0, node_assert.ok)(!require_url.isGatewayUrl(new URL(url)));
 	}
+	const mutated = new URL("https://server.example/");
+	mutated.search = "?";
+	(0, node_assert.ok)(!require_url.isGatewayUrl(mutated));
+	mutated.search = "";
+	mutated.hash = "#";
+	(0, node_assert.ok)(!require_url.isGatewayUrl(mutated));
+});
+(0, node_test.test)("fromCompatibleEf61Id() converts compatible identifiers", () => {
+	for (const [input, expected] of [
+		["https://server.example/.well-known/apgateway/did:key:z6MkAlice/objects/1", "ap+ef61://did%3Akey%3Az6MkAlice/objects/1"],
+		["http://server.example:8080/.well-known/apgateway/did:key:z6MkAlice/actor", "ap+ef61://did%3Akey%3Az6MkAlice/actor"],
+		["https://server.example/.well-known/apgateway/did%3Akey%3Az6MkAlice/actor", "ap+ef61://did%3Akey%3Az6MkAlice/actor"],
+		["https://server.example/.well-known/apgateway/DID:key:z6MkAlice/actor", "ap+ef61://did%3Akey%3Az6MkAlice/actor"],
+		["https://server.example/.well-known/apgateway/did:key:z6MkAlice/a/b/c", "ap+ef61://did%3Akey%3Az6MkAlice/a/b/c"],
+		["https://server.example/.well-known/apgateway/did:key:z6MkAlice/actor#main-key", "ap+ef61://did%3Akey%3Az6MkAlice/actor#main-key"],
+		["https://server.example/.well-known/apgateway/did:key:z6MkAlice/actor#", "ap+ef61://did%3Akey%3Az6MkAlice/actor#"],
+		["https://server.example/.well-known/apgateway/did:key:z6MkAlice/outbox?page=2", "ap+ef61://did%3Akey%3Az6MkAlice/outbox?page=2"],
+		["https://server.example/.well-known/apgateway/did:key:z6MkAlice/a%2Fb", "ap+ef61://did%3Akey%3Az6MkAlice/a%2Fb"],
+		["https://server.example/.well-known/apgateway/did:web:example.com%3A8080/actor", "ap+ef61://did%3Aweb%3Aexample.com%253A8080/actor"],
+		["https://server.example/.well-known/apgateway/did:example:a%2525/x", "ap+ef61://did%3Aexample%3Aa%2525/x"]
+	]) {
+		(0, node_assert.deepStrictEqual)(require_url.fromCompatibleEf61Id(input)?.href, expected, input);
+		(0, node_assert.deepStrictEqual)(require_url.fromCompatibleEf61Id(new URL(input))?.href, expected, input);
+	}
+	const converted = require_url.fromCompatibleEf61Id("https://server.example/.well-known/apgateway/did:key:z6MkAlice/objects/1");
+	(0, node_assert.deepStrictEqual)(require_url.formatIri(converted), "ap+ef61://did:key:z6MkAlice/objects/1");
+	(0, node_assert.deepStrictEqual)(require_url.canonicalizePortableUri(converted.href), "ap+ef61://did:key:z6MkAlice/objects/1");
+	(0, node_assert.ok)(require_url.arePortableUrisEqual(require_url.fromCompatibleEf61Id("https://a.example/.well-known/apgateway/did:key:z6MkAlice/actor").href, require_url.fromCompatibleEf61Id("https://b.example/.well-known/apgateway/did:key:z6MkAlice/actor").href));
+});
+(0, node_test.test)("fromCompatibleEf61Id() returns null for other URLs", () => {
+	for (const input of [
+		"https://server.example/users/alice",
+		"https://server.example/.well-known/webfinger?resource=acct:a@b",
+		"https://server.example/.well-known/apgateway",
+		"https://server.example/.well-known/apgateway/",
+		"https://server.example/.well-known/apgateway/hl:zQmdfTbBqBPQ7VNxZEYEj14VmRuZBkqFbiwReogJgS1zR1n",
+		"https://server.example/.well-known/apgateway/objects/did:key:z6MkAlice/x",
+		"https://server.example/.well-known/apgatewayx/did:key:z6MkAlice/x",
+		"https://server.example/ap/did:key:z6MkAlice/actor",
+		"https://server.example/?id=/.well-known/apgateway/did:key:z6MkAlice/x",
+		"ap://did:key:z6MkAlice/actor",
+		"ap+ef61://did:key:z6MkAlice/actor",
+		"ftp://server.example/.well-known/apgateway/did:key:z6MkAlice/actor",
+		"not a URL",
+		"/.well-known/apgateway/did:key:z6MkAlice/actor"
+	]) (0, node_assert.deepStrictEqual)(require_url.fromCompatibleEf61Id(input), null, input);
+	(0, node_assert.deepStrictEqual)(require_url.fromCompatibleEf61Id(new URL("ap+ef61://did%3Akey%3Az6MkAlice/actor")), null);
+	(0, node_assert.deepStrictEqual)(require_url.fromCompatibleEf61Id(123), null);
+});
+(0, node_test.test)("fromCompatibleEf61Id() rejects malformed compatible identifiers", () => {
+	for (const input of [
+		"https://server.example/.well-known/apgateway/did:key:z6MkAlice",
+		"https://server.example/.well-known/apgateway/did:",
+		"https://server.example/.well-known/apgateway/did:key/actor",
+		"https://server.example/.well-known/apgateway/did:ke%y:z6MkAlice/actor",
+		"https://server.example/.well-known/apgateway/did:key:z6MkAlice/a%zz",
+		"https://server.example/.well-known/apgateway/did:key:z6MkAlice/a#%zz",
+		"https://server.example/.well-known/apgateway/did:key:z6MkAlice/a?x=%zz",
+		"https://server.example/.well-known/apgateway/did:key:z6MkAlice/a?@gateway=https%3A%2F%2Fevil.example",
+		"https://server.example/.well-known/apgateway/did:key:z6MkAlice/a?page=2&%40gateway=x",
+		"https://server.example/.well-known/apgateway/did:key:z6MkAlice/a?@%67ateway=x",
+		"https://server.example/.well-known/apgateway/did:key:z6MkAlice/a?gateways=x",
+		"https://server.example/.well-known/apgateway/did:example:a%25/x",
+		"https://user:pass@server.example/.well-known/apgateway/did:key:z6MkAlice/a",
+		"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 = [
+		[
+			"ap+ef61://did:key:z6MkAlice/objects/1",
+			"https://server.example",
+			"https://server.example/.well-known/apgateway/did:key:z6MkAlice/objects/1"
+		],
+		[
+			"ap://did:key:z6MkAlice/objects/1",
+			"https://server.example/",
+			"https://server.example/.well-known/apgateway/did:key:z6MkAlice/objects/1"
+		],
+		[
+			"ap://did%3Akey%3Az6MkAlice/actor",
+			new URL("http://server.example:8080"),
+			"http://server.example:8080/.well-known/apgateway/did:key:z6MkAlice/actor"
+		],
+		[
+			new URL("ap+ef61://did%3Akey%3Az6MkAlice/actor"),
+			"https://server.example",
+			"https://server.example/.well-known/apgateway/did:key:z6MkAlice/actor"
+		],
+		[
+			new URL("ap://did%3Akey%3Az6MkAlice/actor"),
+			"https://SERVER.example",
+			"https://server.example/.well-known/apgateway/did:key:z6MkAlice/actor"
+		],
+		[
+			"ap://did:key:z6MkAlice/a/b/c",
+			"https://server.example",
+			"https://server.example/.well-known/apgateway/did:key:z6MkAlice/a/b/c"
+		],
+		[
+			"ap://did:key:z6MkAlice/actor#main-key",
+			"https://server.example",
+			"https://server.example/.well-known/apgateway/did:key:z6MkAlice/actor#main-key"
+		],
+		[
+			"ap://did:key:z6MkAlice/actor#",
+			"https://server.example",
+			"https://server.example/.well-known/apgateway/did:key:z6MkAlice/actor#"
+		],
+		[
+			"ap://DID:key:z6MkAlice/actor",
+			"https://server.example",
+			"https://server.example/.well-known/apgateway/did:key:z6MkAlice/actor"
+		],
+		[
+			"ap://did:example:a%2525/x",
+			"https://server.example",
+			"https://server.example/.well-known/apgateway/did:example:a%2525/x"
+		],
+		[
+			"ap://did:web:example.com%3A8080/actor",
+			"https://server.example",
+			"https://server.example/.well-known/apgateway/did:web:example.com%3A8080/actor"
+		],
+		[
+			"ap://did:key:z6MkAlice/a%2Fb/%252e",
+			"https://server.example",
+			"https://server.example/.well-known/apgateway/did:key:z6MkAlice/a%2Fb/%252e"
+		],
+		[
+			"ap://did:key:z6MkAlice/a\\b c	é/%7euser",
+			"https://server.example",
+			"https://server.example/.well-known/apgateway/did:key:z6MkAlice/a%5Cb%20c%09%C3%A9/~user"
+		]
+	];
+	for (const [portableId, gateway, expected] of cases) (0, node_assert.deepStrictEqual)(require_url.toCompatibleEf61Id(portableId, gateway).href, expected, String(portableId));
+});
+(0, node_test.test)("toCompatibleEf61Id() removes location hints from queries", () => {
+	const base = "https://server.example/.well-known/apgateway/did:key:z6MkAlice";
+	const cases = [
+		["ap://did:key:z6MkAlice/actor?@gateway=https%3A%2F%2Fa.example&@gateway=https%3A%2F%2Fb.example", `${base}/actor`],
+		["ap://did:key:z6MkAlice/actor?gateways=https%3A%2F%2Fa.example", `${base}/actor`],
+		["ap://did:key:z6MkAlice/actor?%40gateway=https%3A%2F%2Fa.example", `${base}/actor`],
+		["ap://did:key:z6MkAlice/actor?@%67ateway=https%3A%2F%2Fa.example", `${base}/actor`],
+		["ap://did:key:z6MkAlice/actor?@gateway", `${base}/actor`],
+		["ap://did:key:z6MkAlice/c?page=3&@gateway=https%3A%2F%2Fa.example&maxItems=20&page=4", `${base}/c?page=3&maxItems=20&page=4`],
+		["ap://did:key:z6MkAlice/c?a=1&&b=2#frag", `${base}/c?a=1&&b=2#frag`],
+		["ap://did:key:z6MkAlice/c?", `${base}/c?`],
+		["ap://did:key:z6MkAlice/c?x='y'", `${base}/c?x=%27y%27`],
+		["ap://did:key:z6MkAlice/c?@gate	way=https%3A%2F%2Fa.example", `${base}/c?@gate%09way=https%3A%2F%2Fa.example`],
+		["ap://did:key:z6MkAlice/c?@gate\nway=1&x=\r2", `${base}/c?@gate%0Away=1&x=%0D2`],
+		["ap://did:key:z6MkAlice/c?%ff=1", `${base}/c?%FF=1`]
+	];
+	for (const [portableId, expected] of cases) {
+		const result = require_url.toCompatibleEf61Id(portableId, "https://server.example");
+		(0, node_assert.deepStrictEqual)(result.href, expected, portableId);
+		(0, node_assert.ok)(!/[?&](%40|@)gateway(=|&|$)/i.test(result.search), portableId);
+	}
+});
+(0, node_test.test)("toCompatibleEf61Id() rejects invalid portable IDs", () => {
+	const cases = [
+		"https://server.example/actor",
+		"https://server.example/.well-known/apgateway/did:key:z6MkAlice/actor",
+		"at://did:plc:example/record",
+		"ap://not-a-did/actor",
+		"ap://did:key:z6MkAlice",
+		"ap://did:key:z6MkAlice/a%zz",
+		"ap://did:key:z6MkAlice/a#%zz",
+		"ap://did:key:z6MkAlice/a?x=%zz",
+		"ap://did:key:z6MkAlice/.",
+		"ap://did:key:z6MkAlice/..",
+		"ap://did:key:z6MkAlice/a/./b",
+		"ap://did:key:z6MkAlice/a/../b",
+		"ap://did:key:z6MkAlice/a/%2e/b",
+		"ap://did:key:z6MkAlice/a/%2E%2e/b",
+		"ap://did:key:z6MkAlice/a/.%2e/b",
+		"ap://did:key:z6MkAlice/a/%2e./b",
+		new URL("https://server.example/actor"),
+		new URL("ap+ef61://user:pass@did%3Akey%3Az6MkAlice/actor"),
+		new URL("ap+ef61://did%3Akey%3Az6MkAlice:8080/actor"),
+		123
+	];
+	for (const portableId of cases) (0, node_assert.throws)(() => require_url.toCompatibleEf61Id(portableId, "https://server.example"), TypeError, String(portableId));
+});
+(0, node_test.test)("toCompatibleEf61Id() rejects gateways that are not HTTP(S) origins", () => {
+	const cases = [
+		"ftp://server.example",
+		"ap+ef61://did:key:z6MkAlice/actor",
+		"https://user:pass@server.example",
+		"https://user@server.example",
+		"https://server.example/ap",
+		"https://server.example/ap/",
+		"https://server.example/.well-known/apgateway",
+		"https://server.example/?x=1",
+		"https://server.example/?",
+		"https://server.example/#fragment",
+		"https://server.example/#",
+		"server.example",
+		"",
+		new URL("https://server.example/?"),
+		new URL("https://server.example/#"),
+		new URL("https://server.example/ap"),
+		new URL("ftp://server.example/"),
+		123
+	];
+	for (const gateway of cases) (0, node_assert.throws)(() => require_url.toCompatibleEf61Id("ap://did:key:z6MkAlice/actor", gateway), TypeError, String(gateway));
+});
+(0, node_test.test)("compatible identifier conversion round-trips", () => {
+	for (const portableId of [
+		"ap+ef61://did:key:z6MkAlice/objects/1",
+		"ap://did:key:z6MkAlice/actor",
+		"ap://did%3Akey%3Az6MkAlice/actor/inbox",
+		"ap://did:key:z6MkAlice/actor#",
+		"ap://did:key:z6MkAlice/actor#main-key",
+		"ap://did:key:z6MkAlice/a%2Fb/%252e",
+		"ap://did:key:z6MkAlice/a\\b c	é",
+		"ap://did:example:a%2525/x",
+		"ap://did:web:example.com%3A8080/actor",
+		"ap://did:key:z6MkAlice/c?page=3&@gateway=https%3A%2F%2Fa.example"
+	]) {
+		const converted = require_url.fromCompatibleEf61Id(require_url.toCompatibleEf61Id(portableId, "https://server.example"));
+		(0, node_assert.ok)(converted != null, portableId);
+		(0, node_assert.deepStrictEqual)(require_url.canonicalizePortableUri(converted.href), require_url.canonicalizePortableUri(portableId), portableId);
+	}
+	(0, node_assert.ok)(!require_url.arePortableUrisEqual(require_url.fromCompatibleEf61Id(require_url.toCompatibleEf61Id("ap://did:key:z6MkAlice/actor", "https://server.example")).href, require_url.fromCompatibleEf61Id(require_url.toCompatibleEf61Id("ap://did:key:z6MkAlice/actor#", "https://server.example")).href));
+});
+(0, node_test.test)("UrlError reason is independent of its cause", () => {
+	const cause = /* @__PURE__ */ new Error("Underlying failure");
+	(0, node_assert.strictEqual)(new require_url.UrlError("Rejected URL").reason, "disallowed");
+	const disallowedError = new require_url.UrlError("Rejected URL", { cause });
+	(0, node_assert.strictEqual)(disallowedError.reason, "disallowed");
+	(0, node_assert.strictEqual)(disallowedError.cause, cause);
+	const dnsError = new require_url.UrlError("Lookup failed", {
+		reason: "dns",
+		cause
+	});
+	(0, node_assert.strictEqual)(dnsError.reason, "dns");
+	(0, node_assert.strictEqual)(dnsError.cause, cause);
+});
+(0, node_test.test)("validatePublicUrl() classifies disallowed URLs", async () => {
+	for (const url of [
+		"ftp://example.com",
+		"https://localhost",
+		"https://127.0.0.1"
+	]) await (0, node_assert.rejects)(() => require_url.validatePublicUrl(url), {
+		name: "UrlError",
+		reason: "disallowed"
+	});
 });
 (0, node_test.test)("validatePublicUrl()", async () => {
 	await (0, node_assert.rejects)(() => require_url.validatePublicUrl("ftp://localhost"), require_url.UrlError);
@@ -271,6 +597,45 @@ let node_test = require("node:test");
 	await require_url.validatePublicUrl("https://[2001:db8::1]");
 	await require_url.validatePublicUrl("https://[64:ff9b::8.8.8.8]");
 });
+(0, node_test.test)("validateLookupAddresses() tolerates Cloudflare Workers CNAME entries", () => {
+	require_url.validateLookupAddresses([
+		{
+			address: "app-host.example.net.",
+			family: 4
+		},
+		{
+			address: "93.184.216.34",
+			family: 4
+		},
+		{
+			address: "2606:2800:220:1:248:1893:25c8:1946",
+			family: 6
+		}
+	]);
+});
+(0, node_test.test)("validateLookupAddresses() rejects unsafe or CNAME-only Cloudflare Workers results", () => {
+	(0, node_assert.throws)(() => require_url.validateLookupAddresses([{
+		address: "private-host.example.net.",
+		family: 4
+	}, {
+		address: "127.0.0.1",
+		family: 4
+	}]), {
+		name: "UrlError",
+		reason: "disallowed"
+	});
+	(0, node_assert.throws)(() => require_url.validateLookupAddresses([{
+		address: "app-host.example.net.",
+		family: 4
+	}]), {
+		name: "UrlError",
+		reason: "dns"
+	});
+	(0, node_assert.throws)(() => require_url.validateLookupAddresses([]), {
+		name: "UrlError",
+		reason: "dns"
+	});
+});
 (0, node_test.test)("isValidPublicIPv4Address()", () => {
 	(0, node_assert.ok)(require_url.isValidPublicIPv4Address("8.8.8.8"));
 	(0, node_assert.ok)(!require_url.isValidPublicIPv4Address("192.168.1.1"));
@@ -328,4 +693,122 @@ let node_test = require("node:test");
 	(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