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

package/dist/url-Dzyp-NsC.js

@@ -0,0 +1,860 @@
+
+import dns from "node:dns/promises";
+import { isIP } from "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 = isIP(hostname);
+	if (hostnameFamily !== 0) {
+		validatePublicIpAddress(hostname, hostnameFamily);
+		return;
+	}
+	if ("Deno" in globalThis && !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 dns.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 = 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
+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 };