@fedify/vocab-runtime 2.4.0-dev.1504 → 2.4.0-dev.1528

package/src/url.test.ts

@@ -1,13 +1,264 @@
-import { deepStrictEqual, ok, rejects } from "node:assert";
+import { deepStrictEqual, ok, rejects, throws } from "node:assert";
 import { test } from "node:test";
 import {
   expandIPv6Address,
+  formatIri,
+  haveSameIriOrigin,
   isValidPublicIPv4Address,
   isValidPublicIPv6Address,
+  parseIri,
+  parseJsonLdId,
   UrlError,
   validatePublicUrl,
 } from "./url.ts";
 
+test("parseIri() accepts portable ActivityPub URI schemes", () => {
+  const cases = [
+    "ap://did:key:z6Mkabc/actor",
+    "ap://did%3Akey%3Az6Mkabc/actor",
+    "ap+ef61://did:key:z6Mkabc/actor",
+    "ap+ef61://did%3Akey%3Az6Mkabc/actor",
+    "AP+EF61://did:key:z6Mkabc/actor",
+  ];
+  for (const iri of cases) {
+    deepStrictEqual(
+      parseIri(iri),
+      new URL("ap+ef61://did%3Akey%3Az6Mkabc/actor"),
+    );
+  }
+});
+
+test("parseIri() accepts DID schemes case-insensitively", () => {
+  const cases = [
+    "ap://DID:key:z6Mkabc/actor",
+    "ap://DID%3Akey%3Az6Mkabc/actor",
+  ];
+  for (const iri of cases) {
+    deepStrictEqual(
+      parseIri(iri),
+      new URL("ap+ef61://DID%3Akey%3Az6Mkabc/actor"),
+    );
+  }
+});
+
+test("parseIri() accepts DID method names that start with digits", () => {
+  deepStrictEqual(
+    parseIri("ap://did:3:abc/actor"),
+    new URL("ap+ef61://did%3A3%3Aabc/actor"),
+  );
+});
+
+test("parseIri() accepts hyphens in DID method-specific IDs", () => {
+  deepStrictEqual(
+    parseIri("ap+ef61://did:web:foo-bar.example/actor"),
+    new URL("ap+ef61://did%3Aweb%3Afoo-bar.example/actor"),
+  );
+});
+
+test("parseIri() preserves existing URL parsing behavior", () => {
+  deepStrictEqual(
+    parseIri("/actor", new URL("https://example.com/users/alice")),
+    new URL("https://example.com/actor"),
+  );
+  deepStrictEqual(
+    parseIri("at://did:plc:example/record"),
+    new URL("at://did%3Aplc%3Aexample/record"),
+  );
+  throws(() => parseIri("ap://not-a-did/actor"), TypeError);
+});
+
+test("parseJsonLdId() parses JSON-LD ids", () => {
+  deepStrictEqual(parseJsonLdId(undefined), undefined);
+  deepStrictEqual(parseJsonLdId("_:blank"), undefined);
+  deepStrictEqual(
+    parseJsonLdId("/actor", new URL("https://example.com/users/alice")),
+    new URL("https://example.com/actor"),
+  );
+  deepStrictEqual(
+    parseJsonLdId("ap://did:key:z6Mkabc/actor"),
+    new URL("ap+ef61://did%3Akey%3Az6Mkabc/actor"),
+  );
+  throws(() => parseJsonLdId("/actor"), {
+    name: "TypeError",
+    message: "Invalid @id: /actor",
+  });
+});
+
+test("parseIri() resolves relative IRIs against portable string bases", () => {
+  deepStrictEqual(
+    parseIri("/actor", "ap://did:key:z6Mkabc/objects/1"),
+    new URL("ap+ef61://did%3Akey%3Az6Mkabc/actor"),
+  );
+  deepStrictEqual(
+    parseIri("attachments/1", "ap://did:key:z6Mkabc/objects/1"),
+    new URL("ap+ef61://did%3Akey%3Az6Mkabc/objects/attachments/1"),
+  );
+  throws(
+    () => parseIri("//example.com/outbox", "ap://did:key:z6Mkabc/objects/1"),
+    TypeError,
+  );
+});
+
+test("parseIri() resolves relative IRIs against at:// string bases", () => {
+  deepStrictEqual(
+    parseIri("/record", "at://did:plc:example/collection/item"),
+    new URL("at://did%3Aplc%3Aexample/record"),
+  );
+  deepStrictEqual(
+    parseIri("reply", "at://did:plc:example/collection/item"),
+    new URL("at://did%3Aplc%3Aexample/collection/reply"),
+  );
+  deepStrictEqual(
+    parseIri("reply", "at://did%3Aplc%3Aexample/collection/item"),
+    new URL("at://did%3Aplc%3Aexample/collection/reply"),
+  );
+});
+
+test("parseIri() rejects portable IRIs without paths", () => {
+  throws(() => parseIri("ap://did:key:z6Mkabc"), TypeError);
+  throws(
+    () =>
+      parseIri("ap://did:key:z6Mkabc?gateways=https%3A%2F%2Fserver.example"),
+    TypeError,
+  );
+  throws(() => parseIri("ap://did:key:z6Mkabc#actor"), TypeError);
+});
+
+test("parseIri() rejects malformed portable DID authorities", () => {
+  const cases = [
+    "ap://did:/actor",
+    "ap://did:key/actor",
+    "ap://did%3Akey%3Aabc%25zz/actor",
+    "ap://did:key:abc%25zz/actor",
+  ];
+  for (const iri of cases) {
+    throws(() => parseIri(iri), TypeError);
+  }
+});
+
+test("haveSameIriOrigin() compares portable IRI authorities", () => {
+  ok(haveSameIriOrigin(
+    parseIri("ap://did:key:z6Mkabc/actor"),
+    parseIri("ap://did:key:z6Mkabc/outbox"),
+  ));
+  ok(haveSameIriOrigin(
+    new URL("ap://did%3Akey%3Az6Mkabc/actor"),
+    new URL("ap+ef61://did%3Akey%3Az6Mkabc/outbox"),
+  ));
+  ok(haveSameIriOrigin(
+    parseIri("ap://DID:key:z6Mkabc/actor"),
+    parseIri("ap://did:key:z6Mkabc/outbox"),
+  ));
+  ok(haveSameIriOrigin(
+    new URL("ap+ef61://DID%3Akey%3Az6Mkabc/actor"),
+    new URL("ap+ef61://did%3Akey%3Az6Mkabc/outbox"),
+  ));
+  ok(
+    !haveSameIriOrigin(
+      parseIri("ap://did:key:z6Mkabc/actor"),
+      parseIri("ap://did:key:z6Mkdef/actor"),
+    ),
+  );
+});
+
+test("parseIri() normalizes portable URL instances", () => {
+  deepStrictEqual(
+    parseIri(new URL("ap+ef61://did%3Aexample%3Aabc%2Fdef/actor")),
+    new URL("ap+ef61://did%3Aexample%3Aabc%252Fdef/actor"),
+  );
+  throws(() => parseIri("ap+ef61://not-a-did/actor"), TypeError);
+});
+
+test("formatIri() emits canonical portable ActivityPub URI syntax", () => {
+  const cases = [
+    new URL("ap://did%3Akey%3Az6Mkabc/actor"),
+    new URL("ap+ef61://did%3Akey%3Az6Mkabc/actor"),
+  ];
+  for (const iri of cases) {
+    deepStrictEqual(formatIri(iri), "ap+ef61://did:key:z6Mkabc/actor");
+  }
+  deepStrictEqual(
+    formatIri(new URL("https://example.com/actor")),
+    "https://example.com/actor",
+  );
+  deepStrictEqual(formatIri("/actor"), "/actor");
+});
+
+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"),
+  );
+  deepStrictEqual(
+    formatIri(parsed),
+    "ap+ef61://did:example:abc%2Fdef/actor",
+  );
+  deepStrictEqual(
+    parseIri(formatIri(parsed)),
+    parsed,
+  );
+  deepStrictEqual(
+    formatIri(new URL("ap+ef61://did%3Aexample%3Aabc%2Fdef/actor")),
+    "ap+ef61://did:example:abc%2Fdef/actor",
+  );
+});
+
+test("parseIri() normalizes equivalent encoded DID authorities", () => {
+  deepStrictEqual(
+    parseIri("ap://did:example:abc%252Fdef/actor"),
+    parseIri("ap://did%3Aexample%3Aabc%252Fdef/actor"),
+  );
+});
+
+test("formatIri() preserves DID-internal pct-encoded authority characters", () => {
+  const parsed = parseIri("ap://did:web:example.com%3A3000/actor");
+  deepStrictEqual(
+    parsed,
+    new URL("ap+ef61://did%3Aweb%3Aexample.com%253A3000/actor"),
+  );
+  deepStrictEqual(
+    formatIri(parsed),
+    "ap+ef61://did:web:example.com%3A3000/actor",
+  );
+});
+
+test("parseIri() accepts portable DID URLs with encoded DID delimiters", () => {
+  const parsed = parseIri("ap://did:web:example.com%3A3000/u/1");
+  deepStrictEqual(
+    parsed,
+    new URL("ap+ef61://did%3Aweb%3Aexample.com%253A3000/u/1"),
+  );
+  deepStrictEqual(
+    formatIri(parsed),
+    "ap+ef61://did:web:example.com%3A3000/u/1",
+  );
+});
+
+test("parseIri() decodes pct-encoded DID delimiters in order", () => {
+  const parsed = parseIri("ap://did%3Aweb%3Aexample.com%253A3000/u/1");
+  deepStrictEqual(
+    parsed,
+    new URL("ap+ef61://did%3Aweb%3Aexample.com%253A3000/u/1"),
+  );
+  deepStrictEqual(
+    formatIri(parsed),
+    "ap+ef61://did:web:example.com%3A3000/u/1",
+  );
+});
+
+test("parseIri() preserves encoded percent signs while decoding delimiters", () => {
+  const parsed = parseIri("ap://did%3Aweb%3Aexample.com%2500/u/1");
+  deepStrictEqual(
+    parsed,
+    new URL("ap+ef61://did%3Aweb%3Aexample.com%2500/u/1"),
+  );
+  deepStrictEqual(
+    formatIri(parsed),
+    "ap+ef61://did:web:example.com%00/u/1",
+  );
+});
+
 test("validatePublicUrl()", async () => {
   await rejects(() => validatePublicUrl("ftp://localhost"), UrlError);
   await rejects(

package/src/url.ts

@@ -9,6 +9,147 @@ export class UrlError extends Error {
   }
 }
 
+const PORTABLE_IRI_PATTERN =
+  /^(ap|ap\+ef61):\/\/([^/?#]*)([^?#]*)(\?[^#]*)?(#.*)?$/i;
+const INVALID_PERCENT_ENCODING_PATTERN = /%(?![0-9A-Fa-f]{2})/;
+const DID_SCHEME_PATTERN = /^did:/i;
+const DID_PATTERN = /^did:[a-z0-9]+:[-A-Za-z0-9._%]+(?::[-A-Za-z0-9._%]+)*$/i;
+
+/**
+ * Parses a JSON-LD `@id` value as an IRI.
+ */
+export function parseJsonLdId(
+  id: string | undefined,
+  base?: string | URL,
+): URL | undefined {
+  if (id == null || id.startsWith("_:")) return undefined;
+  try {
+    return parseIri(id, base);
+  } catch {
+    throw new TypeError("Invalid @id: " + id);
+  }
+}
+
+/**
+ * Parses an IRI as a URL, including FEP-ef61 portable ActivityPub IRIs.
+ */
+export function parseIri(iri: string | URL, base?: string | URL): URL {
+  if (iri instanceof URL) {
+    return normalizePortableUrl(iri) ?? new URL(iri.href);
+  }
+  const portable = parsePortableIri(iri);
+  if (portable != null) return portable;
+  base = normalizeBaseIri(base);
+  if (!URL.canParse(iri, base) && iri.startsWith("at://")) {
+    return parseAtUri(iri);
+  }
+  const parsed = new URL(iri, base);
+  return normalizePortableUrl(parsed) ?? parsed;
+}
+
+/**
+ * Formats a URL as an IRI, including FEP-ef61 portable ActivityPub IRIs.
+ */
+export function formatIri(iri: string | URL): string {
+  const parsed = parsePortableIri(iri instanceof URL ? iri.href : iri);
+  if (parsed == null) {
+    return iri instanceof URL
+      ? iri.href
+      : URL.canParse(iri)
+      ? new URL(iri).href
+      : iri;
+  }
+  const authority = decodePortableAuthority(parsed.host);
+  return `ap+ef61://${authority}${parsed.pathname}${parsed.search}${parsed.hash}`;
+}
+
+/**
+ * Checks whether two IRIs have the same origin.
+ */
+export function haveSameIriOrigin(left: URL, right: URL): boolean {
+  return getComparableIriOrigin(left) === getComparableIriOrigin(right);
+}
+
+function getComparableIriOrigin(iri: URL): string {
+  iri = normalizePortableUrl(iri) ?? iri;
+  if (iri.origin !== "null") return iri.origin;
+  if (iri.host !== "") {
+    const host = iri.protocol === "ap+ef61:"
+      ? encodeURIComponent(
+        decodePortableAuthority(iri.host).replace(DID_SCHEME_PATTERN, "did:"),
+      )
+      : iri.host;
+    return `${iri.protocol}//${host}`;
+  }
+  return iri.href;
+}
+
+function parsePortableIri(iri: string): URL | null {
+  const match = iri.match(PORTABLE_IRI_PATTERN);
+  if (match == null) return null;
+  // The readable ap://did:... authority form is not RFC 3986 compliant:
+  // colons are not valid in a URI reg-name authority.  Keep accepting it for
+  // 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]);
+  if (!DID_PATTERN.test(authority)) {
+    throw new TypeError("Invalid portable ActivityPub IRI authority.");
+  }
+  if (match[3] === "") {
+    throw new TypeError("Invalid portable ActivityPub IRI path.");
+  }
+  return new URL(
+    `ap+ef61://${encodeURIComponent(authority)}${match[3]}${match[4] ?? ""}${
+      match[5] ?? ""
+    }`,
+  );
+}
+
+function normalizePortableUrl(iri: URL): URL | null {
+  if (iri.protocol !== "ap:" && iri.protocol !== "ap+ef61:") return null;
+  return parsePortableIri(
+    `ap+ef61://${iri.host}${iri.pathname}${iri.search}${iri.hash}`,
+  );
+}
+
+function normalizeBaseIri(base?: string | URL): string | URL | undefined {
+  if (base == null) return undefined;
+  if (base instanceof URL) return normalizePortableUrl(base) ?? base;
+  return parsePortableIri(base) ??
+    (base.startsWith("at://") && !URL.canParse(".", base)
+      ? parseAtUri(base)
+      : base);
+}
+
+function decodePortableAuthority(authority: string): string {
+  if (INVALID_PERCENT_ENCODING_PATTERN.test(authority)) {
+    throw new TypeError("Invalid portable ActivityPub IRI authority.");
+  }
+  if (DID_SCHEME_PATTERN.test(authority)) {
+    const decoded = authority.replace(/%25/gi, "%");
+    if (INVALID_PERCENT_ENCODING_PATTERN.test(decoded)) {
+      throw new TypeError("Invalid portable ActivityPub IRI authority.");
+    }
+    return decoded;
+  }
+  const decoded = authority.replace(
+    /%(25|3A)/gi,
+    (match) => match.toLowerCase() === "%3a" ? ":" : "%",
+  );
+  if (INVALID_PERCENT_ENCODING_PATTERN.test(decoded)) {
+    throw new TypeError("Invalid portable ActivityPub IRI authority.");
+  }
+  return decoded;
+}
+
+function parseAtUri(uri: string): URL {
+  const index = uri.indexOf("/", 5);
+  const authority = index >= 0 ? uri.slice(5, index) : uri.slice(5);
+  const path = index >= 0 ? uri.slice(index) : "";
+  return new URL("at://" + encodeURIComponent(authority) + path);
+}
+
 /**
  * Validates a URL to prevent SSRF attacks.
  */

package/tsdown.config.ts

@@ -4,7 +4,12 @@ import { defineConfig } from "tsdown";
 
 export default [
   defineConfig({
-    entry: ["src/mod.ts", "src/jsonld.ts", "src/temporal.ts"],
+    entry: [
+      "src/mod.ts",
+      "src/internal/jsonld-cache.ts",
+      "src/jsonld.ts",
+      "src/temporal.ts",
+    ],
     dts: { compilerOptions: { isolatedDeclarations: true, declaration: true } },
     format: ["esm", "cjs"],
     platform: "neutral",