@fedify/vocab-runtime 2.4.0-dev.2256 → 2.4.0-dev.2260

package/dist/tests/portable-dereference-DRE5bz-l.mjs

@@ -0,0 +1,249 @@
+import { t as preloadedContexts } from "./contexts-CIKsin4e.mjs";
+import { h as parseGatewayOrigin, o as formatIri, s as fromCompatibleEf61Id, t as GATEWAY_HINT_PARAMETER, u as haveSameFe34Origin } from "./url-DMxmp7ZG.mjs";
+import { c as unwrapReleasedDocumentLoader, s as registerDocumentLoaderWrapper } from "./jsonld-cache-BPQmOZWD.mjs";
+import { getLogger } from "@logtape/logtape";
+import "@opentelemetry/api";
+//#region src/internal/portable-dereference.ts
+const logger = getLogger([
+	"fedify",
+	"vocab",
+	"gateway"
+]);
+/**
+* The maximum number of `@gateway` location hints to try for one reference.
+* Hints come from possibly untrusted documents, so they are bounded to keep
+* a single accessor call from fanning out to many servers.
+*/
+const MAX_GATEWAY_HINTS = 5;
+const BASELINE_CONTEXT_URLS = /* @__PURE__ */ new Set([
+	"https://w3id.org/identity/v1",
+	"https://www.w3.org/ns/activitystreams",
+	"https://w3id.org/security/v1",
+	"https://w3id.org/security/data-integrity/v1"
+]);
+const provenances = /* @__PURE__ */ new WeakMap();
+function getObjectId(object) {
+	if (object == null || typeof object !== "object" || !("id" in object)) return null;
+	const id = object.id;
+	return id instanceof URL ? id : null;
+}
+/**
+* Checks whether a vocabulary object is part of a chain of portable objects,
+* i.e., whether it has a portable ID, has an FEP-ef61 compatible identifier
+* as its ID (even a malformed one, so that it fails closed), or was obtained
+* from a portable object.  Accessors of such objects dereference references
+* as portable objects.
+*
+* Being part of a chain does not mean that the object itself is verified:
+* an object parsed from arbitrary JSON-LD is in a chain just because of its
+* ID.  Only {@link dereferencePortableIri} records that an object was
+* accepted by a verifier.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+function isInPortableChain(object) {
+	if (provenances.has(object)) return true;
+	const id = getObjectId(object);
+	return id != null && (isPortableIri(id) || isCompatibleEf61Iri(id));
+}
+/**
+* Checks whether a URL is an FEP-ef61 compatible identifier, i.e., an HTTP(S)
+* URL under a gateway's `/.well-known/apgateway/` path that stands for
+* a portable object.  Malformed compatible identifiers count as compatible
+* identifiers too.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+function isCompatibleEf61Iri(url) {
+	try {
+		return fromCompatibleEf61Id(url) != null;
+	} catch (error) {
+		if (error instanceof TypeError) return true;
+		throw error;
+	}
+}
+/**
+* Records that a vocabulary object returned by a property accessor was
+* obtained through the given property of a portable object, so that later
+* dereferences from it can tell where it came from.  Nothing is recorded if
+* the parent is not in a portable chain, or if the child already has its
+* provenance.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+function recordPortableReferrer(parent, child, property) {
+	if (child == null || typeof child !== "object") return;
+	if (provenances.has(child) || !isInPortableChain(parent)) return;
+	provenances.set(child, { referrer: {
+		object: parent,
+		property
+	} });
+}
+/**
+* Checks whether a URL is an FEP-ef61 portable ActivityPub IRI.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+function isPortableIri(url) {
+	return url.protocol === "ap+ef61:" || url.protocol === "ap:";
+}
+/**
+* Picks the ordered list of FEP-ef61 gateways to fetch a portable IRI from.
+*
+* If `gateways` is given, it is used as is (even when empty), and `@gateway`
+* location hints in the IRI are ignored.  Otherwise, up to
+* {@link MAX_GATEWAY_HINTS} valid `@gateway` hints are used.  Duplicate
+* gateways are dropped in both cases.
+*
+* @throws {TypeError} If an explicit gateway is not an HTTP(S) origin.
+* @internal
+*/
+function getPortableGatewayCandidates(url, gateways) {
+	const candidates = [];
+	const seen = /* @__PURE__ */ new Set();
+	const add = (gateway) => {
+		if (seen.has(gateway.href)) return;
+		seen.add(gateway.href);
+		candidates.push(gateway);
+	};
+	if (gateways != null) {
+		for (const gateway of gateways) {
+			const parsed = parseGatewayOrigin(gateway);
+			if (parsed == null) throw new TypeError("FEP-ef61 gateways must be HTTP(S) origins with no credentials, path, query, or fragment: " + String(gateway));
+			add(parsed);
+		}
+		return candidates;
+	}
+	for (const hint of new URLSearchParams(url.search).getAll(GATEWAY_HINT_PARAMETER)) {
+		if (candidates.length >= MAX_GATEWAY_HINTS) break;
+		const parsed = parseGatewayOrigin(hint);
+		if (parsed == null) {
+			logger.debug("Ignoring an invalid FEP-ef61 gateway hint {hint} in {url}.", {
+				hint,
+				url: formatIri(url)
+			});
+			continue;
+		}
+		add(parsed);
+	}
+	return candidates;
+}
+/**
+* Gets the gateways through which a portable reference without location hints
+* can be dereferenced, from the portable actor that the reference belongs to.
+*
+* The references in a portable actor's own document, such as its `outbox`,
+* usually have no `@gateway` hints, as they are not needed there, since
+* the actor's `gateways` already tells where to retrieve them.  So this walks
+* from the object whose property is being dereferenced up through the objects
+* it was obtained from, e.g., from a collection page to the collection and
+* then to the actor, and returns the `gateways` of the first object that has
+* any, but only if that object has the same DID as the reference.  The
+* gateways only tell where to look; whatever they serve is still verified.
+*
+* @param object The object whose property is being dereferenced.
+* @param url The portable IRI to dereference.
+* @returns Up to {@link MAX_GATEWAY_HINTS} valid gateways, or `undefined` if
+*          the IRI has valid `@gateway` hints or no such object is found.
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+function getReferrerGateways(object, url) {
+	if (getPortableGatewayCandidates(url).length > 0) return void 0;
+	const visited = /* @__PURE__ */ new Set();
+	let current = object;
+	while (current != null && !visited.has(current)) {
+		visited.add(current);
+		const gateways = "gateways" in current ? current.gateways : void 0;
+		if (Array.isArray(gateways) && gateways.length > 0) {
+			const id = getObjectId(current);
+			const portableId = id == null ? null : isPortableIri(id) ? id : getCompatibleEf61Target(id);
+			if (portableId == null || !haveSameFe34Origin(portableId, url)) return;
+			const candidates = [];
+			for (const gateway of gateways) {
+				if (candidates.length >= MAX_GATEWAY_HINTS) break;
+				if (typeof gateway !== "string" && !(gateway instanceof URL)) continue;
+				const parsed = parseGatewayOrigin(gateway);
+				if (parsed == null) continue;
+				if (candidates.some((c) => c.href === parsed.href)) continue;
+				candidates.push(parsed);
+			}
+			return candidates.length > 0 ? candidates : void 0;
+		}
+		current = provenances.get(current)?.referrer?.object;
+	}
+}
+function getCompatibleEf61Target(id) {
+	try {
+		return fromCompatibleEf61Id(id);
+	} catch {
+		return null;
+	}
+}
+/**
+* Creates a context loader that returns the same context documents for the
+* whole dereference operation, so that the identity check, the proof
+* verifier, and the parser interpret the fetched document identically even
+* if the underlying loader is nondeterministic.  Failed loads are not
+* remembered, so a transient failure does not affect the next gateway.
+*
+* The parsed object keeps the loader for its own later dereferences, so
+* `release()` turns it into a plain pass-through to the underlying loader
+* once the operation is over.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+function createSnapshotContextLoader(contextLoader, suppressError) {
+	contextLoader = unwrapReleasedDocumentLoader(contextLoader);
+	const cache = /* @__PURE__ */ new Map();
+	let released = false;
+	const release = () => {
+		released = true;
+		state.released = true;
+		cache.clear();
+	};
+	const loader = async (url, options) => {
+		if (released) return await contextLoader(url, options);
+		const key = URL.canParse(url) ? new URL(url).href : url;
+		if (BASELINE_CONTEXT_URLS.has(key)) return {
+			contextUrl: null,
+			document: structuredClone(preloadedContexts[key]),
+			documentUrl: key
+		};
+		let promise = cache.get(key);
+		if (promise == null) {
+			const loading = contextLoader(url, suppressError ? {
+				...options,
+				suppressError: true
+			} : options).then((document) => structuredClone(document));
+			promise = loading;
+			cache.set(key, loading);
+			loading.catch(() => {
+				if (cache.get(key) === loading) cache.delete(key);
+			});
+		}
+		return structuredClone(await promise);
+	};
+	const state = {
+		base: contextLoader,
+		released: false
+	};
+	registerDocumentLoaderWrapper(loader, state);
+	return {
+		loader,
+		release
+	};
+}
+//#endregion
+export { recordPortableReferrer as a, isPortableIri as i, getPortableGatewayCandidates as n, getReferrerGateways as r, createSnapshotContextLoader as t };

package/dist/tests/{portable-media-HeXeBuyd.cjs → portable-media-BC-QRzPd.cjs}

@@ -1,6 +1,6 @@
-const require_request = require("./request-BE3wHjK4.cjs");
-const require_body = require("./body-ILOzDJe-.cjs");
-const require_url = require("./url-Ddeuv0sE.cjs");
+const require_request = require("./request-kRkxuOkZ.cjs");
+const require_body = require("./body-edyRdC9n.cjs");
+const require_url = require("./url-BNakuZ8k.cjs");
 const require_digest = require("./digest-3FeH2Y-Q.cjs");
 //#region src/portable-media.ts
 function resolveTimeout(value, fallback) {

package/dist/tests/{portable-media-SWj7DacP.mjs → portable-media-CP6hh3ja.mjs}

@@ -1,6 +1,6 @@
-import { r as getUserAgent } from "./request-DkiHcgVt.mjs";
-import { r as readBoundedBytes } from "./body-NALc-7u_.mjs";
-import { g as parseGatewayUrl, x as validatePublicUrl } from "./url-ClVBNQup.mjs";
+import { r as getUserAgent } from "./request-D-SOvXf_.mjs";
+import { r as readBoundedBytes } from "./body-BbkIKvTI.mjs";
+import { g as parseGatewayUrl, x as validatePublicUrl } from "./url-DMxmp7ZG.mjs";
 import { a as verifyDigestMultibase, i as parseHashlink, r as parseDigestMultibase } from "./digest-COC7xDiQ.mjs";
 //#region src/portable-media.ts
 function resolveTimeout(value, fallback) {

package/dist/tests/portable-media.test.cjs

@@ -1,5 +1,5 @@
 const require_digest = require("./digest-3FeH2Y-Q.cjs");
-const require_portable_media = require("./portable-media-HeXeBuyd.cjs");
+const require_portable_media = require("./portable-media-BC-QRzPd.cjs");
 let node_assert_strict = require("node:assert/strict");
 let node_test = require("node:test");
 let node_http = require("node:http");

package/dist/tests/portable-media.test.mjs

@@ -1,5 +1,5 @@
 import { n as createHashlink, t as computeDigestMultibase } from "./digest-COC7xDiQ.mjs";
-import { t as fetchPortableMedia } from "./portable-media-SWj7DacP.mjs";
+import { t as fetchPortableMedia } from "./portable-media-CP6hh3ja.mjs";
 import { deepStrictEqual, equal, rejects } from "node:assert/strict";
 import { test } from "node:test";
 import { createServer } from "node:http";

package/dist/tests/portable-workers.test.cjs

@@ -1,8 +1,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_url = require("./url-Ddeuv0sE.cjs");
+const require_url = require("./url-BNakuZ8k.cjs");
 const require_key = require("./key-C-AYkdJJ.cjs");
 const require_digest = require("./digest-3FeH2Y-Q.cjs");
-const require_portable_dereference = require("./portable-dereference-BCfSQoXP.cjs");
+const require_portable_dereference = require("./portable-dereference-BNXtgg5U.cjs");
 let node_assert_strict = require("node:assert/strict");
 let _fedify_fixture = require("@fedify/fixture");
 //#region src/portable-workers.test.ts

package/dist/tests/portable-workers.test.mjs

@@ -1,7 +1,7 @@
-import { _ as parseIri, i as canonicalizePortableUri, o as formatIri, s as fromCompatibleEf61Id, y as toCompatibleEf61Id } from "./url-ClVBNQup.mjs";
+import { _ as parseIri, i as canonicalizePortableUri, o as formatIri, s as fromCompatibleEf61Id, y as toCompatibleEf61Id } from "./url-DMxmp7ZG.mjs";
 import { i as importDidKey, t as exportDidKey } from "./key-C2Db_TAJ.mjs";
 import { n as createHashlink, o as verifyHashlink, t as computeDigestMultibase } from "./digest-COC7xDiQ.mjs";
-import { n as getPortableGatewayCandidates } from "./portable-dereference-EAbEhAJ4.mjs";
+import { n as getPortableGatewayCandidates } from "./portable-dereference-DRE5bz-l.mjs";
 import { deepStrictEqual, equal } from "node:assert/strict";
 import { test, testDefinitions } from "@fedify/fixture";
 //#region src/portable-workers.test.ts

package/dist/tests/{request-DkiHcgVt.mjs → request-D-SOvXf_.mjs}

@@ -1,7 +1,7 @@
 import process from "node:process";
 //#region deno.json
 var name = "@fedify/vocab-runtime";
-var version = "2.4.0-dev.2256+683c50ba";
+var version = "2.4.0-dev.2260+42356e7d";
 //#endregion
 //#region src/request.ts
 /**

package/dist/tests/{request-BE3wHjK4.cjs → request-kRkxuOkZ.cjs}

@@ -3,7 +3,7 @@ let node_process = require("node:process");
 node_process = require_rolldown_runtime.__toESM(node_process, 1);
 //#region deno.json
 var name = "@fedify/vocab-runtime";
-var version = "2.4.0-dev.2256+683c50ba";
+var version = "2.4.0-dev.2260+42356e7d";
 //#endregion
 //#region src/request.ts
 /**

package/dist/tests/request.test.cjs

@@ -1,5 +1,5 @@
 const require_rolldown_runtime = require("./rolldown-runtime-emK7D4bc.cjs");
-const require_request = require("./request-BE3wHjK4.cjs");
+const require_request = require("./request-kRkxuOkZ.cjs");
 let node_test = require("node:test");
 let node_process = require("node:process");
 node_process = require_rolldown_runtime.__toESM(node_process, 1);

package/dist/tests/request.test.mjs

@@ -1,4 +1,4 @@
-import { n as createActivityPubRequest, o as version, r as getUserAgent } from "./request-DkiHcgVt.mjs";
+import { n as createActivityPubRequest, o as version, r as getUserAgent } from "./request-D-SOvXf_.mjs";
 import { test } from "node:test";
 import process from "node:process";
 import { deepStrictEqual } from "node:assert";

package/dist/tests/{url-Ddeuv0sE.cjs → url-BNakuZ8k.cjs}

@@ -42,7 +42,14 @@ function assertCompatiblePathCanBeParsed(raw, parsed) {
 	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.
+* 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;
@@ -60,6 +67,16 @@ function parseJsonLdId(id, base) {
 * 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);
@@ -84,6 +101,12 @@ function parseIri(iri, base) {
 * 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);
@@ -186,7 +209,20 @@ function haveSameFe34Origin(left, right) {
 	}
 }
 /**
-* Checks whether two IRIs have the same origin.
+* 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);
@@ -274,14 +310,27 @@ function parseAtUri(uri) {
 	return new URL("at://" + encodeURIComponent(authority) + path);
 }
 /**
-* Checks whether the URL is an FEP-ef61 gateway base URI.
+* 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.
+* 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

package/dist/tests/{url-ClVBNQup.mjs → url-DMxmp7ZG.mjs}

@@ -40,7 +40,14 @@ function assertCompatiblePathCanBeParsed(raw, parsed) {
 	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.
+* 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;
@@ -58,6 +65,16 @@ function parseJsonLdId(id, base) {
 * 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);
@@ -82,6 +99,12 @@ function parseIri(iri, base) {
 * 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);
@@ -184,7 +207,20 @@ function haveSameFe34Origin(left, right) {
 	}
 }
 /**
-* Checks whether two IRIs have the same origin.
+* 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);
@@ -272,14 +308,27 @@ function parseAtUri(uri) {
 	return new URL("at://" + encodeURIComponent(authority) + path);
 }
 /**
-* Checks whether the URL is an FEP-ef61 gateway base URI.
+* 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.
+* 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

package/dist/tests/url.test.cjs

@@ -1,4 +1,4 @@
-const require_url = require("./url-Ddeuv0sE.cjs");
+const require_url = require("./url-BNakuZ8k.cjs");
 let node_test = require("node:test");
 let node_assert = require("node:assert");
 //#region src/url.test.ts

package/dist/tests/url.test.mjs

@@ -1,4 +1,4 @@
-import { C as withoutGatewayHints, S as withGatewayHints, _ as parseIri, a as expandIPv6Address, b as validateLookupAddresses, c as getFe34Origin, d as haveSameIriOrigin, f as isGatewayUrl, g as parseGatewayUrl, i as canonicalizePortableUri, l as getGatewayHints, m as isValidPublicIPv6Address, n as UrlError, o as formatIri, p as isValidPublicIPv4Address, r as arePortableUrisEqual, s as fromCompatibleEf61Id, u as haveSameFe34Origin, v as parseJsonLdId, x as validatePublicUrl, y as toCompatibleEf61Id } from "./url-ClVBNQup.mjs";
+import { C as withoutGatewayHints, S as withGatewayHints, _ as parseIri, a as expandIPv6Address, b as validateLookupAddresses, c as getFe34Origin, d as haveSameIriOrigin, f as isGatewayUrl, g as parseGatewayUrl, i as canonicalizePortableUri, l as getGatewayHints, m as isValidPublicIPv6Address, n as UrlError, o as formatIri, p as isValidPublicIPv4Address, r as arePortableUrisEqual, s as fromCompatibleEf61Id, u as haveSameFe34Origin, v as parseJsonLdId, x as validatePublicUrl, y as toCompatibleEf61Id } from "./url-DMxmp7ZG.mjs";
 import { test } from "node:test";
 import { deepStrictEqual, ok, rejects, strictEqual, throws } from "node:assert";
 //#region src/url.test.ts

package/dist/{url-DKA6dTWV.cjs → url-DrGTR8yv.cjs}

@@ -43,7 +43,14 @@ function assertCompatiblePathCanBeParsed(raw, parsed) {
 	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.
+* 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;
@@ -61,6 +68,16 @@ function parseJsonLdId(id, base) {
 * 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);
@@ -85,6 +102,12 @@ function parseIri(iri, base) {
 * 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);
@@ -187,7 +210,20 @@ function haveSameFe34Origin(left, right) {
 	}
 }
 /**
-* Checks whether two IRIs have the same origin.
+* 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);
@@ -275,14 +311,27 @@ function parseAtUri(uri) {
 	return new URL("at://" + encodeURIComponent(authority) + path);
 }
 /**
-* Checks whether the URL is an FEP-ef61 gateway base URI.
+* 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.
+* 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