@fedify/vocab-runtime 2.4.0-dev.2030 → 2.4.0-dev.2047

package/dist/tests/url.test.mjs

@@ -1,4 +1,4 @@
-import { a as formatIri, c as haveSameIriOrigin, d as isValidPublicIPv6Address, f as parseGatewayUrl, g as validatePublicUrl, h as validateLookupAddresses, i as expandIPv6Address, l as isGatewayUrl, m as parseJsonLdId, n as arePortableUrisEqual, o as getFe34Origin, p as parseIri, r as canonicalizePortableUri, s as haveSameFe34Origin, t as UrlError, u as isValidPublicIPv4Address } from "./url-Basm1L_c.mjs";
+import { _ as validateLookupAddresses, a as formatIri, c as haveSameFe34Origin, d as isValidPublicIPv4Address, f as isValidPublicIPv6Address, g as toCompatibleEf61Id, h as parseJsonLdId, i as expandIPv6Address, l as haveSameIriOrigin, m as parseIri, n as arePortableUrisEqual, o as fromCompatibleEf61Id, p as parseGatewayUrl, r as canonicalizePortableUri, s as getFe34Origin, t as UrlError, u as isGatewayUrl, v as validatePublicUrl } from "./url-DgJM9WJn.mjs";
 import { test } from "node:test";
 import { deepStrictEqual, ok, rejects, throws } from "node:assert";
 //#region src/url.test.ts
@@ -244,6 +244,225 @@ test("parseGatewayUrl() accepts only HTTP(S) base URIs", () => {
 		ok(!isGatewayUrl(new URL(url)));
 	}
 });
+test("fromCompatibleEf61Id() converts compatible identifiers", () => {
+	for (const [input, expected] of [
+		["https://server.example/.well-known/apgateway/did:key:z6MkAlice/objects/1", "ap+ef61://did%3Akey%3Az6MkAlice/objects/1"],
+		["http://server.example:8080/.well-known/apgateway/did:key:z6MkAlice/actor", "ap+ef61://did%3Akey%3Az6MkAlice/actor"],
+		["https://server.example/.well-known/apgateway/did%3Akey%3Az6MkAlice/actor", "ap+ef61://did%3Akey%3Az6MkAlice/actor"],
+		["https://server.example/.well-known/apgateway/DID:key:z6MkAlice/actor", "ap+ef61://did%3Akey%3Az6MkAlice/actor"],
+		["https://server.example/.well-known/apgateway/did:key:z6MkAlice/a/b/c", "ap+ef61://did%3Akey%3Az6MkAlice/a/b/c"],
+		["https://server.example/.well-known/apgateway/did:key:z6MkAlice/actor#main-key", "ap+ef61://did%3Akey%3Az6MkAlice/actor#main-key"],
+		["https://server.example/.well-known/apgateway/did:key:z6MkAlice/actor#", "ap+ef61://did%3Akey%3Az6MkAlice/actor#"],
+		["https://server.example/.well-known/apgateway/did:key:z6MkAlice/outbox?page=2", "ap+ef61://did%3Akey%3Az6MkAlice/outbox?page=2"],
+		["https://server.example/.well-known/apgateway/did:key:z6MkAlice/a%2Fb", "ap+ef61://did%3Akey%3Az6MkAlice/a%2Fb"],
+		["https://server.example/.well-known/apgateway/did:web:example.com%3A8080/actor", "ap+ef61://did%3Aweb%3Aexample.com%253A8080/actor"],
+		["https://server.example/.well-known/apgateway/did:example:a%2525/x", "ap+ef61://did%3Aexample%3Aa%2525/x"]
+	]) {
+		deepStrictEqual(fromCompatibleEf61Id(input)?.href, expected, input);
+		deepStrictEqual(fromCompatibleEf61Id(new URL(input))?.href, expected, input);
+	}
+	const converted = fromCompatibleEf61Id("https://server.example/.well-known/apgateway/did:key:z6MkAlice/objects/1");
+	deepStrictEqual(formatIri(converted), "ap+ef61://did:key:z6MkAlice/objects/1");
+	deepStrictEqual(canonicalizePortableUri(converted.href), "ap+ef61://did:key:z6MkAlice/objects/1");
+	ok(arePortableUrisEqual(fromCompatibleEf61Id("https://a.example/.well-known/apgateway/did:key:z6MkAlice/actor").href, fromCompatibleEf61Id("https://b.example/.well-known/apgateway/did:key:z6MkAlice/actor").href));
+});
+test("fromCompatibleEf61Id() returns null for other URLs", () => {
+	for (const input of [
+		"https://server.example/users/alice",
+		"https://server.example/.well-known/webfinger?resource=acct:a@b",
+		"https://server.example/.well-known/apgateway",
+		"https://server.example/.well-known/apgateway/",
+		"https://server.example/.well-known/apgateway/hl:zQmdfTbBqBPQ7VNxZEYEj14VmRuZBkqFbiwReogJgS1zR1n",
+		"https://server.example/.well-known/apgateway/objects/did:key:z6MkAlice/x",
+		"https://server.example/.well-known/apgatewayx/did:key:z6MkAlice/x",
+		"https://server.example/ap/did:key:z6MkAlice/actor",
+		"https://server.example/?id=/.well-known/apgateway/did:key:z6MkAlice/x",
+		"ap://did:key:z6MkAlice/actor",
+		"ap+ef61://did:key:z6MkAlice/actor",
+		"ftp://server.example/.well-known/apgateway/did:key:z6MkAlice/actor",
+		"not a URL",
+		"/.well-known/apgateway/did:key:z6MkAlice/actor"
+	]) deepStrictEqual(fromCompatibleEf61Id(input), null, input);
+	deepStrictEqual(fromCompatibleEf61Id(new URL("ap+ef61://did%3Akey%3Az6MkAlice/actor")), null);
+	deepStrictEqual(fromCompatibleEf61Id(123), null);
+});
+test("fromCompatibleEf61Id() rejects malformed compatible identifiers", () => {
+	for (const input of [
+		"https://server.example/.well-known/apgateway/did:key:z6MkAlice",
+		"https://server.example/.well-known/apgateway/did:",
+		"https://server.example/.well-known/apgateway/did:key/actor",
+		"https://server.example/.well-known/apgateway/did:ke%y:z6MkAlice/actor",
+		"https://server.example/.well-known/apgateway/did:key:z6MkAlice/a%zz",
+		"https://server.example/.well-known/apgateway/did:key:z6MkAlice/a#%zz",
+		"https://server.example/.well-known/apgateway/did:key:z6MkAlice/a?x=%zz",
+		"https://server.example/.well-known/apgateway/did:key:z6MkAlice/a?@gateway=https%3A%2F%2Fevil.example",
+		"https://server.example/.well-known/apgateway/did:key:z6MkAlice/a?page=2&%40gateway=x",
+		"https://server.example/.well-known/apgateway/did:key:z6MkAlice/a?@%67ateway=x",
+		"https://server.example/.well-known/apgateway/did:key:z6MkAlice/a?gateways=x",
+		"https://server.example/.well-known/apgateway/did:example:a%25/x",
+		"https://user:pass@server.example/.well-known/apgateway/did:key:z6MkAlice/a",
+		"https://user@server.example/.well-known/apgateway/did:key:z6MkAlice/a"
+	]) throws(() => fromCompatibleEf61Id(input), TypeError, input);
+});
+test("toCompatibleEf61Id() converts portable URIs", () => {
+	const cases = [
+		[
+			"ap+ef61://did:key:z6MkAlice/objects/1",
+			"https://server.example",
+			"https://server.example/.well-known/apgateway/did:key:z6MkAlice/objects/1"
+		],
+		[
+			"ap://did:key:z6MkAlice/objects/1",
+			"https://server.example/",
+			"https://server.example/.well-known/apgateway/did:key:z6MkAlice/objects/1"
+		],
+		[
+			"ap://did%3Akey%3Az6MkAlice/actor",
+			new URL("http://server.example:8080"),
+			"http://server.example:8080/.well-known/apgateway/did:key:z6MkAlice/actor"
+		],
+		[
+			new URL("ap+ef61://did%3Akey%3Az6MkAlice/actor"),
+			"https://server.example",
+			"https://server.example/.well-known/apgateway/did:key:z6MkAlice/actor"
+		],
+		[
+			new URL("ap://did%3Akey%3Az6MkAlice/actor"),
+			"https://SERVER.example",
+			"https://server.example/.well-known/apgateway/did:key:z6MkAlice/actor"
+		],
+		[
+			"ap://did:key:z6MkAlice/a/b/c",
+			"https://server.example",
+			"https://server.example/.well-known/apgateway/did:key:z6MkAlice/a/b/c"
+		],
+		[
+			"ap://did:key:z6MkAlice/actor#main-key",
+			"https://server.example",
+			"https://server.example/.well-known/apgateway/did:key:z6MkAlice/actor#main-key"
+		],
+		[
+			"ap://did:key:z6MkAlice/actor#",
+			"https://server.example",
+			"https://server.example/.well-known/apgateway/did:key:z6MkAlice/actor#"
+		],
+		[
+			"ap://DID:key:z6MkAlice/actor",
+			"https://server.example",
+			"https://server.example/.well-known/apgateway/did:key:z6MkAlice/actor"
+		],
+		[
+			"ap://did:example:a%2525/x",
+			"https://server.example",
+			"https://server.example/.well-known/apgateway/did:example:a%2525/x"
+		],
+		[
+			"ap://did:web:example.com%3A8080/actor",
+			"https://server.example",
+			"https://server.example/.well-known/apgateway/did:web:example.com%3A8080/actor"
+		],
+		[
+			"ap://did:key:z6MkAlice/a%2Fb/%252e",
+			"https://server.example",
+			"https://server.example/.well-known/apgateway/did:key:z6MkAlice/a%2Fb/%252e"
+		],
+		[
+			"ap://did:key:z6MkAlice/a\\b c	é/%7euser",
+			"https://server.example",
+			"https://server.example/.well-known/apgateway/did:key:z6MkAlice/a%5Cb%20c%09%C3%A9/~user"
+		]
+	];
+	for (const [portableId, gateway, expected] of cases) deepStrictEqual(toCompatibleEf61Id(portableId, gateway).href, expected, String(portableId));
+});
+test("toCompatibleEf61Id() removes location hints from queries", () => {
+	const base = "https://server.example/.well-known/apgateway/did:key:z6MkAlice";
+	const cases = [
+		["ap://did:key:z6MkAlice/actor?@gateway=https%3A%2F%2Fa.example&@gateway=https%3A%2F%2Fb.example", `${base}/actor`],
+		["ap://did:key:z6MkAlice/actor?gateways=https%3A%2F%2Fa.example", `${base}/actor`],
+		["ap://did:key:z6MkAlice/actor?%40gateway=https%3A%2F%2Fa.example", `${base}/actor`],
+		["ap://did:key:z6MkAlice/actor?@%67ateway=https%3A%2F%2Fa.example", `${base}/actor`],
+		["ap://did:key:z6MkAlice/actor?@gateway", `${base}/actor`],
+		["ap://did:key:z6MkAlice/c?page=3&@gateway=https%3A%2F%2Fa.example&maxItems=20&page=4", `${base}/c?page=3&maxItems=20&page=4`],
+		["ap://did:key:z6MkAlice/c?a=1&&b=2#frag", `${base}/c?a=1&&b=2#frag`],
+		["ap://did:key:z6MkAlice/c?", `${base}/c?`],
+		["ap://did:key:z6MkAlice/c?x='y'", `${base}/c?x=%27y%27`],
+		["ap://did:key:z6MkAlice/c?@gate	way=https%3A%2F%2Fa.example", `${base}/c?@gate%09way=https%3A%2F%2Fa.example`],
+		["ap://did:key:z6MkAlice/c?@gate\nway=1&x=\r2", `${base}/c?@gate%0Away=1&x=%0D2`],
+		["ap://did:key:z6MkAlice/c?%ff=1", `${base}/c?%FF=1`]
+	];
+	for (const [portableId, expected] of cases) {
+		const result = toCompatibleEf61Id(portableId, "https://server.example");
+		deepStrictEqual(result.href, expected, portableId);
+		ok(!/[?&](%40|@)gateway(=|&|$)/i.test(result.search), portableId);
+	}
+});
+test("toCompatibleEf61Id() rejects invalid portable IDs", () => {
+	const cases = [
+		"https://server.example/actor",
+		"https://server.example/.well-known/apgateway/did:key:z6MkAlice/actor",
+		"at://did:plc:example/record",
+		"ap://not-a-did/actor",
+		"ap://did:key:z6MkAlice",
+		"ap://did:key:z6MkAlice/a%zz",
+		"ap://did:key:z6MkAlice/a#%zz",
+		"ap://did:key:z6MkAlice/a?x=%zz",
+		"ap://did:key:z6MkAlice/.",
+		"ap://did:key:z6MkAlice/..",
+		"ap://did:key:z6MkAlice/a/./b",
+		"ap://did:key:z6MkAlice/a/../b",
+		"ap://did:key:z6MkAlice/a/%2e/b",
+		"ap://did:key:z6MkAlice/a/%2E%2e/b",
+		"ap://did:key:z6MkAlice/a/.%2e/b",
+		"ap://did:key:z6MkAlice/a/%2e./b",
+		new URL("https://server.example/actor"),
+		new URL("ap+ef61://user:pass@did%3Akey%3Az6MkAlice/actor"),
+		new URL("ap+ef61://did%3Akey%3Az6MkAlice:8080/actor"),
+		123
+	];
+	for (const portableId of cases) throws(() => toCompatibleEf61Id(portableId, "https://server.example"), TypeError, String(portableId));
+});
+test("toCompatibleEf61Id() rejects gateways that are not HTTP(S) origins", () => {
+	const cases = [
+		"ftp://server.example",
+		"ap+ef61://did:key:z6MkAlice/actor",
+		"https://user:pass@server.example",
+		"https://user@server.example",
+		"https://server.example/ap",
+		"https://server.example/ap/",
+		"https://server.example/.well-known/apgateway",
+		"https://server.example/?x=1",
+		"https://server.example/?",
+		"https://server.example/#fragment",
+		"https://server.example/#",
+		"server.example",
+		"",
+		new URL("https://server.example/?"),
+		new URL("https://server.example/#"),
+		new URL("https://server.example/ap"),
+		new URL("ftp://server.example/"),
+		123
+	];
+	for (const gateway of cases) throws(() => toCompatibleEf61Id("ap://did:key:z6MkAlice/actor", gateway), TypeError, String(gateway));
+});
+test("compatible identifier conversion round-trips", () => {
+	for (const portableId of [
+		"ap+ef61://did:key:z6MkAlice/objects/1",
+		"ap://did:key:z6MkAlice/actor",
+		"ap://did%3Akey%3Az6MkAlice/actor/inbox",
+		"ap://did:key:z6MkAlice/actor#",
+		"ap://did:key:z6MkAlice/actor#main-key",
+		"ap://did:key:z6MkAlice/a%2Fb/%252e",
+		"ap://did:key:z6MkAlice/a\\b c	é",
+		"ap://did:example:a%2525/x",
+		"ap://did:web:example.com%3A8080/actor",
+		"ap://did:key:z6MkAlice/c?page=3&@gateway=https%3A%2F%2Fa.example"
+	]) {
+		const converted = fromCompatibleEf61Id(toCompatibleEf61Id(portableId, "https://server.example"));
+		ok(converted != null, portableId);
+		deepStrictEqual(canonicalizePortableUri(converted.href), canonicalizePortableUri(portableId), portableId);
+	}
+	ok(!arePortableUrisEqual(fromCompatibleEf61Id(toCompatibleEf61Id("ap://did:key:z6MkAlice/actor", "https://server.example")).href, fromCompatibleEf61Id(toCompatibleEf61Id("ap://did:key:z6MkAlice/actor#", "https://server.example")).href));
+});
 test("validatePublicUrl()", async () => {
 	await rejects(() => validatePublicUrl("ftp://localhost"), UrlError);
 	await rejects(() => validatePublicUrl("data:text/plain;base64,SGVsbG8sIFdvcmxkIQ=="), UrlError);

package/dist/{url-BHAShw9J.js → url-CEhi4hb4.js}

@@ -224,6 +224,152 @@ function parseGatewayUrl(url) {
 	if (!isGatewayUrl(parsed)) throw new TypeError("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 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), which FEP-ef61 forbids in
+*                     compatible identifiers.
+* @since 2.4.0
+*/
+function fromCompatibleEf61Id(input) {
+	return convertCompatibleEf61Id(input)?.url ?? null;
+}
+function convertCompatibleEf61Id(input) {
+	let url;
+	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 (!url.pathname.startsWith(COMPATIBLE_ID_PATH_PREFIX)) return null;
+	const tail = url.pathname.slice(23);
+	if (!COMPATIBLE_ID_DID_PATTERN.test(tail)) 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.");
+		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), 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 || 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.");
+	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;
+	}
+}
 /**
 * Validates a URL to prevent SSRF attacks.
 */
@@ -417,4 +563,4 @@ function matchesIPv6Prefix(address, prefixWords, prefixLength) {
 	return true;
 }
 //#endregion
-export { formatIri as a, haveSameIriOrigin as c, isValidPublicIPv6Address as d, parseGatewayUrl as f, validatePublicUrl as h, expandIPv6Address as i, isGatewayUrl as l, parseJsonLdId as m, arePortableUrisEqual as n, getFe34Origin as o, parseIri as p, canonicalizePortableUri as r, haveSameFe34Origin as s, UrlError as t, isValidPublicIPv4Address as u };
+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 };

package/dist/{tests/url-CPfMatUL.cjs → url-Cke4irYD.cjs}

@@ -1,3 +1,4 @@
+
 let node_dns_promises = require("node:dns/promises");
 let node_net = require("node:net");
 //#region src/url.ts
@@ -223,6 +224,152 @@ function parseGatewayUrl(url) {
 	if (!isGatewayUrl(parsed)) throw new TypeError("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 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), which FEP-ef61 forbids in
+*                     compatible identifiers.
+* @since 2.4.0
+*/
+function fromCompatibleEf61Id(input) {
+	return convertCompatibleEf61Id(input)?.url ?? null;
+}
+function convertCompatibleEf61Id(input) {
+	let url;
+	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 (!url.pathname.startsWith(COMPATIBLE_ID_PATH_PREFIX)) return null;
+	const tail = url.pathname.slice(23);
+	if (!COMPATIBLE_ID_DID_PATTERN.test(tail)) 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.");
+		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), 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 || 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.");
+	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;
+	}
+}
 /**
 * Validates a URL to prevent SSRF attacks.
 */
@@ -446,6 +593,12 @@ Object.defineProperty(exports, "formatIri", {
 		return formatIri;
 	}
 });
+Object.defineProperty(exports, "fromCompatibleEf61Id", {
+	enumerable: true,
+	get: function() {
+		return fromCompatibleEf61Id;
+	}
+});
 Object.defineProperty(exports, "getFe34Origin", {
 	enumerable: true,
 	get: function() {
@@ -500,10 +653,10 @@ Object.defineProperty(exports, "parseJsonLdId", {
 		return parseJsonLdId;
 	}
 });
-Object.defineProperty(exports, "validateLookupAddresses", {
+Object.defineProperty(exports, "toCompatibleEf61Id", {
 	enumerable: true,
 	get: function() {
-		return validateLookupAddresses;
+		return toCompatibleEf61Id;
 	}
 });
 Object.defineProperty(exports, "validatePublicUrl", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/vocab-runtime",
-  "version": "2.4.0-dev.2030+e6b3de3d",
+  "version": "2.4.0-dev.2047+140b94db",
   "homepage": "https://fedify.dev/",
   "repository": {
     "type": "git",
@@ -52,6 +52,16 @@
       "require": "./dist/internal/jsonld-cache.cjs",
       "default": "./dist/internal/jsonld-cache.js"
     },
+    "./internal/portable-dereference": {
+      "types": {
+        "import": "./dist/internal/portable-dereference.d.ts",
+        "require": "./dist/internal/portable-dereference.d.cts",
+        "default": "./dist/internal/portable-dereference.d.ts"
+      },
+      "import": "./dist/internal/portable-dereference.js",
+      "require": "./dist/internal/portable-dereference.cjs",
+      "default": "./dist/internal/portable-dereference.js"
+    },
     "./internal/signed-representation": {
       "types": {
         "import": "./dist/internal/signed-representation.d.ts",
@@ -86,7 +96,7 @@
   },
   "license": "MIT",
   "devDependencies": {
-    "@types/node": "^24.2.1",
+    "@types/node": "^24.12.2",
     "fetch-mock": "^12.5.4",
     "tsdown": "^0.22.0",
     "typescript": "^6.0.0"