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

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,
+  );
+}

package/src/portable-workers.test.ts

@@ -0,0 +1,81 @@
+import { test, testDefinitions } from "@fedify/fixture";
+import { deepStrictEqual, equal } from "node:assert/strict";
+import {
+  computeDigestMultibase,
+  createHashlink,
+  verifyHashlink,
+} from "./digest.ts";
+import { exportDidKey, importDidKey } from "./key.ts";
+import { getPortableGatewayCandidates } from "./internal/portable-dereference.ts";
+import {
+  canonicalizePortableUri,
+  formatIri,
+  fromCompatibleEf61Id,
+  parseIri,
+  toCompatibleEf61Id,
+} from "./url.ts";
+
+const portableId = "ap://did:key:z6Mkabc/actor";
+
+export { testDefinitions };
+
+test("vocab-runtime portable URI formats on Workers", () => {
+  equal(formatIri(parseIri(portableId)), "ap+ef61://did:key:z6Mkabc/actor");
+  equal(
+    canonicalizePortableUri(`${portableId}?@gateway=https%3A%2F%2Fa.example`),
+    "ap+ef61://did:key:z6Mkabc/actor",
+  );
+});
+
+test("vocab-runtime compatible IDs on Workers", () => {
+  const compatible = toCompatibleEf61Id(portableId, "https://gw.example");
+  equal(
+    compatible.href,
+    "https://gw.example/.well-known/apgateway/did:key:z6Mkabc/actor",
+  );
+  equal(
+    formatIri(fromCompatibleEf61Id(compatible)!),
+    "ap+ef61://did:key:z6Mkabc/actor",
+  );
+});
+
+test("vocab-runtime did:key on Workers", async () => {
+  const keys = await crypto.subtle.generateKey("Ed25519", true, [
+    "sign",
+    "verify",
+  ]) as CryptoKeyPair;
+  const did = await exportDidKey(keys.publicKey);
+  const imported = await importDidKey(did);
+  deepStrictEqual(
+    new Uint8Array(await crypto.subtle.exportKey("raw", imported)),
+    new Uint8Array(await crypto.subtle.exportKey("raw", keys.publicKey)),
+  );
+});
+
+test("vocab-runtime hashlink on Workers", async () => {
+  const bytes = new TextEncoder().encode("portable media");
+  const digest = await computeDigestMultibase(bytes);
+  equal(await verifyHashlink(bytes, createHashlink(digest)), true);
+  equal(
+    await verifyHashlink(
+      new TextEncoder().encode("tampered"),
+      createHashlink(digest),
+    ),
+    false,
+  );
+});
+
+test("vocab-runtime gateway candidates on Workers", () => {
+  const hinted = parseIri(
+    `${portableId}?@gateway=https%3A%2F%2Fhint.example`,
+  );
+  deepStrictEqual(
+    getPortableGatewayCandidates(hinted, ["https://first.example"])
+      .map((url) => url.href),
+    ["https://first.example/"],
+  );
+  deepStrictEqual(
+    getPortableGatewayCandidates(hinted).map((url) => url.href),
+    ["https://hint.example/"],
+  );
+});

package/src/portable.ts

@@ -0,0 +1,180 @@
+import type { TracerProvider } from "@opentelemetry/api";
+import type { DocumentLoader } from "./docloader.ts";
+
+/**
+ * Options passed to a {@link PortableObjectVerifier}.
+ * @since 2.4.0
+ */
+export interface PortableObjectVerifierOptions {
+  /**
+   * The document loader for fetching remote documents, such as verification
+   * methods that are not `did:key` URLs.
+   */
+  readonly documentLoader?: DocumentLoader;
+
+  /**
+   * The document loader for fetching remote JSON-LD contexts.  During
+   * gateway dereferencing, this loader returns the same context documents
+   * that the vocabulary parser sees.
+   */
+  readonly contextLoader?: DocumentLoader;
+
+  /**
+   * The OpenTelemetry tracer provider.
+   */
+  readonly tracerProvider?: TracerProvider;
+
+  /**
+   * The URL the document was finally retrieved from, i.e., the `documentUrl`
+   * of the document loader's result, which may differ from the requested URL
+   * after redirects.  Trust decisions such as the [FEP-ef61] gateway trust
+   * policy for unsecured collections depend on it, so custom document loaders
+   * must report it truthfully.
+   *
+   * [FEP-ef61]: https://w3id.org/fep/ef61
+   * @since 2.4.0
+   */
+  readonly documentUrl?: URL;
+
+  /**
+   * The gateways that the caller explicitly passed to the accessor through
+   * its `gateways` option, in order.  It is `undefined` if the caller did not
+   * pass the option, and can be empty.
+   * @since 2.4.0
+   */
+  readonly gateways?: readonly URL[];
+
+  /**
+   * The gateways inferred from the reference, in order, when the caller did
+   * not pass the `gateways` option: the `@gateway` location hints of
+   * a portable IRI, the gateway named by an FEP-ef61 compatible identifier,
+   * or the WebFinger server of a portable actor.  They only tell where the
+   * document and related objects might be retrieved, and must not be
+   * trusted to act for the portable object's DID.
+   * @since 2.4.0
+   */
+  readonly gatewayHints?: readonly URL[];
+
+  /**
+   * The object whose property referred to the document, if the document was
+   * dereferenced through a property accessor.
+   * @since 2.4.0
+   */
+  readonly referrer?: PortableObjectReferrer;
+}
+
+/**
+ * An object whose property referred to a portable object being verified.
+ * Referrers form a chain: {@link PortableObjectReferrer.referrer} is the
+ * object through which this referrer itself was obtained, and so on.
+ * @since 2.4.0
+ */
+export interface PortableObjectReferrer {
+  /**
+   * The referring vocabulary object.
+   */
+  readonly object: unknown;
+
+  /**
+   * The `@id` of the referring object, if any.
+   */
+  readonly id: URL | null;
+
+  /**
+   * The expanded URI of the property through which the referring object
+   * referred to the next object in the chain, e.g.,
+   * `https://www.w3.org/ns/activitystreams#outbox`.
+   */
+  readonly property: string;
+
+  /**
+   * How the referring object itself was accepted by a
+   * {@link PortableObjectVerifier} when it was dereferenced through gateways:
+   *
+   * - `"verified"`: accepted as verified, e.g., with a valid integrity proof.
+   * - `"unsecured"`: accepted without an integrity proof, e.g., as an
+   *   unsecured collection served by a trusted gateway.
+   *
+   * It is `undefined` if the referring object was not dereferenced through
+   * gateways, e.g., if it was embedded in another object or constructed by
+   * the application.
+   */
+  readonly acceptance?: "verified" | "unsecured";
+
+  /**
+   * The opaque collection context that a {@link PortableObjectVerifier}
+   * attached to the referring object when it accepted it.  See
+   * {@link PortableObjectVerification}.
+   */
+  readonly collectionContext?: unknown;
+
+  /**
+   * The referrer of the referring object, if any.
+   */
+  readonly referrer?: PortableObjectReferrer;
+
+  /**
+   * Whether the chain was cut off here because it was too long.  If `true`,
+   * the referring object may have a referrer which is not included.
+   */
+  readonly truncated?: boolean;
+}
+
+/**
+ * The result of a {@link PortableObjectVerifier}.
+ * @since 2.4.0
+ */
+export type PortableObjectVerification =
+  | {
+    /** Whether the document is accepted. */
+    readonly verified: false;
+  }
+  | {
+    /** Whether the document is accepted. */
+    readonly verified: true;
+
+    /**
+     * Whether the document was accepted without an integrity proof, e.g., as
+     * an unsecured [FEP-ef61] collection served by a gateway that its owner
+     * lists.  Objects embedded in such a document are not trusted because of
+     * their origin; property accessors dereference and verify them one by
+     * one instead.
+     *
+     * [FEP-ef61]: https://w3id.org/fep/ef61
+     */
+    readonly unsecured?: boolean;
+
+    /**
+     * An opaque value that the verifier wants to receive again as
+     * {@link PortableObjectReferrer.collectionContext} when objects referred
+     * to by this document, such as collection pages, are verified.
+     */
+    readonly collectionContext?: unknown;
+  };
+
+/**
+ * A function that applies the [FEP-ef61] trust policy to a portable object
+ * fetched through a gateway.
+ *
+ * It receives the fetched JSON-LD document as is, and resolves to an object
+ * whose `verified` property tells whether the document is acceptable, e.g.,
+ * whether it carries a valid [FEP-8b32] Object Integrity Proof made by the
+ * DID in its portable ID.  `verifyPortableObject()` and
+ * `verifyPortableObjectProof()` from `@fedify/fedify` satisfy this type, so
+ * they can be passed as the `verifyPortableObject` option of generated
+ * vocabulary accessors such as `Activity.getObject()`.
+ *
+ * [FEP-ef61]: https://w3id.org/fep/ef61
+ * [FEP-8b32]: https://w3id.org/fep/8b32
+ *
+ * @param document The fetched JSON-LD document.
+ * @param options Loaders, tracing options, and where the document came from.
+ * @returns An object whose `verified` property is `true` if and only if the
+ *          document satisfies the policy.  Other properties, such as
+ *          a failure reason, are logged when verification fails.
+ * @since 2.4.0
+ */
+export type PortableObjectVerifier = (
+  document: unknown,
+  options: PortableObjectVerifierOptions,
+) => Promise<PortableObjectVerification>;

package/src/preprocessor.ts

@@ -1,5 +1,6 @@
 import type { DocumentLoader } from "./docloader.ts";
 import type { TracerProvider } from "@opentelemetry/api";
+import type { PortableObjectVerifier } from "./portable.ts";
 
 /**
  * JSON value shape passed to property preprocessors.
@@ -24,6 +25,12 @@ export interface PropertyPreprocessorContext {
   contextLoader?: DocumentLoader;
   /** OpenTelemetry tracer provider for instrumentation. */
   tracerProvider?: TracerProvider;
+  /**
+   * The default FEP-ef61 portable object verifier that objects returned by
+   * the preprocessor should use for their property accessors.
+   * @since 2.4.0
+   */
+  verifyPortableObject?: PortableObjectVerifier;
   /** Base URL for resolving relative references. */
   baseUrl?: URL;
 }

package/src/request.test.ts

@@ -2,7 +2,7 @@ import { deepStrictEqual } from "node:assert";
 import process from "node:process";
 import { test } from "node:test";
 import metadata from "../deno.json" with { type: "json" };
-import { getUserAgent } from "./request.ts";
+import { createActivityPubRequest, getUserAgent } from "./request.ts";
 
 test("getUserAgent()", () => {
   if ("Deno" in globalThis) {
@@ -91,3 +91,12 @@ test("getUserAgent()", () => {
     );
   }
 });
+
+test("createActivityPubRequest() asks for the ActivityStreams profile", () => {
+  const request = createActivityPubRequest("https://example.com/object");
+  deepStrictEqual(
+    request.headers.get("Accept"),
+    "application/activity+json, " +
+      'application/ld+json; profile="https://www.w3.org/ns/activitystreams"',
+  );
+});

package/src/request.ts

@@ -31,6 +31,14 @@ export class FetchError extends Error {
   }
 }
 
+/**
+ * The `Accept` header value for fetching ActivityPub objects.  ActivityPub
+ * and FEP-ef61 gateways require the ActivityStreams profile on the JSON-LD
+ * media type.
+ */
+const ACTIVITYPUB_ACCEPT =
+  'application/activity+json, application/ld+json; profile="https://www.w3.org/ns/activitystreams"';
+
 /**
  * Options for creating a request.
  * @internal
@@ -52,7 +60,7 @@ export function createActivityPubRequest(
 ): Request {
   return new Request(url, {
     headers: {
-      Accept: "application/activity+json, application/ld+json",
+      Accept: ACTIVITYPUB_ACCEPT,
       "User-Agent": typeof options.userAgent === "string"
         ? options.userAgent
         : getUserAgent(options.userAgent),