@fedify/vocab-runtime 2.4.0-dev.1581 → 2.4.0-dev.1599

package/dist/tests/url.test.mjs

@@ -1,4 +1,4 @@
-import { a as isValidPublicIPv4Address, c as parseJsonLdId, i as haveSameIriOrigin, l as validatePublicUrl, n as expandIPv6Address, o as isValidPublicIPv6Address, r as formatIri, s as parseIri, t as UrlError } from "./url-YWJbnRlf.mjs";
+import { a as formatIri, c as isValidPublicIPv6Address, d as validatePublicUrl, i as expandIPv6Address, l as parseIri, n as arePortableUrisEqual, o as haveSameIriOrigin, r as canonicalizePortableUri, s as isValidPublicIPv4Address, t as UrlError, u as parseJsonLdId } from "./url-D7ay_5pk.mjs";
 import { deepStrictEqual, ok, rejects, throws } from "node:assert";
 import { test } from "node:test";
 //#region src/url.test.ts
@@ -75,6 +75,86 @@ test("formatIri() emits canonical portable ActivityPub URI syntax", () => {
 	deepStrictEqual(formatIri(new URL("https://example.com/actor")), "https://example.com/actor");
 	deepStrictEqual(formatIri("/actor"), "/actor");
 });
+test("canonicalizePortableUri() emits comparison forms", () => {
+	for (const iri of [
+		"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"
+	]) 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/é#é"), "ap+ef61://did:key:z6Mkabc/%C3%A9#%C3%A9");
+	ok(arePortableUrisEqual("ap://did:key:z6Mkabc/é#é", "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", () => {
+	for (const iri of [
+		"https://example.com/actor",
+		"at://did:plc:example/record",
+		"/actor",
+		"ap://not-a-did/actor",
+		"ap://did:key:z6Mkabc"
+	]) throws(() => canonicalizePortableUri(iri), TypeError);
+	throws(() => canonicalizePortableUri(new URL("ap+ef61://did%3Akey%3Az6Mkabc/actor")), 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(parsed, new URL("ap+ef61://did%3Aexample%3Aabc%252Fdef/actor"));

package/dist/{url-BAdyyqAa.cjs → url-BMDN9GnE.cjs}

@@ -11,6 +11,7 @@ var UrlError = class 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;
 /**
@@ -45,6 +46,49 @@ function formatIri(iri) {
 	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.
+*
+* @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(decodePortableAuthority(parsed.host).replace(DID_SCHEME_PATTERN, "did:"))}${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;
+	}
+}
+/**
 * Checks whether two IRIs have the same origin.
 */
 function haveSameIriOrigin(left, right) {
@@ -87,6 +131,31 @@ function decodePortableAuthority(authority) {
 	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);
@@ -265,6 +334,18 @@ Object.defineProperty(exports, "UrlError", {
 		return UrlError;
 	}
 });
+Object.defineProperty(exports, "arePortableUrisEqual", {
+	enumerable: true,
+	get: function() {
+		return arePortableUrisEqual;
+	}
+});
+Object.defineProperty(exports, "canonicalizePortableUri", {
+	enumerable: true,
+	get: function() {
+		return canonicalizePortableUri;
+	}
+});
 Object.defineProperty(exports, "expandIPv6Address", {
 	enumerable: true,
 	get: function() {

package/dist/{url-BuxPHxK2.js → url-BlFta-Eh.js}

@@ -10,6 +10,7 @@ var UrlError = class 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;
 /**
@@ -44,6 +45,49 @@ function formatIri(iri) {
 	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.
+*
+* @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(decodePortableAuthority(parsed.host).replace(DID_SCHEME_PATTERN, "did:"))}${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;
+	}
+}
+/**
 * Checks whether two IRIs have the same origin.
 */
 function haveSameIriOrigin(left, right) {
@@ -86,6 +130,31 @@ function decodePortableAuthority(authority) {
 	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);
@@ -258,4 +327,4 @@ function matchesIPv6Prefix(address, prefixWords, prefixLength) {
 	return true;
 }
 //#endregion
-export { isValidPublicIPv4Address as a, parseJsonLdId as c, haveSameIriOrigin as i, validatePublicUrl as l, expandIPv6Address as n, isValidPublicIPv6Address as o, formatIri as r, parseIri as s, UrlError as t };
+export { formatIri as a, isValidPublicIPv6Address as c, validatePublicUrl as d, expandIPv6Address as i, parseIri as l, arePortableUrisEqual as n, haveSameIriOrigin as o, canonicalizePortableUri as r, isValidPublicIPv4Address as s, UrlError as t, parseJsonLdId as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/vocab-runtime",
-  "version": "2.4.0-dev.1581+2c99806d",
+  "version": "2.4.0-dev.1599+7b19967f",
   "homepage": "https://fedify.dev/",
   "repository": {
     "type": "git",

package/src/mod.ts

@@ -54,6 +54,8 @@ export {
   type PropertyPreprocessorContext,
 } from "./preprocessor.ts";
 export {
+  arePortableUrisEqual,
+  canonicalizePortableUri,
   expandIPv6Address,
   formatIri,
   haveSameIriOrigin,

package/src/url.test.ts

@@ -1,6 +1,8 @@
 import { deepStrictEqual, ok, rejects, throws } from "node:assert";
 import { test } from "node:test";
 import {
+  arePortableUrisEqual,
+  canonicalizePortableUri,
   expandIPv6Address,
   formatIri,
   haveSameIriOrigin,
@@ -184,6 +186,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(