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

package/dist/{url-Be3moMor.js → url-DqqDZY9i.js}

@@ -219,9 +219,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.
@@ -229,6 +230,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);
@@ -356,7 +358,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) {
@@ -382,6 +384,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) {
@@ -577,4 +739,4 @@ function matchesIPv6Prefix(address, prefixWords, prefixLength) {
 	return true;
 }
 //#endregion
-export { validatePublicUrl as _, formatIri as a, haveSameFe34Origin as c, isValidPublicIPv4Address as d, isValidPublicIPv6Address as f, toCompatibleEf61Id as g, parseJsonLdId as h, expandIPv6Address as i, haveSameIriOrigin as l, parseIri as m, arePortableUrisEqual as n, fromCompatibleEf61Id as o, parseGatewayUrl as p, canonicalizePortableUri as r, getFe34Origin as s, UrlError as t, isGatewayUrl as u };
+export { withoutGatewayHints as S, parseIri as _, expandIPv6Address as a, validatePublicUrl as b, getFe34Origin as c, haveSameIriOrigin as d, isGatewayUrl as f, parseGatewayUrl as g, parseGatewayOrigin as h, canonicalizePortableUri as i, getGatewayHints as l, isValidPublicIPv6Address as m, UrlError as n, formatIri as o, isValidPublicIPv4Address as p, arePortableUrisEqual as r, fromCompatibleEf61Id as s, GATEWAY_HINT_PARAMETER as t, haveSameFe34Origin as u, parseJsonLdId as v, withGatewayHints as x, toCompatibleEf61Id as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/vocab-runtime",
-  "version": "2.4.0-dev.2219+eb70f060",
+  "version": "2.4.0-dev.2233+abb4a6b2",
   "homepage": "https://fedify.dev/",
   "repository": {
     "type": "git",

package/src/internal/portable-dereference.test.ts

@@ -1,7 +1,7 @@
 import { deepStrictEqual, ok, throws } from "node:assert/strict";
 import { test } from "node:test";
 import type { DocumentLoader } from "../docloader.ts";
-import { parseIri } from "../url.ts";
+import { parseIri, withGatewayHints } from "../url.ts";
 import { createScopedContextLoader } from "./jsonld-cache.ts";
 import {
   createSnapshotContextLoader,
@@ -55,6 +55,8 @@ test("getPortableGatewayCandidates() reads @gateway hints", () => {
         "&gateways=https%3A%2F%2Flegacy.example" +
         "&@gateway=not%20a%20URL" +
         "&@gateway=https%3A%2F%2Fb.example%2Fpath" +
+        "&@gateway=https%3A%2F%2Fquery.example%2F%3F" +
+        "&@gateway=https%3A%2F%2Ffragment.example%2F%23" +
         "&%40gateway=https%3A%2F%2Fb.example" +
         "&@gateway=https%3A%2F%2Fa.example%2F",
     ))),
@@ -76,6 +78,19 @@ test("getPortableGatewayCandidates() reads @gateway hints", () => {
   );
 });
 
+test("getPortableGatewayCandidates() reads hints from withGatewayHints()", () => {
+  const gateways = Array.from(
+    { length: 7 },
+    (_, i) => `https://g${i}.example`,
+  );
+  deepStrictEqual(
+    hrefs(getPortableGatewayCandidates(
+      withGatewayHints("ap://did:key:z6Mkabc/actor?page=1", gateways),
+    )),
+    [0, 1, 2, 3, 4].map((i) => `https://g${i}.example/`),
+  );
+});
+
 test("createSnapshotContextLoader() does not nest released snapshots", async () => {
   const calls: string[] = [];
   const base: DocumentLoader = (url) => {

package/src/internal/portable-dereference.ts

@@ -21,7 +21,9 @@ import {
   canonicalizePortableUri,
   formatIri,
   fromCompatibleEf61Id,
+  GATEWAY_HINT_PARAMETER,
   haveSameFe34Origin,
+  parseGatewayOrigin,
   parseIri,
   toCompatibleEf61Id,
 } from "../url.ts";
@@ -35,8 +37,6 @@ const logger = getLogger(["fedify", "vocab", "gateway"]);
  */
 const MAX_GATEWAY_HINTS = 5;
 
-const LOCATION_HINT_PARAMETER = "@gateway";
-
 // The same baseline contexts that Fedify's proof verifier always resolves
 // from its built-in copies (see getNormalizationContextLoader() in
 // @fedify/fedify).  Serving them identically here keeps the identity check,
@@ -524,7 +524,7 @@ export function getPortableGatewayCandidates(
   }
   for (
     const hint of new URLSearchParams(url.search).getAll(
-      LOCATION_HINT_PARAMETER,
+      GATEWAY_HINT_PARAMETER,
     )
   ) {
     if (candidates.length >= MAX_GATEWAY_HINTS) break;
@@ -541,23 +541,6 @@ export function getPortableGatewayCandidates(
   return candidates;
 }
 
-function parseGatewayOrigin(gateway: string | URL): URL | null {
-  let url: 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;
-  // Comparing href with the origin also rejects credentials, a path, and
-  // query and fragment components, including empty ? and # delimiters.
-  if (
-    (url.protocol !== "http:" && url.protocol !== "https:") ||
-    url.href !== `${url.origin}/`
-  ) {
-    return null;
-  }
-  return url;
-}
-
 /**
  * Creates a context loader that returns the same context documents for the
  * whole dereference operation, so that the identity check, the proof

package/src/mod.ts

@@ -83,6 +83,7 @@ export {
   formatIri,
   fromCompatibleEf61Id,
   getFe34Origin,
+  getGatewayHints,
   haveSameFe34Origin,
   haveSameIriOrigin,
   isGatewayUrl,
@@ -94,4 +95,6 @@ export {
   toCompatibleEf61Id,
   UrlError,
   validatePublicUrl,
+  withGatewayHints,
+  withoutGatewayHints,
 } from "./url.ts";

package/src/url.test.ts

@@ -7,6 +7,7 @@ import {
   formatIri,
   fromCompatibleEf61Id,
   getFe34Origin,
+  getGatewayHints,
   haveSameFe34Origin,
   haveSameIriOrigin,
   isGatewayUrl,
@@ -19,6 +20,8 @@ import {
   UrlError,
   validateLookupAddresses,
   validatePublicUrl,
+  withGatewayHints,
+  withoutGatewayHints,
 } from "./url.ts";
 
 test("parseIri() accepts portable ActivityPub URI schemes", () => {
@@ -644,7 +647,13 @@ test("parseIri() preserves encoded percent signs while decoding delimiters", ()
 });
 
 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)));
   }
@@ -656,7 +665,9 @@ test("parseGatewayUrl() accepts only HTTP(S) base URIs", () => {
       "https://user@server.example/",
       "https://server.example/path",
       "https://server.example/?x=1",
+      "https://server.example/?",
       "https://server.example/#fragment",
+      "https://server.example/#",
     ]
   ) {
     // Inboxes tell a malformed gateway from other errors by this prefix:
@@ -668,6 +679,13 @@ test("parseGatewayUrl() accepts only HTTP(S) base URIs", () => {
     );
     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", () => {
@@ -1212,3 +1230,295 @@ test("expandIPv6Address()", () => {
     "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(): Generator<string | URL> {
+    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",
+        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",
+  );
+  // There is no limit on the number of hints:
+  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",
+  );
+  // Characters that the URL parser strips cannot turn into a hint name:
+  for (const char of ["\t", "\n", "\r"]) {
+    const hinted = withGatewayHints(
+      `ap://did:key:z6Mkabc/actor?@gate${char}way=https%3A%2F%2Fevil.example`,
+      ["https://new.example"],
+    );
+    deepStrictEqual(getGatewayHints(hinted).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);
+  }
+  // Characters that the URL parser would strip are percent-encoded instead:
+  strictEqual(
+    withoutGatewayHints("ap://did:key:z6Mkabc/a\tb").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" as unknown as string[],
+      ),
+    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"), []);
+  // A literal question mark is a part of the parameter name:
+  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\tway=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",
+  );
+});