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

package/dist/tests/url.test.cjs

@@ -1,4 +1,4 @@
-const require_url = require("./url-B8xyTwP-.cjs");
+const require_url = require("./url-CtHyzMR4.cjs");
 let node_test = require("node:test");
 let node_assert = require("node:assert");
 //#region src/url.test.ts
@@ -228,7 +228,11 @@ let node_assert = require("node:assert");
 	(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)));
 	}
@@ -238,11 +242,19 @@ let node_assert = require("node:assert");
 		"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), (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 [
@@ -608,4 +620,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

package/dist/tests/url.test.mjs

@@ -1,4 +1,4 @@
-import { _ as validateLookupAddresses, 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, v as validatePublicUrl } from "./url-DfS-cvwr.mjs";
+import { C as withoutGatewayHints, S as withGatewayHints, _ as parseIri, a as expandIPv6Address, b as validateLookupAddresses, 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 validatePublicUrl, y as toCompatibleEf61Id } from "./url-Cdu4ASgJ.mjs";
 import { test } from "node:test";
 import { deepStrictEqual, ok, rejects, strictEqual, throws } from "node:assert";
 //#region src/url.test.ts
@@ -228,7 +228,11 @@ test("parseIri() preserves encoded percent signs while decoding delimiters", ()
 	deepStrictEqual(formatIri(parsed), "ap+ef61://did:web:example.com%00/u/1");
 });
 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/"
+	]) {
 		deepStrictEqual(parseGatewayUrl(url), new URL(url));
 		ok(isGatewayUrl(new URL(url)));
 	}
@@ -238,11 +242,19 @@ test("parseGatewayUrl() accepts only HTTP(S) base URIs", () => {
 		"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/#"
 	]) {
 		throws(() => parseGatewayUrl(url), (error) => error instanceof TypeError && error.message.startsWith("Invalid FEP-ef61 gateway: "));
 		ok(!isGatewayUrl(new URL(url)));
 	}
+	const mutated = new URL("https://server.example/");
+	mutated.search = "?";
+	ok(!isGatewayUrl(mutated));
+	mutated.search = "";
+	mutated.hash = "#";
+	ok(!isGatewayUrl(mutated));
 });
 test("fromCompatibleEf61Id() converts compatible identifiers", () => {
 	for (const [input, expected] of [
@@ -608,5 +620,123 @@ test("expandIPv6Address()", () => {
 	deepStrictEqual(expandIPv6Address("2001:db8::1"), "2001:0db8:0000:0000:0000:0000:0000:0001");
 	deepStrictEqual(expandIPv6Address("64:ff9b::8.8.8.8"), "0064:ff9b:0000:0000:0000:0000:0808:0808");
 });
+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",
+		parseIri("ap://did:key:z6Mkabc/actor"),
+		new URL("ap://did%3Akey%3Az6Mkabc/actor")
+	]) {
+		const hinted = withGatewayHints(id, ["https://server1.example", new URL("https://server2.example/")]);
+		ok(hinted instanceof URL);
+		strictEqual(hinted.href, "ap+ef61://did%3Akey%3Az6Mkabc/actor?@gateway=https%3A%2F%2Fserver1.example&@gateway=https%3A%2F%2Fserver2.example");
+		strictEqual(formatIri(hinted), expected);
+		deepStrictEqual(parseIri(formatIri(hinted)), hinted);
+	}
+});
+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";
+	}
+	strictEqual(formatIri(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");
+	strictEqual(formatIri(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`);
+	deepStrictEqual(getGatewayHints(withGatewayHints("ap://did:key:z6Mkabc/actor", many)).map((url) => url.origin), many);
+});
+test("withGatewayHints() keeps other query parameters and fragments", () => {
+	strictEqual(formatIri(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");
+	strictEqual(formatIri(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");
+	strictEqual(withGatewayHints("ap://did:key:z6Mkabc/actor#", ["https://s.example"]).href, "ap+ef61://did%3Akey%3Az6Mkabc/actor?@gateway=https%3A%2F%2Fs.example#");
+});
+test("withGatewayHints() replaces existing location hints", () => {
+	strictEqual(formatIri(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"
+	]) deepStrictEqual(getGatewayHints(withGatewayHints(`ap://did:key:z6Mkabc/actor?@gate${char}way=https%3A%2F%2Fevil.example`, ["https://new.example"])).map((url) => url.href), ["https://new.example/"]);
+});
+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"]
+	]) {
+		strictEqual(withGatewayHints(input, []).href, expected, input);
+		strictEqual(withoutGatewayHints(input).href, expected, input);
+	}
+	const input = parseIri("ap://did:key:z6Mkabc/actor?@gateway=https%3A%2F%2Fa.example");
+	const href = input.href;
+	withoutGatewayHints(input);
+	strictEqual(input.href, href);
+});
+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")
+	]) {
+		throws(() => withGatewayHints(id, ["https://server.example"]), TypeError, String(id));
+		throws(() => withoutGatewayHints(id), TypeError, String(id));
+		throws(() => getGatewayHints(id), TypeError, String(id));
+	}
+});
+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"
+	]) {
+		throws(() => withGatewayHints(id, ["https://server.example"]), TypeError, id);
+		throws(() => withoutGatewayHints(id), TypeError, id);
+	}
+	strictEqual(withoutGatewayHints("ap://did:key:z6Mkabc/a	b").href, "ap+ef61://did%3Akey%3Az6Mkabc/a%09b");
+});
+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")
+	]) throws(() => withGatewayHints("ap://did:key:z6Mkabc/actor", [gateway]), TypeError, String(gateway));
+	throws(() => withGatewayHints("ap://did:key:z6Mkabc/actor", "https://server.example"), TypeError);
+});
+test("getGatewayHints() reads @gateway location hints", () => {
+	deepStrictEqual(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/"]);
+	deepStrictEqual(getGatewayHints("ap://did:key:z6Mkabc/actor"), []);
+	const questioned = "ap://did:key:z6Mkabc/actor??@gateway=https%3A%2F%2Fa.example";
+	deepStrictEqual(getGatewayHints(questioned), []);
+	strictEqual(withoutGatewayHints(questioned).href, "ap+ef61://did%3Akey%3Az6Mkabc/actor??@gateway=https%3A%2F%2Fa.example");
+	deepStrictEqual(getGatewayHints(withGatewayHints(questioned, ["https://b.example"])).map((url) => url.href), ["https://b.example/"]);
+	deepStrictEqual(getGatewayHints("ap://did:key:z6Mkabc/actor?@gate%09way=https%3A%2F%2Fa.example"), []);
+	deepStrictEqual(getGatewayHints("ap://did:key:z6Mkabc/actor?@gate	way=https%3A%2F%2Fa.example"), []);
+});
+test("withGatewayHints() round-trips with other portable ID helpers", () => {
+	const hinted = withGatewayHints("ap://did:key:z6Mkabc/objects/1#frag", ["https://server1.example", "https://server2.example"]);
+	strictEqual(canonicalizePortableUri(formatIri(hinted)), "ap+ef61://did:key:z6Mkabc/objects/1#frag");
+	ok(arePortableUrisEqual(formatIri(hinted), "ap://did:key:z6Mkabc/objects/1#frag"));
+	strictEqual(toCompatibleEf61Id(hinted, "https://server1.example").href, "https://server1.example/.well-known/apgateway/did:key:z6Mkabc/objects/1#frag");
+	strictEqual(formatIri(withoutGatewayHints(hinted)), "ap+ef61://did:key:z6Mkabc/objects/1#frag");
+});
 //#endregion
 export {};

package/dist/{url-DDVweCXr.cjs → url-BHfQuRdy.cjs}

@@ -221,9 +221,10 @@ function parseAtUri(uri) {
 }
 /**
 * Checks whether the URL is an FEP-ef61 gateway base URI.
+* @since 2.4.0
 */
 function isGatewayUrl(url) {
-	return (url.protocol === "http:" || url.protocol === "https:") && url.username === "" && url.password === "" && url.pathname === "/" && url.search === "" && url.hash === "";
+	return (url.protocol === "http:" || url.protocol === "https:") && url.href === `${url.origin}/`;
 }
 /**
 * Parses and validates an FEP-ef61 gateway base URI.
@@ -231,6 +232,7 @@ function isGatewayUrl(url) {
 *                     with no credentials, path, query, or fragment.  In the
 *                     latter case, the message starts with
 *                     `Invalid FEP-ef61 gateway:`.
+* @since 2.4.0
 */
 function parseGatewayUrl(url) {
 	const parsed = parseIri(url);
@@ -358,7 +360,7 @@ function toCompatibleEf61Id(portableId, gateway) {
 }
 function parseCompatibleEf61Gateway(gateway) {
 	const url = gateway instanceof URL ? gateway : typeof gateway === "string" && URL.canParse(gateway) ? new URL(gateway) : null;
-	if (url == null || url.protocol !== "http:" && url.protocol !== "https:" || url.href !== `${url.origin}/`) throw new TypeError("FEP-ef61 gateways for compatible identifiers must be HTTP(S) origins with no credentials, path, query, or fragment.");
+	if (url == null || !isGatewayUrl(url)) throw new TypeError("FEP-ef61 gateways for compatible identifiers must be HTTP(S) origins with no credentials, path, query, or fragment.");
 	return url;
 }
 function getRawPortableIri(portableId) {
@@ -384,6 +386,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) {
@@ -579,6 +741,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() {
@@ -621,6 +789,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() {
@@ -651,6 +825,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() {
@@ -681,3 +861,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;
+	}
+});