@fedify/vocab-runtime 2.4.0-dev.1583 → 2.4.0-dev.1618

package/src/url.test.ts

@@ -1,8 +1,12 @@
 import { deepStrictEqual, ok, rejects, throws } from "node:assert";
 import { test } from "node:test";
 import {
+  arePortableUrisEqual,
+  canonicalizePortableUri,
   expandIPv6Address,
   formatIri,
+  getFe34Origin,
+  haveSameFe34Origin,
   haveSameIriOrigin,
   isValidPublicIPv4Address,
   isValidPublicIPv6Address,
@@ -28,15 +32,16 @@ test("parseIri() accepts portable ActivityPub URI schemes", () => {
   }
 });
 
-test("parseIri() accepts DID schemes case-insensitively", () => {
+test("parseIri() normalizes DID scheme and method casing", () => {
   const cases = [
     "ap://DID:key:z6Mkabc/actor",
     "ap://DID%3Akey%3Az6Mkabc/actor",
+    "ap://did:KEY:z6Mkabc/actor",
   ];
   for (const iri of cases) {
     deepStrictEqual(
       parseIri(iri),
-      new URL("ap+ef61://DID%3Akey%3Az6Mkabc/actor"),
+      new URL("ap+ef61://did%3Akey%3Az6Mkabc/actor"),
     );
   }
 });
@@ -137,6 +142,14 @@ test("parseIri() rejects malformed portable DID authorities", () => {
 });
 
 test("haveSameIriOrigin() compares portable IRI authorities", () => {
+  ok(haveSameIriOrigin(
+    new URL("ftp://example.com/pub/1"),
+    new URL("ftp://example.com/pub/2"),
+  ));
+  ok(haveSameIriOrigin(
+    new URL("mailto:alice@example.com"),
+    new URL("mailto:alice@example.com"),
+  ));
   ok(haveSameIriOrigin(
     parseIri("ap://did:key:z6Mkabc/actor"),
     parseIri("ap://did:key:z6Mkabc/outbox"),
@@ -161,6 +174,122 @@ test("haveSameIriOrigin() compares portable IRI authorities", () => {
   );
 });
 
+test("getFe34Origin() computes web and cryptographic origins", () => {
+  deepStrictEqual(
+    getFe34Origin("https://Example.COM:443/users/alice"),
+    "https://example.com",
+  );
+  deepStrictEqual(
+    getFe34Origin(new URL("http://example.com:8080/notes/1")),
+    "http://example.com:8080",
+  );
+  deepStrictEqual(
+    getFe34Origin(
+      "ap://did:key:z6Mkabc/actor?gateways=https%3A%2F%2Fa.example",
+    ),
+    "did:key:z6Mkabc",
+  );
+  deepStrictEqual(
+    getFe34Origin("ap+ef61://did%3Akey%3Az6Mkabc/objects/1#fragment"),
+    "did:key:z6Mkabc",
+  );
+  deepStrictEqual(
+    getFe34Origin(new URL("ap+ef61://did%3Akey%3Az6Mkabc/actor")),
+    "did:key:z6Mkabc",
+  );
+  deepStrictEqual(
+    getFe34Origin("did:key:z6Mkabc#z6Mkabc"),
+    "did:key:z6Mkabc",
+  );
+  deepStrictEqual(
+    getFe34Origin(new URL("did:key:z6Mkabc?service=activitypub#key")),
+    "did:key:z6Mkabc",
+  );
+  deepStrictEqual(
+    getFe34Origin("did:key:z6Mkabc/path/to/resource?service=activitypub#key"),
+    "did:key:z6Mkabc",
+  );
+  deepStrictEqual(
+    getFe34Origin("did:KEY:z6Mkabc#z6Mkabc"),
+    "did:key:z6Mkabc",
+  );
+  deepStrictEqual(
+    getFe34Origin("ap://did%3Aweb%3Afoo%2Dbar.example/actor"),
+    "did:web:foo-bar.example",
+  );
+  deepStrictEqual(
+    getFe34Origin("did:web:foo%2dbar.example#key"),
+    "did:web:foo-bar.example",
+  );
+});
+
+test("getFe34Origin() rejects unsupported or malformed identifiers", () => {
+  for (
+    const iri of [
+      "mailto:alice@example.com",
+      "ap://not-a-did/actor",
+      "ap://did:key/actor",
+      "did:key",
+      "did:key:",
+      "did:",
+    ]
+  ) {
+    throws(() => getFe34Origin(iri), TypeError);
+  }
+});
+
+test("haveSameFe34Origin() compares web and cryptographic origins", () => {
+  ok(haveSameFe34Origin(
+    "https://example.com/users/alice",
+    "https://example.com/notes/1",
+  ));
+  ok(
+    !haveSameFe34Origin(
+      "https://example.com/users/alice",
+      "http://example.com/users/alice",
+    ),
+  );
+  ok(
+    !haveSameFe34Origin(
+      "https://example.com/users/alice",
+      "https://example.com:8443/users/alice",
+    ),
+  );
+  ok(haveSameFe34Origin(
+    "ap://did:key:z6Mkabc/actor",
+    "ap+ef61://did%3Akey%3Az6Mkabc/objects/1",
+  ));
+  ok(haveSameFe34Origin(
+    "ap+ef61://did:key:z6Mkabc/actor",
+    "did:key:z6Mkabc#z6Mkabc",
+  ));
+  ok(haveSameFe34Origin(
+    "ap://did:KEY:z6Mkabc/actor",
+    "did:key:z6Mkabc#z6Mkabc",
+  ));
+  ok(haveSameFe34Origin(
+    "ap://did%3Aweb%3Afoo%2Dbar.example/actor",
+    "ap://did:web:foo-bar.example/note",
+  ));
+  ok(haveSameFe34Origin(
+    "ap://did%3Aexample%3Aabc%252fdef/actor",
+    "did:example:abc%2Fdef#key",
+  ));
+  ok(
+    !haveSameFe34Origin(
+      "ap+ef61://did:key:z6Mkabc/actor",
+      "did:key:z6Mkdef#z6Mkdef",
+    ),
+  );
+  ok(
+    !haveSameFe34Origin(
+      "ap+ef61://did:key:z6Mkabc/actor",
+      "https://example.com/actor",
+    ),
+  );
+  ok(!haveSameFe34Origin("ap://not-a-did/actor", "ap://not-a-did/actor"));
+});
+
 test("parseIri() normalizes portable URL instances", () => {
   deepStrictEqual(
     parseIri(new URL("ap+ef61://did%3Aexample%3Aabc%2Fdef/actor")),
@@ -184,6 +313,256 @@ test("formatIri() emits canonical portable ActivityPub URI syntax", () => {
   deepStrictEqual(formatIri("/actor"), "/actor");
 });
 
+test("canonicalizePortableUri() emits comparison forms", () => {
+  const cases = [
+    "ap://did:key:z6Mkabc/actor",
+    "ap://did%3Akey%3Az6Mkabc/actor",
+    "ap://did:key:z6Mkabc/actor?gateways=https%3A%2F%2Fa.example",
+    "ap+ef61://did:key:z6Mkabc/actor",
+    "ap+ef61://did%3Akey%3Az6Mkabc/actor?gateways=https%3A%2F%2Fa.example",
+  ];
+  for (const iri of cases) {
+    deepStrictEqual(
+      canonicalizePortableUri(iri),
+      "ap+ef61://did:key:z6Mkabc/actor",
+    );
+  }
+});
+
+test("canonicalizePortableUri() preserves paths and fragments", () => {
+  deepStrictEqual(
+    canonicalizePortableUri(
+      "ap://did:key:z6Mkabc/objects/1/attachments/2?gateways=https%3A%2F%2Fa.example#image",
+    ),
+    "ap+ef61://did:key:z6Mkabc/objects/1/attachments/2#image",
+  );
+  deepStrictEqual(
+    canonicalizePortableUri("ap://did:key:z6Mkabc/objects/1#reply"),
+    "ap+ef61://did:key:z6Mkabc/objects/1#reply",
+  );
+});
+
+test("canonicalizePortableUri() preserves DID-internal pct-encoded characters", () => {
+  deepStrictEqual(
+    canonicalizePortableUri("ap://did:example:abc%2Fdef/actor?x=1"),
+    "ap+ef61://did:example:abc%2Fdef/actor",
+  );
+  deepStrictEqual(
+    canonicalizePortableUri("ap://did%3Aweb%3Aexample.com%253A3000/u/1"),
+    "ap+ef61://did:web:example.com%3A3000/u/1",
+  );
+});
+
+test("canonicalizePortableUri() normalizes authority pct-encoding casing", () => {
+  deepStrictEqual(
+    canonicalizePortableUri("ap://did:example:abc%2fdef/actor"),
+    "ap+ef61://did:example:abc%2Fdef/actor",
+  );
+  deepStrictEqual(
+    canonicalizePortableUri("ap://did:example:abc%2fdef%3abar/actor"),
+    "ap+ef61://did:example:abc%2Fdef%3Abar/actor",
+  );
+  deepStrictEqual(
+    canonicalizePortableUri("ap://did%3Aexample%3Aabc%252fdef/actor"),
+    "ap+ef61://did:example:abc%2Fdef/actor",
+  );
+  deepStrictEqual(
+    canonicalizePortableUri("ap://did%3Akey%3Az6Mk%2Dabc/actor"),
+    "ap+ef61://did:key:z6Mk-abc/actor",
+  );
+  ok(arePortableUrisEqual(
+    "ap://did:example:abc%2fdef/actor",
+    "ap://did:example:abc%2Fdef/actor",
+  ));
+  ok(arePortableUrisEqual(
+    "ap://did%3Akey%3Az6Mk%2Dabc/actor",
+    "ap://did:key:z6Mk-abc/actor",
+  ));
+});
+
+test("canonicalizePortableUri() normalizes path and fragment pct-encoding casing", () => {
+  deepStrictEqual(
+    canonicalizePortableUri("ap://did:key:z6Mkabc/actor%2fprofile#part%2ftwo"),
+    "ap+ef61://did:key:z6Mkabc/actor%2Fprofile#part%2Ftwo",
+  );
+  deepStrictEqual(
+    canonicalizePortableUri("ap://did:key:z6Mkabc/actor%2fprofile%3aimage"),
+    "ap+ef61://did:key:z6Mkabc/actor%2Fprofile%3Aimage",
+  );
+  deepStrictEqual(
+    canonicalizePortableUri("ap://did:key:z6Mkabc/actor%2Dprofile#part%7Etwo"),
+    "ap+ef61://did:key:z6Mkabc/actor-profile#part~two",
+  );
+  ok(arePortableUrisEqual(
+    "ap://did:key:z6Mkabc/actor%2fprofile#part%2ftwo",
+    "ap://did:key:z6Mkabc/actor%2Fprofile#part%2Ftwo",
+  ));
+  ok(arePortableUrisEqual(
+    "ap://did:key:z6Mkabc/actor%2Dprofile#part%7Etwo",
+    "ap://did:key:z6Mkabc/actor-profile#part~two",
+  ));
+});
+
+test("canonicalizePortableUri() encodes raw path and fragment characters", () => {
+  deepStrictEqual(
+    canonicalizePortableUri("ap://did:key:z6Mkabc/\u00e9#\u00e9"),
+    "ap+ef61://did:key:z6Mkabc/%C3%A9#%C3%A9",
+  );
+  ok(arePortableUrisEqual(
+    "ap://did:key:z6Mkabc/\u00e9#\u00e9",
+    "ap://did:key:z6Mkabc/%C3%A9#%C3%A9",
+  ));
+});
+
+test("canonicalizePortableUri() normalizes DID scheme casing", () => {
+  deepStrictEqual(
+    canonicalizePortableUri("ap://DID:key:z6Mkabc/actor"),
+    "ap+ef61://did:key:z6Mkabc/actor",
+  );
+  deepStrictEqual(
+    canonicalizePortableUri("ap://DID%3Akey%3Az6Mkabc/actor"),
+    "ap+ef61://did:key:z6Mkabc/actor",
+  );
+});
+
+test("canonicalizePortableUri() preserves opaque path segments", () => {
+  deepStrictEqual(
+    canonicalizePortableUri("ap://did:key:z6Mkabc/a/../b?gateways=x"),
+    "ap+ef61://did:key:z6Mkabc/a/../b",
+  );
+  deepStrictEqual(
+    canonicalizePortableUri("ap://did:key:z6Mkabc/a/%2e%2e/b"),
+    "ap+ef61://did:key:z6Mkabc/a/../b",
+  );
+  ok(
+    !arePortableUrisEqual(
+      "ap://did:key:z6Mkabc/a/../b",
+      "ap://did:key:z6Mkabc/b",
+    ),
+  );
+  ok(
+    !arePortableUrisEqual(
+      "ap://did:key:z6Mkabc/a/%2e%2e/b",
+      "ap://did:key:z6Mkabc/b",
+    ),
+  );
+});
+
+test("canonicalizePortableUri() rejects non-portable URIs", () => {
+  const cases = [
+    "https://example.com/actor",
+    "at://did:plc:example/record",
+    "/actor",
+    "ap://not-a-did/actor",
+    "ap://did:key:z6Mkabc",
+  ];
+  for (const iri of cases) {
+    throws(() => canonicalizePortableUri(iri), TypeError);
+  }
+  throws(
+    () =>
+      canonicalizePortableUri(
+        new URL("ap+ef61://did%3Akey%3Az6Mkabc/actor") as unknown as string,
+      ),
+    TypeError,
+  );
+});
+
+test("canonicalizePortableUri() rejects invalid path and fragment pct-encoding", () => {
+  throws(() => canonicalizePortableUri("ap://did:key:z6Mkabc/a%zz"), TypeError);
+  throws(
+    () => canonicalizePortableUri("ap://did:key:z6Mkabc/actor#part%zz"),
+    TypeError,
+  );
+  throws(
+    () => canonicalizePortableUri("ap://did:key:z6Mkabc/\ud800"),
+    TypeError,
+  );
+  throws(
+    () => canonicalizePortableUri("ap://did:key:z6Mkabc/actor#\ud800"),
+    TypeError,
+  );
+});
+
+test("arePortableUrisEqual() compares canonical portable URI forms", () => {
+  ok(arePortableUrisEqual(
+    "ap://did:key:z6Mkabc/actor",
+    "ap+ef61://did%3Akey%3Az6Mkabc/actor?gateways=https%3A%2F%2Fa.example",
+  ));
+  ok(arePortableUrisEqual(
+    "ap://DID:key:z6Mkabc/actor",
+    "ap://did:key:z6Mkabc/actor",
+  ));
+  ok(
+    !arePortableUrisEqual(
+      "ap://did:key:z6Mkabc/actor",
+      "ap://did:key:z6Mkdef/actor",
+    ),
+  );
+  ok(
+    !arePortableUrisEqual(
+      "ap://did:key:z6Mkabc/actor",
+      "ap://did:key:z6Mkabc/outbox",
+    ),
+  );
+  ok(
+    !arePortableUrisEqual(
+      "ap://did:key:z6Mkabc/actor#one",
+      "ap://did:key:z6Mkabc/actor#two",
+    ),
+  );
+});
+
+test("arePortableUrisEqual() handles non-portable URI strings", () => {
+  ok(arePortableUrisEqual(
+    "https://example.com/actor",
+    "https://example.com/actor",
+  ));
+  ok(
+    !arePortableUrisEqual(
+      "https://example.com/actor",
+      "https://example.com/outbox",
+    ),
+  );
+  ok(
+    !arePortableUrisEqual(
+      "ap://did:key:z6Mkabc/actor",
+      "https://example.com/actor",
+    ),
+  );
+  ok(arePortableUrisEqual("ap://not-a-did/actor", "ap://not-a-did/actor"));
+  ok(
+    !arePortableUrisEqual(
+      "ap://not-a-did/actor",
+      "ap://not-a-did/outbox",
+    ),
+  );
+  ok(
+    !arePortableUrisEqual(
+      "ap://not-a-did/actor",
+      "ap://did:key:z6Mkabc/actor",
+    ),
+  );
+  ok(
+    !arePortableUrisEqual(
+      "ap://did:key:z6Mkabc/a%zz",
+      "ap://did:key:z6Mkabc/a%25zz",
+    ),
+  );
+  ok(
+    !arePortableUrisEqual(
+      "ap://did:key:z6Mkabc/\ud800",
+      "ap://did:key:z6Mkabc/%EF%BF%BD",
+    ),
+  );
+  ok(
+    !arePortableUrisEqual(
+      "ap://did:key:z6Mkabc/actor#\ud800",
+      "ap://did:key:z6Mkabc/actor#%EF%BF%BD",
+    ),
+  );
+});
+
 test("formatIri() preserves DID authority pct-encoded delimiters", () => {
   const parsed = parseIri("ap://did:example:abc%2Fdef/actor");
   deepStrictEqual(

package/src/url.ts

@@ -12,6 +12,7 @@ export class UrlError extends Error {
 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;
 
@@ -63,6 +64,123 @@ export function formatIri(iri: string | URL): string {
   return `ap+ef61://${authority}${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.
+ *
+ * @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
+ */
+export function canonicalizePortableUri(input: string): string {
+  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)!;
+  // parsePortableIri() validates the value but returns a URL, which normalizes
+  // opaque path segments.  Use the raw match for path and fragment comparison.
+  // parsed.host is the encodeURIComponent() output from parsePortableIri(), so
+  // decodePortableAuthority() reverses the shared percent-encoded authority
+  // path here rather than the raw did:-prefixed branch.
+  const authority = normalizePortableAuthority(
+    getDidUrlOrigin(decodePortableAuthority(parsed.host)),
+  );
+  // Keep path and fragment text from the raw match to avoid URL dot-segment
+  // normalization, but still encode raw characters and normalize
+  // percent-escape hex casing per URI comparison rules.
+  const path = normalizePortableComponent(match[3]);
+  const fragment = match[5] == null ? "" : normalizePortableComponent(match[5]);
+  return `ap+ef61://${authority}${path}${fragment}`;
+}
+
+/**
+ * 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
+ */
+export function arePortableUrisEqual(
+  left: string,
+  right: string,
+): boolean {
+  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
+ */
+export function getFe34Origin(input: string | URL): string {
+  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
+ */
+export function haveSameFe34Origin(
+  left: string | URL,
+  right: string | URL,
+): boolean {
+  try {
+    return getFe34Origin(left) === getFe34Origin(right);
+  } catch (error) {
+    if (error instanceof TypeError) return false;
+    throw error;
+  }
+}
+
 /**
  * Checks whether two IRIs have the same origin.
  */
@@ -76,7 +194,7 @@ function getComparableIriOrigin(iri: URL): string {
   if (iri.host !== "") {
     const host = iri.protocol === "ap+ef61:"
       ? encodeURIComponent(
-        decodePortableAuthority(iri.host).replace(DID_SCHEME_PATTERN, "did:"),
+        getDidUrlOrigin(decodePortableAuthority(iri.host)),
       )
       : iri.host;
     return `${iri.protocol}//${host}`;
@@ -84,6 +202,18 @@ function getComparableIriOrigin(iri: URL): string {
   return iri.href;
 }
 
+function getPortableCryptographicOrigin(iri: URL): string {
+  return getDidUrlOrigin(decodePortableAuthority(iri.host));
+}
+
+function getDidUrlOrigin(iri: string): string {
+  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: string): URL | null {
   const match = iri.match(PORTABLE_IRI_PATTERN);
   if (match == null) return null;
@@ -92,7 +222,7 @@ function parsePortableIri(iri: string): URL | null {
   // current FEP-ef61 interoperability, but normalize it to a percent-encoded
   // URL authority internally.  The ap: URI syntax may change later; see:
   // https://bnewbold.leaflet.pub/3mph4hzvbdc2v
-  const authority = decodePortableAuthority(match[2]);
+  const authority = getDidUrlOrigin(decodePortableAuthority(match[2]));
   if (!DID_PATTERN.test(authority)) {
     throw new TypeError("Invalid portable ActivityPub IRI authority.");
   }
@@ -143,6 +273,49 @@ function decodePortableAuthority(authority: string): string {
   return decoded;
 }
 
+function normalizePercentEncoding(value: string): string {
+  return value.replace(
+    PERCENT_ENCODING_PATTERN,
+    (match) => match.toUpperCase(),
+  );
+}
+
+function normalizePortableAuthority(authority: string): string {
+  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: string): string {
+  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: string): URL {
   const index = uri.indexOf("/", 5);
   const authority = index >= 0 ? uri.slice(5, index) : uri.slice(5);