@fedify/vocab-runtime 2.4.0-pr.936.41 → 2.4.1

package/src/key.ts

@@ -174,12 +174,22 @@ export async function importDidKey(did: string | URL): Promise<CryptoKey> {
 /**
  * Exports an Ed25519 public key as a `did:key` DID.
  *
+ * The DID is encoded in base58-btc with the Ed25519 multicodec prefix, e.g.,
+ * `did:key:z6Mk...`, as [FEP-ef61] requires for the DIDs of portable
+ * objects.
+ *
+ * [FEP-ef61]: https://w3id.org/fep/ef61
+ *
  * @param key The Ed25519 public key.
  * @returns The `did:key` DID.
- * @throws {TypeError} If the key is invalid or unsupported.
+ * @throws {TypeError} If the key is invalid or unsupported, or it is not
+ *                     a public key.
  * @since 2.4.0
  */
 export async function exportDidKey(key: CryptoKey): Promise<string> {
+  if (key.type !== "public") {
+    throw new TypeError("The key must be a public key.");
+  }
   if (key.algorithm.name !== "Ed25519") {
     throw new TypeError(
       "Unsupported key type: " + JSON.stringify(key.algorithm),

package/src/langstr.test.ts

@@ -1,4 +1,4 @@
-import { deepStrictEqual } from "node:assert";
+import { deepStrictEqual, throws } from "node:assert";
 import { test } from "node:test";
 import util from "node:util";
 import { LanguageString } from "./langstr.ts";
@@ -11,6 +11,23 @@ test("new LanguageString()", () => {
   deepStrictEqual(new LanguageString("Hello", new Intl.Locale("en")), langStr);
 });
 
+test("new LanguageString() with extlang tags", () => {
+  // Intl.Locale objects have no own enumerable properties, so their base names
+  // are compared instead:
+  deepStrictEqual(new LanguageString("你好", "zh-YUE").locale.baseName, "yue");
+  deepStrictEqual(
+    new LanguageString("你好", "zh-yue-HK").locale.baseName,
+    "yue-HK",
+  );
+  // Whether cmn is canonicalized to zh depends on the runtime:
+  deepStrictEqual(
+    new LanguageString("你好", "zh-cmn-Hant").locale.baseName,
+    new Intl.Locale("cmn-Hant").baseName,
+  );
+  throws(() => new LanguageString("Hello", "en-USA"), RangeError);
+  throws(() => new LanguageString("你好", "zh-yue-"), RangeError);
+});
+
 test("Deno.inspect(LanguageString)", () => {
   const langStr = new LanguageString("Hello, 'world'", "en");
   deepStrictEqual(

package/src/langstr.ts

@@ -1,3 +1,5 @@
+import { normalizeLanguageTag } from "./langtag.ts";
+
 /**
  * A language-tagged string which corresponds to the `rdf:langString` type.
  */
@@ -12,12 +14,14 @@ export class LanguageString extends String {
    * Constructs a new `LanguageString`.
    * @param value A string value written in the given language.
    * @param language The language of the string.  If a string is given, it will
-   *                 be parsed as a `Intl.Locale` object.
+   *                 be parsed as a `Intl.Locale` object.  Extended language
+   *                 subtags are normalized first, e.g., `zh-yue` is parsed as
+   *                 `yue`.
    */
   constructor(value: string, language: Intl.Locale | string) {
     super(value);
     this.locale = typeof language === "string"
-      ? new Intl.Locale(language)
+      ? new Intl.Locale(normalizeLanguageTag(language))
       : language;
   }
 }

package/src/langtag.test.ts

@@ -0,0 +1,53 @@
+import { deepStrictEqual } from "node:assert";
+import { test } from "node:test";
+import { normalizeLanguageTag } from "./langtag.ts";
+
+test("normalizeLanguageTag() removes extlang subtags", () => {
+  const cases: [string, string][] = [
+    ["zh-yue", "yue"],
+    ["zh-YUE", "yue"],
+    ["ZH-Yue-hk", "yue-hk"],
+    ["zh-yue-HK", "yue-HK"],
+    ["zh-cmn-Hant", "cmn-Hant"],
+    ["zh-yue-u-nu-hanidec", "yue-u-nu-hanidec"],
+    ["sgn-ase", "ase"],
+    ["ar-arz", "arz"],
+    ["ms-zlm", "zlm"],
+    ["kok-gom", "gom"],
+    ["koK-gom", "gom"],
+    ["lv-ltg", "ltg"],
+    ["sw-swc", "swc"],
+    ["uz-uzs", "uzs"],
+    // Valid tags never have more than one extlang, so only the first one is
+    // removed and the result is still rejected by Intl.Locale:
+    ["zh-yue-cmn", "yue-cmn"],
+    ["zh-yue-", "yue-"],
+  ];
+  for (const [input, expected] of cases) {
+    deepStrictEqual(normalizeLanguageTag(input), expected, input);
+  }
+});
+
+test("normalizeLanguageTag() leaves other tags unchanged", () => {
+  const tags = [
+    "",
+    "en",
+    "en-US",
+    "en-USA",
+    "en-yue",
+    "zh",
+    "zh-Hant-TW",
+    "yue",
+    "yue-HK",
+    "x-private",
+    "i-klingon",
+    "zh-min-nan",
+    "koK-gom",
+    "zh-yuK",
+    "constructor-yue",
+    "toString-yue",
+  ];
+  for (const tag of tags) {
+    deepStrictEqual(normalizeLanguageTag(tag), tag, tag);
+  }
+});

package/src/langtag.ts

@@ -0,0 +1,76 @@
+/**
+ * Extended language subtags (extlangs) registered in the IANA Language Subtag
+ * Registry, grouped by their prefixes.  Every extlang record has exactly one
+ * prefix and a `Preferred-Value` equal to the extlang subtag itself, so
+ * replacing the prefix and the extlang with the extlang alone yields
+ * the canonical form.
+ *
+ * Generated from the registry with File-Date: 2026-09-17.
+ */
+const EXTLANGS: Record<string, string> = {
+  ar: "aao abh abv acm acq acw acx acy adf aeb aec afb ajp apc apd arb arq " +
+    "ars ary arz auz avl ayh ayl ayn ayp bbz pga shu ssh",
+  kok: "gom knn",
+  lv: "ltg lvs",
+  ms: "bjn btj bve bvu coa dup hji jak jax kvb kvr kxd lce lcf liw max meo " +
+    "mfa mfb min mqg msi mui orn ors pel pse tmw urk vkk vkt xmm zlm zmi " +
+    "zsm",
+  sgn: "ads aed aen afg ajs ase asf asp asq asw bfi bfk bog bqn bqy bvl bzs " +
+    "cds csc csd cse csf csg csl csn csq csr csx doq dse dsl dsz dyl ecs " +
+    "ehs esl esn eso eth fcs fse fsl fss gds gse gsg gsm gss gus hab haf " +
+    "hds hks hos hps hsh hsl icl iks ils inl ins ise isg isr jcs jhs jks " +
+    "jls jos jsl jus kgi kvk lbs lgs lls lsb lsc lsg lsl lsn lso lsp lst " +
+    "lsv lsw lsy lws mdl mfs mre msd msr mzc mzg mzy nbs ncs nsi nsl nsp " +
+    "nsr nzs okl pgz pks prl prz psc psd psg psl pso psp psr pys rib rms " +
+    "rnb rsi rsl rsm rsn sdl sfb sfs sgg sgx slf sls sqk sqs sqx ssp ssr " +
+    "svk swl syy szs tse tsm tsq tss tsy tza ugn ugy ukl uks vgt vsi vsl " +
+    "vsv wbs xki xml xms yds ygs yhs ysl ysm zhk zib zsl",
+  sw: "swc swh",
+  uz: "uzn uzs",
+  zh: "cdo cjy cmn cnp cpx csp czh czo gan hak hnm hsn luh lzh mnp nan sjc " +
+    "wuu yue",
+};
+
+const EXTLANG_PAIRS: ReadonlySet<string> = new Set(
+  Object.entries(EXTLANGS).flatMap(([prefix, extlangs]) =>
+    extlangs.split(" ").map((extlang) => `${prefix}-${extlang}`)
+  ),
+);
+
+const PREFIX_PATTERN = /^[A-Za-z]{2,3}$/;
+const EXTLANG_PATTERN = /^[A-Za-z]{3}$/;
+
+/**
+ * Normalizes a BCP 47 language tag that has an extended language subtag
+ * (extlang), such as `zh-yue`, into its canonical form, such as `yue`, as
+ * described in [RFC 5646, Section 4.5][1].  `Intl.Locale` rejects extlang
+ * tags, so tags should be normalized before being passed to it.
+ *
+ * Only registered extlangs that follow their registered prefix are removed;
+ * any other tag is returned unchanged, so the result still needs to be
+ * validated, e.g., by `Intl.Locale`.
+ *
+ * NOTE: This function is marked as internal in the 2.0.x–2.4.x patch
+ * releases.  When merging it into the *main* branch, remove the `@internal`
+ * tag, formalize it as a public API (`@since 2.5.0`), and add it to
+ * the changelog fragment.
+ *
+ * [1]: https://www.rfc-editor.org/rfc/rfc5646.html#section-4.5
+ *
+ * @param tag The BCP 47 language tag to normalize.
+ * @returns The normalized language tag.
+ * @internal
+ */
+export function normalizeLanguageTag(tag: string): string {
+  const subtags = tag.split("-");
+  if (subtags.length < 2) return tag;
+  const [prefix, extlang, ...rest] = subtags;
+  // Checked before case folding, since `toLowerCase()` maps some non-ASCII
+  // characters (e.g., U+212A KELVIN SIGN) to ASCII letters:
+  if (!PREFIX_PATTERN.test(prefix) || !EXTLANG_PATTERN.test(extlang)) {
+    return tag;
+  }
+  const language = extlang.toLowerCase();
+  if (!EXTLANG_PAIRS.has(`${prefix.toLowerCase()}-${language}`)) return tag;
+  return [language, ...rest].join("-");
+}

package/src/mod.ts

@@ -15,6 +15,8 @@ export {
   type GetDocumentLoaderOptions,
   getRemoteDocument,
   type RemoteDocument,
+  resolveDocumentLoaderTimeout,
+  withDocumentLoaderTimeout,
 } from "./docloader.ts";
 export {
   type DidKeyVerificationMethod,
@@ -34,7 +36,29 @@ export {
   isDecimal,
   parseDecimal,
 } from "./decimal.ts";
+export {
+  computeDigestMultibase,
+  createHashlink,
+  type ParsedDigestMultibase,
+  type ParsedHashlink,
+  parseDigestMultibase,
+  parseHashlink,
+  verifyDigestMultibase,
+  verifyHashlink,
+} from "./digest.ts";
 export { LanguageString } from "./langstr.ts";
+export { normalizeLanguageTag } from "./langtag.ts";
+export {
+  fetchPortableMedia,
+  type FetchPortableMediaOptions,
+  type PortableMedia,
+} from "./portable-media.ts";
+export type {
+  PortableObjectReferrer,
+  PortableObjectVerification,
+  PortableObjectVerifier,
+  PortableObjectVerifierOptions,
+} from "./portable.ts";
 export {
   decodeMultibase,
   encodeMultibase,
@@ -58,7 +82,9 @@ export {
   canonicalizePortableUri,
   expandIPv6Address,
   formatIri,
+  fromCompatibleEf61Id,
   getFe34Origin,
+  getGatewayHints,
   haveSameFe34Origin,
   haveSameIriOrigin,
   isGatewayUrl,
@@ -67,6 +93,9 @@ export {
   parseGatewayUrl,
   parseIri,
   parseJsonLdId,
+  toCompatibleEf61Id,
   UrlError,
   validatePublicUrl,
+  withGatewayHints,
+  withoutGatewayHints,
 } from "./url.ts";

package/src/multibase/multibase.test.ts

@@ -1,5 +1,5 @@
 import { deepStrictEqual } from "node:assert";
-import { test } from "node:test";
+import { test } from "@fedify/fixture";
 import * as constants from "./constants.ts";
 import { decodeMultibase, encodeMultibase } from "./mod.ts";
 import type { BaseName } from "./types.d.ts";
@@ -76,7 +76,7 @@ test("multibase.encode and decode", async (t) => {
   ];
 
   for (const [name, input, expectedOutput] of testCases) {
-    await t.test(`Encoding/Decoding ${name} with ${input}`, () => {
+    await t.step(`Encoding/Decoding ${name} with ${input}`, () => {
       const encoded = encodeMultibase(name, encodeText(input));
       deepStrictEqual(
         decodeText(encoded),
@@ -96,7 +96,7 @@ test("multibase.encode and decode", async (t) => {
     });
   }
 
-  await t.test("should allow base32pad full alphabet", () => {
+  await t.step("should allow base32pad full alphabet", () => {
     const encodedStr = "ctimaq4ygg2iegci7";
     const decoded = decodeMultibase(encodedStr);
     const encoded = encodeMultibase("c", decoded);
@@ -105,12 +105,12 @@ test("multibase.encode and decode", async (t) => {
 });
 
 test("constants", async (t) => {
-  await t.test("constants indexed by name", () => {
+  await t.step("constants indexed by name", () => {
     const names = constants.names;
     deepStrictEqual(Object.keys(names).length, 23);
   });
 
-  await t.test("constants indexed by code", () => {
+  await t.step("constants indexed by code", () => {
     const codes = constants.codes;
     deepStrictEqual(Object.keys(codes).length, 23);
   });

package/src/portable-media.test.ts

@@ -0,0 +1,293 @@
+import { deepStrictEqual, equal, rejects } from "node:assert/strict";
+import { createServer } from "node:http";
+import { test } from "node:test";
+import type { Document, Image, Link } from "@fedify/vocab";
+import { computeDigestMultibase, createHashlink } from "./digest.ts";
+import { fetchPortableMedia, type PortableMedia } from "./portable-media.ts";
+
+const bytes = new TextEncoder().encode("portable image");
+const digest = "zQmU2Jds4B2J83K7CrYC34CEJdB6vCLyqkM2cgBxYeaNWTA";
+const hashlink = createHashlink(digest);
+
+const networkTest = (name: string, run: () => Promise<void>) =>
+  test(name, async (t) => {
+    if (
+      "Deno" in globalThis &&
+      (await Deno.permissions.query({ name: "net" })).state !== "granted"
+    ) {
+      t.skip("Requires network permission for a local test server.");
+      return;
+    }
+    await run();
+  });
+
+type Handler = (path: string) => Response | undefined;
+
+async function withServers(
+  handlers: Handler[],
+  run: (origins: string[]) => Promise<void>,
+): Promise<void> {
+  const servers = handlers.map((handler) =>
+    createServer(async (request, reply) => {
+      const result = handler(request.url ?? "/");
+      if (result == null) return;
+      reply.writeHead(result.status, Object.fromEntries(result.headers));
+      reply.end(new Uint8Array(await result.arrayBuffer()));
+    })
+  );
+  try {
+    const origins: string[] = [];
+    for (const server of servers) {
+      await new Promise<void>((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", resolve);
+      });
+      const address = server.address();
+      if (address == null || typeof address === "string") {
+        throw new Error("Server did not bind a TCP port.");
+      }
+      origins.push(`http://127.0.0.1:${address.port}`);
+    }
+    await run(origins);
+  } finally {
+    await Promise.all(servers.map(async (server) => {
+      server.closeAllConnections();
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+    }));
+  }
+}
+
+networkTest(
+  "fetchPortableMedia() accepts Link, Image, and Document",
+  async () => {
+    const accepts = <T extends PortableMedia>() => {};
+    accepts<Link>();
+    accepts<Image>();
+    accepts<Document>();
+    const link: PortableMedia = {
+      href: new URL(hashlink),
+      digestMultibase: digest,
+    };
+    const image: PortableMedia = {
+      url: new URL(hashlink),
+      digestMultibase: digest,
+    };
+    const document: PortableMedia = {
+      url: { href: new URL(hashlink), digestMultibase: digest },
+    };
+    const requested: string[] = [];
+    await withServers([(path) => {
+      requested.push(path);
+      return new Response(bytes);
+    }], async ([gateway]) => {
+      for (const media of [link, image, document]) {
+        equal(
+          await (await fetchPortableMedia(media, {
+            gateways: [gateway],
+            allowPrivateAddress: true,
+          })).text(),
+          "portable image",
+        );
+      }
+    });
+    deepStrictEqual(
+      requested,
+      Array(3).fill(
+        `/.well-known/apgateway/${hashlink}`,
+      ),
+    );
+  },
+);
+
+networkTest(
+  "fetchPortableMedia() falls back on status and digest mismatch",
+  async () => {
+    const requested: string[] = [];
+    await withServers([
+      (path) => {
+        requested.push(`first:${path}`);
+        return new Response(null, { status: 503 });
+      },
+      (path) => {
+        requested.push(`second:${path}`);
+        return new Response("wrong bytes");
+      },
+      (path) => {
+        requested.push(`third:${path}`);
+        return new Response(bytes, {
+          headers: { "Content-Type": "image/png", "Set-Cookie": "secret=1" },
+        });
+      },
+    ], async (gateways) => {
+      const result = await fetchPortableMedia(
+        { url: new URL(hashlink), digestMultibase: digest },
+        { gateways, allowPrivateAddress: true },
+      );
+      equal(await result.text(), "portable image");
+      equal(result.headers.get("Content-Type"), "image/png");
+      equal(result.headers.get("Set-Cookie"), null);
+    });
+    deepStrictEqual(requested.map((r) => r.split(":")[0]), [
+      "first",
+      "second",
+      "third",
+    ]);
+  },
+);
+
+networkTest("fetchPortableMedia() verifies direct HTTP media", async () => {
+  const wrongDigest = await computeDigestMultibase(new Uint8Array());
+  await withServers([() => new Response(bytes)], async ([origin]) => {
+    const result = await fetchPortableMedia(`${origin}/a`, {
+      digestMultibase: digest,
+      allowPrivateAddress: true,
+    });
+    equal(await result.text(), "portable image");
+    await rejects(() =>
+      fetchPortableMedia(`${origin}/a`, {
+        digestMultibase: wrongDigest,
+        allowPrivateAddress: true,
+      }), /digest does not match/);
+  });
+});
+
+test("fetchPortableMedia() rejects invalid references before fetching", async () => {
+  const wrongDigest = await computeDigestMultibase(new Uint8Array());
+  await rejects(
+    () => fetchPortableMedia({ url: new URL(hashlink) }),
+    /requires digestMultibase/,
+  );
+  await rejects(() =>
+    fetchPortableMedia({
+      url: new URL(hashlink),
+      digestMultibase: digest,
+    }), /requires at least one gateway/);
+  await rejects(() =>
+    fetchPortableMedia({
+      url: new URL(hashlink),
+      digestMultibase: wrongDigest,
+    }, { gateways: ["https://example.com"] }), /disagree/);
+  await rejects(() =>
+    fetchPortableMedia({
+      url: new URL("hl:invalid"),
+      digestMultibase: digest,
+    }, { gateways: ["https://example.com"] }), TypeError);
+  await rejects(() =>
+    fetchPortableMedia({
+      url: { href: new URL(hashlink), digestMultibase: wrongDigest },
+      digestMultibase: digest,
+    }, { gateways: ["https://example.com"] }), /digests disagree/);
+  await rejects(() =>
+    fetchPortableMedia("file:///tmp/media", {
+      digestMultibase: digest,
+    }), TypeError);
+});
+
+networkTest("fetchPortableMedia() bounds response bytes", async () => {
+  await withServers([() => new Response(bytes)], async ([origin]) => {
+    await rejects(() =>
+      fetchPortableMedia(`${origin}/media`, {
+        digestMultibase: digest,
+        maxBytes: bytes.length - 1,
+        allowPrivateAddress: true,
+      }), /exceeds the limit/);
+  });
+  await rejects(() =>
+    fetchPortableMedia("https://example.com/media", {
+      digestMultibase: digest,
+      maxBytes: 0,
+    }), RangeError);
+});
+
+test("fetchPortableMedia() rejects private media and gateways", async () => {
+  await rejects(() =>
+    fetchPortableMedia("http://127.0.0.1/media", {
+      digestMultibase: digest,
+    }), /private address/);
+  await rejects(
+    () =>
+      fetchPortableMedia({
+        url: new URL(hashlink),
+        digestMultibase: digest,
+      }, { gateways: ["http://127.0.0.1"] }),
+    /No gateway returned verified portable media/,
+  );
+});
+
+test("fetchPortableMedia() propagates cancellation", async () => {
+  const controller = new AbortController();
+  const reason = new Error("cancelled");
+  controller.abort(reason);
+  await rejects(() =>
+    fetchPortableMedia({
+      url: new URL(hashlink),
+      digestMultibase: digest,
+    }, {
+      gateways: ["https://example.com"],
+      signal: controller.signal,
+    }), (error) => error === reason);
+});
+
+networkTest(
+  "fetchPortableMedia() falls back after a gateway timeout",
+  async () => {
+    await withServers([
+      () => undefined,
+      () => new Response(bytes),
+    ], async (gateways) => {
+      const response = await fetchPortableMedia({
+        url: new URL(hashlink),
+        digestMultibase: digest,
+      }, {
+        gateways,
+        allowPrivateAddress: true,
+        gatewayTimeout: 500,
+        timeout: 5_000,
+      });
+      equal(await response.text(), "portable image");
+    });
+  },
+);
+
+networkTest("fetchPortableMedia() applies one overall timeout", async () => {
+  await withServers(
+    [() => undefined, () => new Response(bytes)],
+    async (gateways) => {
+      await rejects(
+        () =>
+          fetchPortableMedia({
+            url: new URL(hashlink),
+            digestMultibase: digest,
+          }, {
+            gateways,
+            allowPrivateAddress: true,
+            gatewayTimeout: 100,
+            timeout: 20,
+          }),
+        (error) =>
+          error instanceof DOMException && error.name === "TimeoutError",
+      );
+    },
+  );
+});
+
+networkTest("fetchPortableMedia() follows a safe redirect", async () => {
+  const requested: string[] = [];
+  await withServers([(path) => {
+    requested.push(path);
+    return path === "/media" ? new Response(bytes) : new Response(null, {
+      status: 302,
+      headers: { Location: "/media" },
+    });
+  }], async ([gateway]) => {
+    const response = await fetchPortableMedia({
+      url: new URL(hashlink),
+      digestMultibase: digest,
+    }, { gateways: [gateway], allowPrivateAddress: true });
+    equal(await response.text(), "portable image");
+  });
+  deepStrictEqual(requested, [
+    `/.well-known/apgateway/${hashlink}`,
+    "/media",
+  ]);
+});