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

package/dist/url-DrGTR8yv.cjs

@@ -0,0 +1,993 @@
+
+const require_rolldown_runtime = require("./rolldown-runtime-B7lfambq.cjs");
+let node_dns_promises = require("node:dns/promises");
+node_dns_promises = require_rolldown_runtime.__toESM(node_dns_promises, 1);
+let node_net = require("node:net");
+//#region src/url.ts
+var UrlError = class extends Error {
+	/**
+	* The failure category. Defaults to `"disallowed"`.
+	* `"dns"` includes lookup errors and results with no usable IP addresses.
+	* @since 2.0.29
+	*/
+	reason;
+	constructor(message, options) {
+		super(message, options);
+		this.name = "UrlError";
+		this.reason = options?.reason ?? "disallowed";
+	}
+};
+const PORTABLE_IRI_PATTERN = /^(ap|ap\+ef61):\/\/([^/?#]*)([^?#]*)(\?[^#]*)?(#.*)?$/i;
+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, including FEP-ef61 portable
+* ActivityPub IRIs.  See {@link parseIri} for how IRIs are parsed.
+* @param id The `@id` value.
+* @param base The base IRI to resolve a relative `@id` against.
+* @returns The parsed IRI, or `undefined` if `id` is missing or a blank node
+*          identifier.
+* @throws {TypeError} If `id` is not a valid IRI.
+* @since 2.4.0
+*/
+function parseJsonLdId(id, base) {
+	if (id == null || id.startsWith("_:")) return void 0;
+	try {
+		return parseIri(id, base);
+	} catch {
+		throw new TypeError("Invalid @id: " + id);
+	}
+}
+/**
+* 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.
+*
+* Portable IRIs, e.g., `ap://did:key:z6Mk.../actor`, cannot be represented by
+* JavaScript `URL` as they are, so the returned `URL` keeps the DID authority
+* percent-encoded, e.g., `ap+ef61://did%3Akey%3Az6Mk.../actor`.  Use
+* {@link formatIri} to get the canonical string back.
+* @param iri The IRI to parse.
+* @param base The base IRI to resolve a relative IRI against.
+* @returns The parsed IRI.
+* @throws {TypeError} If the IRI is malformed.
+* @since 2.4.0
+*/
+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.
+*
+* Portable IRIs are formatted with the `ap+ef61:` scheme and a decoded DID
+* authority, even if they were parsed from `ap:` IRIs.  FEP-ef61 currently
+* recommends the `ap:` scheme, so a future major version of Fedify may change
+* the scheme this function produces.  Do not compare its results as strings to
+* tell whether two portable IRIs identify the same object; use
+* `arePortableUrisEqual()` instead.
+* @param iri The IRI to format.
+* @returns The formatted IRI.  A string that cannot be parsed as a URL at all
+*          is returned unchanged.
+* @throws {TypeError} If the IRI is a malformed portable IRI or FEP-ef61
+*                     compatible identifier, e.g., one with dot segments.
+* @since 2.4.0
+*/
+function formatIri(iri) {
+	if (typeof iri === "string") assertPortablePathCanBeParsed(iri);
+	const parsed = parsePortableIri(iri instanceof 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}`;
+}
+/**
+* Canonicalizes a FEP-ef61 portable ActivityPub URI for comparison.
+*
+* This accepts both `ap:` and `ap+ef61:` URI strings with decoded or
+* percent-encoded DID authorities.  The returned value uses the `ap+ef61:`
+* scheme, a decoded DID authority, and no query component.  Pass the raw URI
+* string, not a `URL` object, because JavaScript `URL` normalizes opaque path
+* segments before Fedify can compare them.
+*
+* The `ap+ef61:` scheme of the result is a choice of Fedify's, whereas
+* FEP-ef61 currently canonicalizes portable URIs with the `ap:` scheme.
+* A future major version of Fedify may change the scheme of the result, so
+* do not persist the result as the only copy of an identifier; keep the
+* original URI, and canonicalize it again when comparing.
+*
+* @param input The raw portable ActivityPub URI string to canonicalize.
+* @returns The canonical portable ActivityPub URI string.
+* @throws {TypeError} If the input is not a valid portable ActivityPub IRI.
+* @since 2.4.0
+*/
+function canonicalizePortableUri(input) {
+	if (typeof input !== "string") throw new TypeError("Invalid portable ActivityPub IRI.");
+	const parsed = parsePortableIri(input);
+	if (parsed == null) throw new TypeError("Invalid portable ActivityPub IRI.");
+	const match = input.match(PORTABLE_IRI_PATTERN);
+	return `ap+ef61://${normalizePortableAuthority(getDidUrlOrigin(decodePortableAuthority(parsed.host)))}${normalizePortableComponent(match[3])}${match[5] == null ? "" : normalizePortableComponent(match[5])}`;
+}
+/**
+* Checks whether two FEP-ef61 portable ActivityPub URIs identify the same
+* portable object.
+*
+* Non-string inputs return `false`.  Non-portable URI strings use strict string
+* equality.  Portable URI strings are compared through
+* {@link canonicalizePortableUri}; malformed portable URI strings return
+* `false` unless they are exactly equal.
+*
+* @since 2.4.0
+*/
+function arePortableUrisEqual(left, right) {
+	if (typeof left !== "string" || typeof right !== "string") return false;
+	if (left === right) return true;
+	if (!PORTABLE_IRI_PATTERN.test(left) || !PORTABLE_IRI_PATTERN.test(right)) return false;
+	try {
+		return canonicalizePortableUri(left) === canonicalizePortableUri(right);
+	} catch (error) {
+		if (error instanceof TypeError) return false;
+		throw error;
+	}
+}
+/**
+* Computes an IRI's FEP-fe34 origin.
+*
+* HTTP(S) IRIs use their web origin.  FEP-ef61 portable ActivityPub IRIs and
+* DID URLs use their DID as a cryptographic origin.
+*
+* @throws {TypeError} If the IRI does not have a supported FEP-fe34 origin.
+* @since 2.4.0
+*/
+function getFe34Origin(input) {
+	if (input instanceof URL) {
+		const portable = normalizePortableUrl(input);
+		if (portable != null) return getPortableCryptographicOrigin(portable);
+		if (input.protocol === "did:") return getDidUrlOrigin(input.href);
+		if (input.protocol === "http:" || input.protocol === "https:") return input.origin;
+		throw new TypeError("Unsupported FEP-fe34 origin IRI.");
+	}
+	const portable = parsePortableIri(input);
+	if (portable != null) return getPortableCryptographicOrigin(portable);
+	if (DID_SCHEME_PATTERN.test(input)) return getDidUrlOrigin(input);
+	const parsed = new URL(input);
+	if (parsed.protocol === "http:" || parsed.protocol === "https:") return parsed.origin;
+	throw new TypeError("Unsupported FEP-fe34 origin IRI.");
+}
+/**
+* Checks whether two IRIs have the same FEP-fe34 origin.
+*
+* Malformed or unsupported IRIs are treated as non-matching.
+*
+* @since 2.4.0
+*/
+function haveSameFe34Origin(left, right) {
+	try {
+		return getFe34Origin(left) === getFe34Origin(right);
+	} catch (error) {
+		if (error instanceof TypeError) return false;
+		throw error;
+	}
+}
+/**
+* Checks whether two IRIs have the same origin.  Unlike comparing
+* `URL.origin`, which is `"null"` for URLs with non-special schemes, this
+* compares FEP-ef61 portable ActivityPub IRIs by their schemes and DIDs, so
+* that `ap:` and `ap+ef61:` IRIs of the same DID with decoded or
+* percent-encoded authorities have the same origin.  Other IRIs with
+* a non-special scheme and a host are compared by their schemes and hosts.
+*
+* This is not an FEP-fe34 origin check: an `ap+ef61:` IRI and the `did:key`
+* verification method of the same DID have different origins here.  Use
+* {@link haveSameFe34Origin} for that.
+* @param left The first IRI.
+* @param right The second IRI.
+* @returns `true` if the IRIs have the same origin.
+* @since 2.4.0
+*/
+function haveSameIriOrigin(left, right) {
+	return getComparableIriOrigin(left) === getComparableIriOrigin(right);
+}
+function getComparableIriOrigin(iri) {
+	iri = normalizePortableUrl(iri) ?? iri;
+	if (iri.origin !== "null") return iri.origin;
+	if (iri.host !== "") {
+		const host = iri.protocol === "ap+ef61:" ? encodeURIComponent(getDidUrlOrigin(decodePortableAuthority(iri.host))) : iri.host;
+		return `${iri.protocol}//${host}`;
+	}
+	return iri.href;
+}
+function getPortableCryptographicOrigin(iri) {
+	return getDidUrlOrigin(decodePortableAuthority(iri.host));
+}
+function getDidUrlOrigin(iri) {
+	const did = iri.split(/[/?#]/, 1)[0].replace(DID_SCHEME_PATTERN, "did:");
+	if (!DID_PATTERN.test(did)) throw new TypeError("Invalid DID URL.");
+	const parts = did.split(":");
+	parts[1] = parts[1].toLowerCase();
+	return normalizePortableAuthority(parts.join(":"));
+}
+function parsePortableIri(iri) {
+	const match = iri.match(PORTABLE_IRI_PATTERN);
+	if (match == null) return null;
+	const authority = getDidUrlOrigin(decodePortableAuthority(match[2]));
+	if (!DID_PATTERN.test(authority)) throw new TypeError("Invalid portable ActivityPub IRI authority.");
+	if (match[3] === "") throw new TypeError("Invalid portable ActivityPub IRI path.");
+	return new URL(`ap+ef61://${encodeURIComponent(authority)}${match[3]}${match[4] ?? ""}${match[5] ?? ""}`);
+}
+function normalizePortableUrl(iri) {
+	if (iri.protocol !== "ap:" && iri.protocol !== "ap+ef61:") return null;
+	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) {
+	if (INVALID_PERCENT_ENCODING_PATTERN.test(authority)) throw new TypeError("Invalid portable ActivityPub IRI authority.");
+	if (DID_SCHEME_PATTERN.test(authority)) {
+		const decoded = authority.replace(/%25/gi, "%");
+		if (INVALID_PERCENT_ENCODING_PATTERN.test(decoded)) throw new TypeError("Invalid portable ActivityPub IRI authority.");
+		return decoded;
+	}
+	const decoded = authority.replace(/%(25|3A)/gi, (match) => match.toLowerCase() === "%3a" ? ":" : "%");
+	if (INVALID_PERCENT_ENCODING_PATTERN.test(decoded)) throw new TypeError("Invalid portable ActivityPub IRI authority.");
+	return decoded;
+}
+function normalizePercentEncoding(value) {
+	return value.replace(PERCENT_ENCODING_PATTERN, (match) => match.toUpperCase());
+}
+function normalizePortableAuthority(authority) {
+	return normalizePercentEncoding(authority).replace(PERCENT_ENCODING_PATTERN, (match) => {
+		const decoded = String.fromCharCode(Number.parseInt(match.slice(1), 16));
+		return /[A-Za-z0-9._~-]/.test(decoded) ? decoded : match;
+	});
+}
+function normalizePortableComponent(value) {
+	if (INVALID_PERCENT_ENCODING_PATTERN.test(value)) throw new TypeError("Invalid portable ActivityPub IRI component.");
+	return value.replace(/%[0-9A-Fa-f]{2}|[^%]+/g, (match) => {
+		if (match.startsWith("%")) {
+			const upper = match.toUpperCase();
+			const decoded = String.fromCharCode(Number.parseInt(upper.slice(1), 16));
+			return /[A-Za-z0-9._~-]/.test(decoded) ? decoded : upper;
+		}
+		try {
+			return encodeURI(match);
+		} catch (error) {
+			if (error instanceof URIError) throw new TypeError("Invalid portable ActivityPub IRI component.");
+			throw error;
+		}
+	});
+}
+function parseAtUri(uri) {
+	const index = uri.indexOf("/", 5);
+	const authority = index >= 0 ? uri.slice(5, index) : uri.slice(5);
+	const path = index >= 0 ? uri.slice(index) : "";
+	return new URL("at://" + encodeURIComponent(authority) + path);
+}
+/**
+* Checks whether the URL is an FEP-ef61 gateway base URI, i.e., an HTTP(S)
+* URI with no credentials, path, query, or fragment, such as
+* `https://example.com/`.  FEP-ef61 requires every item of a portable actor's
+* `gateways` to be such a URI.  A URI with an empty query or fragment
+* delimiter, such as `https://example.com/?`, is not a gateway base URI.
+*
+* Note that the `URL` class normalizes `https://example.com` to
+* `https://example.com/`, so both are gateway base URIs.
+* @param url The URL to check.
+* @returns `true` if the URL is an FEP-ef61 gateway base URI.
+* @since 2.4.0
+*/
+function isGatewayUrl(url) {
+	return (url.protocol === "http:" || url.protocol === "https:") && url.href === `${url.origin}/`;
+}
+/**
+* Parses and validates an FEP-ef61 gateway base URI, i.e., an HTTP(S) URI with
+* no credentials, path, query, or fragment, such as `https://example.com`.
+* See {@link isGatewayUrl} for the rules.
+* @param url The gateway base URI to parse.
+* @returns The parsed gateway base URI, whose path is `/`.
+* @throws {TypeError} If the URI is malformed, or is not an HTTP(S) base URI
+*                     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);
+	if (!isGatewayUrl(parsed)) throw new TypeError(`Invalid FEP-ef61 gateway: ${url}.  FEP-ef61 gateways must be HTTP(S) base URIs with no credentials, path, query, or fragment.`);
+	return parsed;
+}
+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
+* URI.
+*
+* A compatible identifier is an HTTP(S) URL under a gateway's fixed
+* `/.well-known/apgateway/` path, such as
+* `https://server.example/.well-known/apgateway/did:key:z6Mk.../objects/1`.
+* This function removes the gateway part and returns the corresponding
+* portable URI, e.g., `ap+ef61://did:key:z6Mk.../objects/1`, in the same
+* internal `URL` form that {@link parseIri} produces.  The path, query, and
+* fragment are preserved, so the result is a portable URI, not a comparison
+* form; pass its `href` to {@link canonicalizePortableUri} or
+* {@link arePortableUrisEqual} to compare it with other portable URIs.
+*
+* The conversion only reveals the *claimed* portable identifier.  Anyone can
+* publish a compatible identifier for any DID on their own server, so the
+* gateway that served it is neither the object's origin nor authorized to act
+* for the DID.  Callers must still verify the retrieved document's Object
+* Integrity Proof against the DID, as FEP-ef61 requires, and should keep the
+* original URL if they need the gateway as a retrieval hint.
+*
+* Arbitrary gateway paths are not supported.
+*
+* [FEP-ef61]: https://w3id.org/fep/ef61
+*
+* @param input The URL to convert.
+* @returns The portable ActivityPub URI, or `null` if the input is not an
+*          HTTP(S) URL whose path starts with `/.well-known/apgateway/did:`.
+*          Other gateway routes, such as the gateway discovery endpoint and
+*          hashlink media URLs, also yield `null`.
+* @throws {TypeError} If the input looks like a compatible identifier but is
+*                     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), 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) {
+	return convertCompatibleEf61Id(input)?.url ?? null;
+}
+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 (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)) {
+		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 {
+			url: parsed,
+			iri
+		};
+	} catch (error) {
+		if (error instanceof TypeError) throw new TypeError("Invalid FEP-ef61 compatible identifier.", { cause: error });
+		throw error;
+	}
+}
+/**
+* Converts a portable ActivityPub URI into an [FEP-ef61] compatible
+* identifier, which is an HTTP(S) URL under the gateway's fixed
+* `/.well-known/apgateway/` path.
+*
+* For example, `ap+ef61://did:key:z6Mk.../objects/1` and
+* `https://server.example` yield
+* `https://server.example/.well-known/apgateway/did:key:z6Mk.../objects/1`.
+* Both `ap:` and `ap+ef61:` URIs with decoded or percent-encoded DID
+* authorities are accepted.  Publishers should use the first gateway in the
+* actor's `gateways` list, as FEP-ef61 requires.
+*
+* The path and fragment are preserved, with characters that are not allowed
+* in HTTP(S) URLs percent-encoded the same way as
+* {@link canonicalizePortableUri} does.  FEP-ef61 location hints (`@gateway`
+* query parameters, and the legacy `gateways` parameter) are removed, since
+* compatible identifiers must not have them; other query parameters are kept
+* in order.
+*
+* Arbitrary gateway paths are not supported.
+*
+* [FEP-ef61]: https://w3id.org/fep/ef61
+*
+* @param portableId The `ap:` or `ap+ef61:` URI to convert.
+* @param gateway The gateway's HTTP(S) origin, e.g., `https://server.example`.
+* @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 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
+*/
+function toCompatibleEf61Id(portableId, gateway) {
+	const gatewayUrl = parseCompatibleEf61Gateway(gateway);
+	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.");
+	let did = decodePortableAuthority(parsed.host);
+	if (/%25/i.test(did)) did = did.replace(/%/g, "%25");
+	const path = normalizePortableComponent(match[3]);
+	if (path.split("/").some((segment) => segment === "." || segment === "..")) throw new TypeError("FEP-ef61 compatible identifiers cannot represent portable IRI paths with dot segments.");
+	const query = match[4] == null ? "" : stripLocationHints(normalizePortableComponent(match[4].slice(1)));
+	const fragment = match[5] == null ? "" : normalizePortableComponent(match[5]);
+	const result = new URL(gatewayUrl.origin + COMPATIBLE_ID_PATH_PREFIX + did + path + query + fragment);
+	const converted = convertCompatibleEf61Id(result);
+	if (converted == null || canonicalizePortableUri(converted.iri) !== canonicalizePortableUri(raw)) throw new TypeError("The portable ActivityPub IRI cannot be represented as an FEP-ef61 compatible identifier.");
+	return result;
+}
+function parseCompatibleEf61Gateway(gateway) {
+	const url = gateway instanceof URL ? gateway : typeof gateway === "string" && URL.canParse(gateway) ? new URL(gateway) : null;
+	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) {
+	if (portableId instanceof URL) {
+		if (portableId.protocol !== "ap:" && portableId.protocol !== "ap+ef61:") throw new TypeError("Invalid portable ActivityPub IRI.");
+		if (portableId.username !== "" || portableId.password !== "" || portableId.port !== "") throw new TypeError("Invalid portable ActivityPub IRI authority.");
+		return portableId.href;
+	}
+	if (typeof portableId !== "string") throw new TypeError("Invalid portable ActivityPub IRI.");
+	return portableId;
+}
+function stripLocationHints(query) {
+	const pairs = query.split("&").filter((pair) => !isLocationHint(pair));
+	return pairs.length < 1 ? "" : `?${pairs.join("&")}`;
+}
+function isLocationHint(pair) {
+	const name = pair.split("=", 1)[0].replace(/\+/g, " ");
+	try {
+		return LOCATION_HINT_PARAMETERS.has(decodeURIComponent(name));
+	} catch (error) {
+		if (error instanceof URIError) return false;
+		throw error;
+	}
+}
+/**
+* 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) {
+	const parsed = new URL(url);
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") throw new UrlError(`Unsupported protocol: ${parsed.protocol}`);
+	let hostname = parsed.hostname;
+	if (hostname.startsWith("[") && hostname.endsWith("]")) hostname = hostname.slice(1, -1);
+	if (hostname === "localhost") throw new UrlError("Localhost is not allowed");
+	const hostnameFamily = (0, node_net.isIP)(hostname);
+	if (hostnameFamily !== 0) {
+		validatePublicIpAddress(hostname, hostnameFamily);
+		return;
+	}
+	if ("Deno" in globalThis && !(0, node_net.isIP)(hostname)) {
+		if ((await Deno.permissions.query({ name: "net" })).state !== "granted") return;
+	}
+	if ("Bun" in globalThis) {
+		if (hostname === "example.com" || hostname.endsWith(".example.com")) return;
+		else if (hostname === "fedify-test.internal") throw new UrlError("Invalid or private address: fedify-test.internal");
+	}
+	let addresses;
+	try {
+		addresses = await node_dns_promises.default.lookup(hostname, { all: true });
+	} catch (error) {
+		throw new UrlError("DNS lookup failed", {
+			cause: error,
+			reason: "dns"
+		});
+	}
+	validateLookupAddresses(addresses);
+}
+/**
+* Validates the IP addresses returned by `node:dns.lookup()`.
+*
+* Cloudflare Workers' `node:dns` implementation currently maps every record
+* in a DNS-over-HTTPS `Answer` array—including CNAME records—to a
+* `LookupAddress`, even though Node.js specifies that the `address` field must
+* contain an IPv4 or IPv6 literal.  See:
+* https://github.com/cloudflare/workerd/issues/6886
+*
+* Work around that bug by ignoring non-IP entries only when the lookup also
+* returns at least one actual IP address.  This remains fail-closed: a result
+* containing no IP addresses is rejected, and every returned IP address is
+* still validated and must be public.  This workaround can be revisited once
+* the Workerd issue is fixed in supported Cloudflare Workers runtimes.
+*
+* @internal
+*/
+function validateLookupAddresses(addresses) {
+	let ipAddressCount = 0;
+	for (const { address } of addresses) {
+		const family = (0, node_net.isIP)(address);
+		if (family === 0) continue;
+		ipAddressCount++;
+		validatePublicIpAddress(address, family);
+	}
+	if (ipAddressCount === 0) throw new UrlError("DNS lookup did not return any IP address", { reason: "dns" });
+}
+function validatePublicIpAddress(address, family) {
+	if (family === 4 && isValidPublicIPv4Address(address) || family === 6 && isValidPublicIPv6Address(address)) return;
+	throw new UrlError(`Invalid or private address: ${address}`);
+}
+function isValidPublicIPv4Address(address) {
+	const parts = parseIPv4Address(address);
+	if (parts == null) return false;
+	const value = ipv4PartsToNumber(parts);
+	return !nonPublicIPv4Prefixes.some(({ base, prefix }) => matchesIPv4Prefix(value, base, prefix));
+}
+function isValidPublicIPv6Address(address) {
+	const words = parseIPv6Address(address);
+	if (words == null) return false;
+	if (nonPublicIPv6Prefixes.some(({ words: prefixWords, prefix }) => matchesIPv6Prefix(words, prefixWords, prefix))) return false;
+	for (const { extractIPv4, prefix, words: prefixWords } of ipv6WithIPv4Prefixes) {
+		if (!matchesIPv6Prefix(words, prefixWords, prefix)) continue;
+		const ipv4Address = extractIPv4(words);
+		if (ipv4Address != null && !isValidPublicIPv4Address(ipv4Address)) return false;
+	}
+	return true;
+}
+function expandIPv6Address(address) {
+	address = address.toLowerCase();
+	const ipv4Delimiter = address.lastIndexOf(":");
+	if (address.includes(".") && ipv4Delimiter >= 0) {
+		const ipv4Parts = parseIPv4Address(address.substring(ipv4Delimiter + 1));
+		if (ipv4Parts == null) return address;
+		const high = (ipv4Parts[0] << 8) + ipv4Parts[1];
+		const low = (ipv4Parts[2] << 8) + ipv4Parts[3];
+		address = address.substring(0, ipv4Delimiter + 1) + high.toString(16) + ":" + low.toString(16);
+	}
+	if (address === "::") return "0000:0000:0000:0000:0000:0000:0000:0000";
+	if (address.startsWith("::")) address = "0000" + address;
+	if (address.endsWith("::")) address = address + "0000";
+	address = address.replace("::", ":0000".repeat(8 - (address.match(/:/g) || []).length) + ":");
+	return address.split(":").map((part) => part.padStart(4, "0")).join(":");
+}
+const nonPublicIPv4Prefixes = [
+	ipv4Prefix("0.0.0.0/8", "RFC 6890"),
+	ipv4Prefix("10.0.0.0/8", "RFC 1918"),
+	ipv4Prefix("100.64.0.0/10", "RFC 6598"),
+	ipv4Prefix("127.0.0.0/8", "RFC 1122"),
+	ipv4Prefix("169.254.0.0/16", "RFC 3927"),
+	ipv4Prefix("172.16.0.0/12", "RFC 1918"),
+	ipv4Prefix("192.0.0.0/24", "RFC 6890"),
+	ipv4Prefix("192.0.2.0/24", "RFC 5737"),
+	ipv4Prefix("192.88.99.0/24", "RFC 7526"),
+	ipv4Prefix("192.168.0.0/16", "RFC 1918"),
+	ipv4Prefix("198.18.0.0/15", "RFC 2544"),
+	ipv4Prefix("198.51.100.0/24", "RFC 5737"),
+	ipv4Prefix("203.0.113.0/24", "RFC 5737"),
+	ipv4Prefix("224.0.0.0/4", "RFC 5771"),
+	ipv4Prefix("240.0.0.0/4", "RFC 1112")
+];
+const nonPublicIPv6Prefixes = [
+	ipv6Prefix("::/16", "RFC 4291"),
+	ipv6Prefix("2001::/32", "RFC 4380"),
+	ipv6Prefix("2002::/16", "RFC 3056"),
+	ipv6Prefix("64:ff9b:1::/48", "RFC 8215"),
+	ipv6Prefix("fc00::/7", "RFC 4193"),
+	ipv6Prefix("fe80::/10", "RFC 4291"),
+	ipv6Prefix("ff00::/8", "RFC 4291")
+];
+const ipv6WithIPv4Prefixes = [{
+	...ipv6Prefix("64:ff9b::/96", "RFC 6052"),
+	extractIPv4: (words) => ipv4FromWords(words[6], words[7])
+}];
+function ipv4Prefix(cidr, rfc) {
+	const [address, prefixText] = cidr.split("/");
+	const prefix = parseInt(prefixText, 10);
+	const parts = parseIPv4Address(address);
+	if (parts == null || !Number.isInteger(prefix) || prefix < 0 || prefix > 32) throw new Error(`Invalid IPv4 prefix: ${cidr}`);
+	return {
+		cidr,
+		base: ipv4PartsToNumber(parts),
+		prefix,
+		rfc
+	};
+}
+function ipv6Prefix(cidr, rfc) {
+	const [address, prefixText] = cidr.split("/");
+	const prefix = parseInt(prefixText, 10);
+	const words = parseIPv6Address(address);
+	if (words == null || !Number.isInteger(prefix) || prefix < 0 || prefix > 128) throw new Error(`Invalid IPv6 prefix: ${cidr}`);
+	return {
+		cidr,
+		words,
+		prefix,
+		rfc
+	};
+}
+function parseIPv4Address(address) {
+	const parts = address.split(".").map((part) => {
+		if (!/^\d+$/.test(part)) return NaN;
+		return parseInt(part, 10);
+	});
+	if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) return null;
+	return parts;
+}
+function parseIPv6Address(address) {
+	const parts = expandIPv6Address(address).split(":");
+	if (parts.length !== 8) return null;
+	const words = parts.map((part) => {
+		if (!/^[0-9a-f]{1,4}$/i.test(part)) return NaN;
+		return parseInt(part, 16);
+	});
+	if (words.some((word) => !Number.isInteger(word) || word < 0 || word > 65535)) return null;
+	return words;
+}
+function ipv4PartsToNumber(parts) {
+	return parts[0] * 2 ** 24 + parts[1] * 2 ** 16 + parts[2] * 2 ** 8 + parts[3];
+}
+function ipv4FromWords(highWord, lowWord) {
+	return [
+		highWord >> 8,
+		highWord & 255,
+		lowWord >> 8,
+		lowWord & 255
+	].join(".");
+}
+function matchesIPv4Prefix(address, prefixBase, prefixLength) {
+	const blockSize = 2 ** (32 - prefixLength);
+	return Math.floor(address / blockSize) === Math.floor(prefixBase / blockSize);
+}
+function matchesIPv6Prefix(address, prefixWords, prefixLength) {
+	let remaining = prefixLength;
+	for (let i = 0; i < 8 && remaining > 0; i++) if (remaining >= 16) {
+		if (address[i] !== prefixWords[i]) return false;
+		remaining -= 16;
+	} else {
+		const mask = 65535 << 16 - remaining & 65535;
+		if ((address[i] & mask) !== (prefixWords[i] & mask)) return false;
+		remaining = 0;
+	}
+	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() {
+		return UrlError;
+	}
+});
+Object.defineProperty(exports, "arePortableUrisEqual", {
+	enumerable: true,
+	get: function() {
+		return arePortableUrisEqual;
+	}
+});
+Object.defineProperty(exports, "canonicalizePortableUri", {
+	enumerable: true,
+	get: function() {
+		return canonicalizePortableUri;
+	}
+});
+Object.defineProperty(exports, "expandIPv6Address", {
+	enumerable: true,
+	get: function() {
+		return expandIPv6Address;
+	}
+});
+Object.defineProperty(exports, "formatIri", {
+	enumerable: true,
+	get: function() {
+		return formatIri;
+	}
+});
+Object.defineProperty(exports, "fromCompatibleEf61Id", {
+	enumerable: true,
+	get: function() {
+		return fromCompatibleEf61Id;
+	}
+});
+Object.defineProperty(exports, "getFe34Origin", {
+	enumerable: true,
+	get: function() {
+		return getFe34Origin;
+	}
+});
+Object.defineProperty(exports, "getGatewayHints", {
+	enumerable: true,
+	get: function() {
+		return getGatewayHints;
+	}
+});
+Object.defineProperty(exports, "haveSameFe34Origin", {
+	enumerable: true,
+	get: function() {
+		return haveSameFe34Origin;
+	}
+});
+Object.defineProperty(exports, "haveSameIriOrigin", {
+	enumerable: true,
+	get: function() {
+		return haveSameIriOrigin;
+	}
+});
+Object.defineProperty(exports, "isGatewayUrl", {
+	enumerable: true,
+	get: function() {
+		return isGatewayUrl;
+	}
+});
+Object.defineProperty(exports, "isValidPublicIPv4Address", {
+	enumerable: true,
+	get: function() {
+		return isValidPublicIPv4Address;
+	}
+});
+Object.defineProperty(exports, "isValidPublicIPv6Address", {
+	enumerable: true,
+	get: function() {
+		return isValidPublicIPv6Address;
+	}
+});
+Object.defineProperty(exports, "parseGatewayOrigin", {
+	enumerable: true,
+	get: function() {
+		return parseGatewayOrigin;
+	}
+});
+Object.defineProperty(exports, "parseGatewayUrl", {
+	enumerable: true,
+	get: function() {
+		return parseGatewayUrl;
+	}
+});
+Object.defineProperty(exports, "parseIri", {
+	enumerable: true,
+	get: function() {
+		return parseIri;
+	}
+});
+Object.defineProperty(exports, "parseJsonLdId", {
+	enumerable: true,
+	get: function() {
+		return parseJsonLdId;
+	}
+});
+Object.defineProperty(exports, "toCompatibleEf61Id", {
+	enumerable: true,
+	get: function() {
+		return toCompatibleEf61Id;
+	}
+});
+Object.defineProperty(exports, "validatePublicUrl", {
+	enumerable: true,
+	get: function() {
+		return validatePublicUrl;
+	}
+});
+Object.defineProperty(exports, "withGatewayHints", {
+	enumerable: true,
+	get: function() {
+		return withGatewayHints;
+	}
+});
+Object.defineProperty(exports, "withoutGatewayHints", {
+	enumerable: true,
+	get: function() {
+		return withoutGatewayHints;
+	}
+});