@fedify/vocab-runtime 2.4.0-pr.934.40 → 2.4.0

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/mod.ts

@@ -15,6 +15,8 @@ export {
   type GetDocumentLoaderOptions,
   getRemoteDocument,
   type RemoteDocument,
+  resolveDocumentLoaderTimeout,
+  withDocumentLoaderTimeout,
 } from "./docloader.ts";
 export {
   type DidKeyVerificationMethod,
@@ -34,7 +36,28 @@ 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 {
+  fetchPortableMedia,
+  type FetchPortableMediaOptions,
+  type PortableMedia,
+} from "./portable-media.ts";
+export type {
+  PortableObjectReferrer,
+  PortableObjectVerification,
+  PortableObjectVerifier,
+  PortableObjectVerifierOptions,
+} from "./portable.ts";
 export {
   decodeMultibase,
   encodeMultibase,
@@ -58,13 +81,20 @@ export {
   canonicalizePortableUri,
   expandIPv6Address,
   formatIri,
+  fromCompatibleEf61Id,
   getFe34Origin,
+  getGatewayHints,
   haveSameFe34Origin,
   haveSameIriOrigin,
+  isGatewayUrl,
   isValidPublicIPv4Address,
   isValidPublicIPv6Address,
+  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",
+  ]);
+});

package/src/portable-media.ts

@@ -0,0 +1,264 @@
+import { MAX_BODY_SIZE, readBoundedBytes } from "./body.ts";
+import {
+  parseDigestMultibase,
+  parseHashlink,
+  verifyDigestMultibase,
+} from "./digest.ts";
+import { getUserAgent, type GetUserAgentOptions } from "./request.ts";
+import { parseGatewayUrl, validatePublicUrl } from "./url.ts";
+
+/** A link or document with an external resource and its integrity digest. */
+export interface PortableMedia {
+  readonly href?: URL | null;
+  readonly url?: URL | {
+    readonly href: URL | null;
+    readonly digestMultibase?: string | null;
+  } | null;
+  readonly digestMultibase?: string | null;
+}
+
+/** Options for {@link fetchPortableMedia}. */
+export interface FetchPortableMediaOptions {
+  /** Ordered FEP-ef61 gateway origins used for `hl:` resources. */
+  readonly gateways?: Iterable<string | URL>;
+  /** Expected digest when the first argument is a URL or string. */
+  readonly digestMultibase?: string;
+  /** Maximum decoded response size in bytes.  Defaults to 16 MiB. */
+  readonly maxBytes?: number;
+  /** Whether private network addresses may be fetched.  Defaults to `false`. */
+  readonly allowPrivateAddress?: boolean;
+  /** The HTTP `User-Agent` value or its components. */
+  readonly userAgent?: string | GetUserAgentOptions;
+  /** Cancels the entire retrieval and all gateway attempts. */
+  readonly signal?: AbortSignal;
+  /** Overall timeout in milliseconds.  Defaults to 10 seconds; `null` disables it. */
+  readonly timeout?: number | null;
+  /** Timeout per gateway in milliseconds.  Defaults to 3 seconds. */
+  readonly gatewayTimeout?: number | null;
+}
+
+function resolveTimeout(
+  value: number | null | undefined,
+  fallback: number,
+): number | null {
+  if (value === null) return null;
+  const result = value ?? fallback;
+  if (!Number.isFinite(result) || result <= 0 || result > 2_147_483_647) {
+    throw new RangeError(
+      "A media timeout must be a positive finite number of milliseconds.",
+    );
+  }
+  return Math.ceil(result);
+}
+
+async function withTimeout<T>(
+  operation: (signal: AbortSignal) => Promise<T>,
+  parent: AbortSignal | undefined,
+  timeout: number | null,
+): Promise<T> {
+  parent?.throwIfAborted();
+  const controller = new AbortController();
+  const onParentAbort = () => controller.abort(parent?.reason);
+  parent?.addEventListener("abort", onParentAbort, { once: true });
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  if (timeout != null) {
+    timer = setTimeout(() =>
+      controller.abort(
+        new DOMException(
+          `Media retrieval timed out after ${timeout} ms.`,
+          "TimeoutError",
+        ),
+      ), timeout);
+  }
+  let onAbort: (() => void) | undefined;
+  const aborted = new Promise<never>((_, reject) => {
+    onAbort = () => reject(controller.signal.reason);
+    controller.signal.addEventListener("abort", onAbort, { once: true });
+  });
+  try {
+    return await Promise.race([operation(controller.signal), aborted]);
+  } finally {
+    if (timer != null) clearTimeout(timer);
+    parent?.removeEventListener("abort", onParentAbort);
+    if (onAbort != null) {
+      controller.signal.removeEventListener("abort", onAbort);
+    }
+  }
+}
+
+function mediaTarget(media: string | URL | PortableMedia): {
+  url: string;
+  digestMultibase: string | null | undefined;
+} {
+  if (typeof media === "string" || media instanceof URL) {
+    return { url: media.toString(), digestMultibase: undefined };
+  }
+  const target = media.href ?? media.url;
+  const url = target instanceof URL
+    ? target.href
+    : target != null && typeof target === "object" && "href" in target
+    ? target.href?.href
+    : undefined;
+  if (url == null) throw new TypeError("Portable media has no URL or href.");
+  const linkDigest = target != null && !(target instanceof URL) &&
+      typeof target === "object" && "digestMultibase" in target
+    ? target.digestMultibase
+    : undefined;
+  if (media.digestMultibase != null && linkDigest != null) {
+    const outer = parseDigestMultibase(media.digestMultibase).digest;
+    const inner = parseDigestMultibase(linkDigest).digest;
+    if (outer.some((byte, i) => byte !== inner[i])) {
+      throw new TypeError("Media and linked resource digests disagree.");
+    }
+  }
+  return { url, digestMultibase: media.digestMultibase ?? linkDigest };
+}
+
+async function fetchVerified(
+  url: URL,
+  digestMultibase: string,
+  options: FetchPortableMediaOptions,
+  signal: AbortSignal,
+  maxBytes: number,
+): Promise<Response> {
+  const visited = new Set<string>();
+  for (let redirects = 0; redirects <= 20; redirects++) {
+    signal.throwIfAborted();
+    if (url.username !== "" || url.password !== "") {
+      throw new TypeError("Media URLs must not contain credentials.");
+    }
+    if (!options.allowPrivateAddress) await validatePublicUrl(url.href);
+    else if (url.protocol !== "http:" && url.protocol !== "https:") {
+      throw new TypeError("Media URLs must use HTTP(S).");
+    }
+    if (visited.has(url.href)) throw new TypeError("Media redirect loop.");
+    visited.add(url.href);
+    const response = await fetch(url, {
+      method: "GET",
+      headers: {
+        Accept: "*/*",
+        "User-Agent": typeof options.userAgent === "string"
+          ? options.userAgent
+          : getUserAgent(options.userAgent),
+      },
+      redirect: "manual",
+      signal,
+    });
+    if ([301, 302, 303, 307, 308].includes(response.status)) {
+      const location = response.headers.get("Location");
+      void response.body?.cancel().catch(() => {});
+      if (location == null || redirects === 20) {
+        throw new TypeError("Invalid or excessive media redirects.");
+      }
+      url = new URL(location, url);
+      continue;
+    }
+    if (response.status !== 200) {
+      void response.body?.cancel().catch(() => {});
+      throw new Error(`Media request failed with HTTP ${response.status}.`);
+    }
+    const bytes = await readBoundedBytes(response, maxBytes, url);
+    signal.throwIfAborted();
+    if (!await verifyDigestMultibase(bytes, digestMultibase)) {
+      throw new Error("Portable media digest does not match.");
+    }
+    const headers = new Headers();
+    const contentType = response.headers.get("Content-Type");
+    if (contentType != null) headers.set("Content-Type", contentType);
+    return new Response(bytes, { headers });
+  }
+  throw new TypeError("Too many media redirects.");
+}
+
+/**
+ * Fetches a portable object's external media and returns it only after its
+ * SHA-256 `digestMultibase` has been verified.  `hl:` resources are tried at
+ * the supplied gateways in order.  The result contains verified body bytes;
+ * its `Content-Type` is unverified metadata supplied by the server.
+ *
+ * @param media A Link, Image, Document, or URL with an external resource.
+ * @param options Retrieval, integrity, and network policy options.
+ * @returns A response containing only verified bytes.
+ * @throws {TypeError} If the media reference or digest is invalid.
+ * @throws {Error} If no source supplies a matching bounded resource.
+ * @since 2.4.0
+ */
+export async function fetchPortableMedia(
+  media: string | URL | PortableMedia,
+  options: FetchPortableMediaOptions = {},
+): Promise<Response> {
+  const { url, digestMultibase: propertyDigest } = mediaTarget(media);
+  const digestMultibase = propertyDigest ?? options.digestMultibase;
+  if (digestMultibase == null) {
+    throw new TypeError("Portable media requires digestMultibase.");
+  }
+  const expected = parseDigestMultibase(digestMultibase).digest;
+  const maxBytes = options.maxBytes ?? MAX_BODY_SIZE;
+  if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
+    throw new RangeError(
+      "The media size limit must be a positive safe integer.",
+    );
+  }
+  const timeout = resolveTimeout(options.timeout, 10_000);
+  const gatewayTimeout = resolveTimeout(options.gatewayTimeout, 3_000);
+  let targets: URL[];
+  let hashlink = false;
+  if (/^hl:/i.test(url)) {
+    hashlink = true;
+    const parsed = parseHashlink(url);
+    const hashDigest = parseDigestMultibase(parsed.digestMultibase).digest;
+    if (expected.some((byte, i) => byte !== hashDigest[i])) {
+      throw new TypeError("Hashlink and digestMultibase disagree.");
+    }
+    const gateways = [
+      ...new Set(
+        [...options.gateways ?? []].map((gateway) =>
+          parseGatewayUrl(gateway.toString()).origin
+        ),
+      ),
+    ];
+    if (gateways.length === 0) {
+      throw new TypeError("Hashlink media requires at least one gateway.");
+    }
+    targets = gateways.map((gateway) =>
+      new URL(`/.well-known/apgateway/${url}`, gateway)
+    );
+  } else {
+    const target = new URL(url);
+    if (target.protocol !== "http:" && target.protocol !== "https:") {
+      throw new TypeError("Portable media URLs must use HTTP(S) or hl:.");
+    }
+    targets = [target];
+  }
+  return await withTimeout(
+    async (signal) => {
+      let lastError: unknown;
+      for (const target of targets) {
+        signal.throwIfAborted();
+        try {
+          return await withTimeout(
+            (attemptSignal) =>
+              fetchVerified(
+                target,
+                digestMultibase,
+                options,
+                attemptSignal,
+                maxBytes,
+              ),
+            signal,
+            hashlink ? gatewayTimeout : null,
+          );
+        } catch (error) {
+          signal.throwIfAborted();
+          if (!hashlink) throw error;
+          lastError = error;
+        }
+      }
+      throw new Error("No gateway returned verified portable media.", {
+        cause: lastError,
+      });
+    },
+    options.signal,
+    timeout,
+  );
+}