@fedify/vocab-runtime 2.4.0-dev.1570 → 2.4.0-dev.1571

package/src/key.ts

@@ -22,6 +22,39 @@ const algorithms: Record<
   "1.3.101.112": "Ed25519",
 };
 
+const DID_KEY_PREFIX = "did:key:";
+const ED25519_PUBLIC_KEY_MULTICODEC = 0xed;
+const ED25519_PUBLIC_KEY_LENGTH = 32;
+const DID_KEY_PATTERN = /^did:key:([^/?#]+)$/;
+const DID_KEY_VERIFICATION_METHOD_PATTERN = /^did:key:([^/?#]+)#([^/?#]+)$/;
+
+/**
+ * Parsed `did:key` verification method.
+ *
+ * @since 2.4.0
+ */
+export interface DidKeyVerificationMethod {
+  /**
+   * The DID URL identifying the verification method.
+   */
+  readonly id: URL;
+
+  /**
+   * The controller DID.
+   */
+  readonly controller: URL;
+
+  /**
+   * The Ed25519 public key encoded as a Multibase Multikey value.
+   */
+  readonly publicKeyMultibase: string;
+
+  /**
+   * The Ed25519 public key.
+   */
+  readonly publicKey: CryptoKey;
+}
+
 /**
  * Imports a PEM-SPKI formatted public key.
  * @param pem The PEM-SPKI formatted public key.
@@ -93,6 +126,98 @@ export function importPem(pem: string): Promise<CryptoKey> {
   return PKCS1_HEADER.test(pem) ? importPkcs1(pem) : importSpki(pem);
 }
 
+function decodeEd25519DidKeyMultibase(multibaseKey: string): Uint8Array {
+  if (!multibaseKey.startsWith("z")) {
+    throw new TypeError("did:key must use base58-btc Multibase encoding.");
+  }
+  let decoded: Uint8Array;
+  try {
+    decoded = decodeMultibase(multibaseKey);
+  } catch (error) {
+    throw new TypeError("Invalid did:key Multibase encoding.", {
+      cause: error,
+    });
+  }
+  const { code } = getMulticodecPrefix(decoded);
+  if (code !== ED25519_PUBLIC_KEY_MULTICODEC) {
+    throw new TypeError("Unsupported did:key type: 0x" + code.toString(16));
+  }
+  const content = removeMulticodecPrefix(decoded);
+  if (content.length !== ED25519_PUBLIC_KEY_LENGTH) {
+    throw new TypeError("Invalid Ed25519 did:key length.");
+  }
+  return content;
+}
+
+/**
+ * Imports an Ed25519 `did:key` DID.
+ *
+ * @param did The `did:key` DID.
+ * @returns The imported Ed25519 public key.
+ * @throws {TypeError} If the DID is malformed or uses an unsupported key type.
+ * @since 2.4.0
+ */
+export async function importDidKey(did: string | URL): Promise<CryptoKey> {
+  const didString = did instanceof URL ? did.href : did;
+  const match = didString.match(DID_KEY_PATTERN);
+  if (match == null) throw new TypeError("Invalid did:key DID.");
+  const content = decodeEd25519DidKeyMultibase(match[1]);
+  return await crypto.subtle.importKey(
+    "raw",
+    content.slice(),
+    "Ed25519",
+    true,
+    ["verify"],
+  );
+}
+
+/**
+ * Exports an Ed25519 public key as a `did:key` DID.
+ *
+ * @param key The Ed25519 public key.
+ * @returns The `did:key` DID.
+ * @throws {TypeError} If the key is invalid or unsupported.
+ * @since 2.4.0
+ */
+export async function exportDidKey(key: CryptoKey): Promise<string> {
+  if (key.algorithm.name !== "Ed25519") {
+    throw new TypeError(
+      "Unsupported key type: " + JSON.stringify(key.algorithm),
+    );
+  }
+  return DID_KEY_PREFIX + await exportMultibaseKey(key);
+}
+
+/**
+ * Parses an Ed25519 `did:key` verification method DID URL.
+ *
+ * @param didUrl The `did:key` DID URL.
+ * @returns The parsed verification method.
+ * @throws {TypeError} If the DID URL is malformed, unsupported, or its
+ *                     fragment does not identify the same key as the DID.
+ * @since 2.4.0
+ */
+export async function parseDidKeyVerificationMethod(
+  didUrl: string | URL,
+): Promise<DidKeyVerificationMethod> {
+  const didUrlString = didUrl instanceof URL ? didUrl.href : didUrl;
+  const match = didUrlString.match(DID_KEY_VERIFICATION_METHOD_PATTERN);
+  if (match == null) {
+    throw new TypeError("Invalid did:key verification method.");
+  }
+  const [, publicKeyMultibase, fragment] = match;
+  if (publicKeyMultibase !== fragment) {
+    throw new TypeError("Invalid did:key verification method fragment.");
+  }
+  const publicKey = await importDidKey(DID_KEY_PREFIX + publicKeyMultibase);
+  return {
+    id: new URL(didUrlString),
+    controller: new URL(DID_KEY_PREFIX + publicKeyMultibase),
+    publicKeyMultibase,
+    publicKey,
+  };
+}
+
 /**
  * Imports a [Multibase]-encoded public key.
  *

package/src/mod.ts

@@ -17,12 +17,16 @@ export {
   type RemoteDocument,
 } from "./docloader.ts";
 export {
+  type DidKeyVerificationMethod,
+  exportDidKey,
   exportMultibaseKey,
   exportSpki,
+  importDidKey,
   importMultibaseKey,
   importPem,
   importPkcs1,
   importSpki,
+  parseDidKeyVerificationMethod,
 } from "./key.ts";
 export {
   canParseDecimal,
@@ -51,8 +55,12 @@ export {
 } from "./preprocessor.ts";
 export {
   expandIPv6Address,
+  formatIri,
+  haveSameIriOrigin,
   isValidPublicIPv4Address,
   isValidPublicIPv6Address,
+  parseIri,
+  parseJsonLdId,
   UrlError,
   validatePublicUrl,
 } from "./url.ts";

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",