@fedify/vocab 2.4.0-dev.2030 → 2.4.0-dev.2047

package/src/lookup.ts

@@ -1,12 +1,24 @@
-import type { GetUserAgentOptions } from "@fedify/vocab-runtime";
+import type {
+  GetUserAgentOptions,
+  PortableObjectVerifier,
+} from "@fedify/vocab-runtime";
 import {
+  canonicalizePortableUri,
   type DocumentLoader,
+  formatIri,
+  fromCompatibleEf61Id,
   getDocumentLoader,
   haveSameFe34Origin,
   haveSameIriOrigin,
   parseIri,
   type RemoteDocument,
 } from "@fedify/vocab-runtime";
+import {
+  dereferencePortableIri,
+  getPortableGatewayCandidates,
+  isPortableIri,
+  PortableObjectRejectedError,
+} from "@fedify/vocab-runtime/internal/portable-dereference";
 import { lookupWebFinger } from "@fedify/webfinger";
 import { getLogger } from "@logtape/logtape";
 import {
@@ -59,6 +71,9 @@ function getLookupRemoteHost(identifier: string | URL): string | undefined {
   let url: URL | undefined;
   if (identifier instanceof URL) {
     url = identifier;
+  } else if (PORTABLE_IRI_PATTERN.test(identifier)) {
+    // The authority of a portable IRI is a DID, not a host:
+    return undefined;
   } else {
     try {
       url = new URL(identifier);
@@ -70,6 +85,7 @@ function getLookupRemoteHost(identifier: string | URL): string | undefined {
       return extractHandleHost(stripped);
     }
   }
+  if (isPortableIri(url)) return undefined;
   if (url.host !== "") return url.host;
   // `acct:` URIs are opaque (no `//host` form), so the URL host is empty.
   // The user and authority live in `url.pathname` as
@@ -166,8 +182,39 @@ export interface LookupObjectOptions {
    * @since 1.8.0
    */
   signal?: AbortSignal;
+
+  /**
+   * The [FEP-ef61] proof policy to apply to portable objects, typically
+   * `verifyPortableObjectProof()` from `@fedify/fedify`, which
+   * `Context.lookupObject()` uses by default.
+   *
+   * When it is given, portable `ap:`/`ap+ef61:` identifiers and compatible
+   * identifiers (e.g., `https://server.example/.well-known/apgateway/did:...`),
+   * whether they are looked up directly or found in the `self` links of
+   * a WebFinger response, are fetched through FEP-ef61 gateways.  A fetched
+   * portable object is returned only if its `@id` identifies the requested
+   * portable object and this function accepts it.  Note that
+   * `crossOrigin: "trust"` does not skip these checks.
+   *
+   * Without it, portable identifiers are not looked up, and compatible
+   * identifiers are fetched as ordinary HTTP(S) URLs, whose objects with
+   * a portable `@id` are refused as cross-origin objects, even with
+   * `crossOrigin: "trust"`.
+   *
+   * [FEP-ef61]: https://w3id.org/fep/ef61
+   * @since 2.4.0
+   */
+  verifyPortableObject?: PortableObjectVerifier;
 }
 
+/**
+ * The maximum number of requests to FEP-ef61 gateways that a single
+ * {@link lookupObject} call makes for portable objects.  Gateways come from
+ * possibly untrusted WebFinger responses and location hints, so they are
+ * bounded to keep a single lookup from fanning out to many servers.
+ */
+const MAX_PORTABLE_ATTEMPTS = 5;
+
 /**
  * Looks up an ActivityStreams object by its URI (including `acct:` URIs)
  * or a fediverse handle (e.g., `@user@server` or `user@server`).
@@ -195,6 +242,12 @@ export interface LookupObjectOptions {
  * // returning a `Note` object.
  * ```
  *
+ * [FEP-ef61] portable objects, including portable actors found through
+ * WebFinger, are looked up only if the `verifyPortableObject` option is
+ * given; see {@link LookupObjectOptions.verifyPortableObject}.
+ *
+ * [FEP-ef61]: https://w3id.org/fep/ef61
+ *
  * @param identifier The URI or fediverse handle to look up.
  * @param options Lookup options.
  * @returns The object, or `null` if not found.
@@ -272,11 +325,41 @@ async function lookupObjectInternal(
 ): Promise<Object | null> {
   const documentLoader = options.documentLoader ??
     getDocumentLoader({ userAgent: options.userAgent });
+  const portable: PortableLookup = {
+    options,
+    documentLoader,
+    attempted: new Set(),
+    remaining: MAX_PORTABLE_ATTEMPTS,
+  };
   if (typeof identifier === "string") {
+    if (PORTABLE_IRI_PATTERN.test(identifier)) {
+      const candidate = parsePortableCandidate(identifier);
+      if (candidate == null) return null;
+      return await lookupPortableObject(portable, candidate, undefined);
+    }
     identifier = toAcctUrl(identifier) ?? new URL(identifier);
   }
+  if (isPortableIri(identifier)) {
+    let candidate: URL;
+    try {
+      candidate = parseIri(identifier);
+    } catch (error) {
+      if (error instanceof TypeError) return null;
+      throw error;
+    }
+    return await lookupPortableObject(portable, candidate, undefined);
+  }
   let remoteDoc: RemoteDocument | null = null;
   if (identifier.protocol === "http:" || identifier.protocol === "https:") {
+    const compatible = getCompatibleCandidate(identifier.href, options);
+    if (compatible !== undefined) {
+      if (compatible == null) return null;
+      return await lookupPortableObject(
+        portable,
+        compatible.id,
+        [compatible.gateway],
+      );
+    }
     try {
       remoteDoc = await documentLoader(identifier.href, {
         signal: options.signal,
@@ -295,6 +378,7 @@ async function lookupObjectInternal(
       signal: options.signal,
     });
     if (jrd?.links == null) return null;
+    const webFingerGateway = getWebFingerGateway(identifier);
     for (const l of jrd.links) {
       if (
         l.type !== "application/activity+json" &&
@@ -302,6 +386,42 @@ async function lookupObjectInternal(
             /application\/ld\+json;\s*profile="https:\/\/www.w3.org\/ns\/activitystreams"/,
           ) || l.rel !== "self" || l.href == null
       ) continue;
+      if (PORTABLE_IRI_PATTERN.test(l.href)) {
+        // FEP-ef61 says the WebFinger host is the actor's first gateway, so
+        // ask it first, and then the location hints in the link:
+        if (options.verifyPortableObject == null) {
+          logger.debug(
+            "Skipping the portable self link {href}, as the " +
+              "verifyPortableObject option is not given.",
+            { href: l.href },
+          );
+          continue;
+        }
+        const candidate = parsePortableCandidate(l.href);
+        if (candidate == null) continue;
+        const gateways = webFingerGateway == null ? [] : [webFingerGateway];
+        gateways.push(...getPortableGatewayCandidates(candidate));
+        const object = await lookupPortableObject(
+          portable,
+          candidate,
+          gateways,
+        );
+        if (object != null) return object;
+        if (options.signal?.aborted) return null;
+        continue;
+      }
+      const compatible = getCompatibleCandidate(l.href, options);
+      if (compatible !== undefined) {
+        if (compatible == null) continue;
+        const object = await lookupPortableObject(
+          portable,
+          compatible.id,
+          [compatible.gateway],
+        );
+        if (object != null) return object;
+        if (options.signal?.aborted) return null;
+        continue;
+      }
       try {
         remoteDoc = await documentLoader(l.href, {
           signal: options.signal,
@@ -335,7 +455,10 @@ async function lookupObjectInternal(
     throw error;
   }
   if (
-    options.crossOrigin !== "trust" && object.id != null &&
+    object.id != null &&
+    // A portable object belongs to its DID, not to the server that serves
+    // it, so crossOrigin: "trust" does not let a server vouch for it:
+    (options.crossOrigin !== "trust" || isPortableIri(object.id)) &&
     !haveSameIriOrigin(object.id, documentUrl) &&
     !haveSameFe34Origin(object.id, documentUrl)
   ) {
@@ -359,6 +482,183 @@ async function lookupObjectInternal(
   return object;
 }
 
+const PORTABLE_IRI_PATTERN = /^ap(?:\+ef61)?:/i;
+
+interface PortableLookup {
+  readonly options: LookupObjectOptions;
+  readonly documentLoader: DocumentLoader;
+  /** Pairs of a canonical portable ID and a gateway already asked. */
+  readonly attempted: Set<string>;
+  /** The number of gateway requests left for this lookup. */
+  remaining: number;
+}
+
+/**
+ * Parses a raw portable IRI.  URL parsing normalizes dot segments in the
+ * opaque path, which would make the parsed IRI identify another portable
+ * object, so such IRIs are refused.
+ */
+function parsePortableCandidate(iri: string): URL | null {
+  try {
+    const parsed = parseIri(iri);
+    if (
+      canonicalizePortableUri(iri) !==
+        canonicalizePortableUri(formatIri(parsed))
+    ) {
+      logger.debug(
+        "Refusing to look up the portable IRI {iri}, as its path cannot be " +
+          "represented without changing the identified object.",
+        { iri },
+      );
+      return null;
+    }
+    return parsed;
+  } catch (error) {
+    if (error instanceof TypeError) {
+      logger.debug("Invalid portable IRI {iri}: {error}", { iri, error });
+      return null;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Recognizes an FEP-ef61 compatible identifier to look up as a portable
+ * object.
+ * @returns `undefined` if the URL should be fetched as an ordinary HTTP(S)
+ *          URL, i.e., it is not a compatible identifier, or the
+ *          `verifyPortableObject` option is not given; `null` if it is
+ *          a malformed compatible identifier; otherwise, the portable ID and
+ *          the gateway to ask.
+ */
+function getCompatibleCandidate(
+  href: string,
+  options: LookupObjectOptions,
+): { id: URL; gateway: URL } | null | undefined {
+  if (options.verifyPortableObject == null || !URL.canParse(href)) {
+    return undefined;
+  }
+  const url = new URL(href);
+  try {
+    const id = fromCompatibleEf61Id(url);
+    if (id == null) return undefined;
+    return { id, gateway: new URL(url.origin) };
+  } catch (error) {
+    if (error instanceof TypeError) {
+      logger.debug(
+        "Invalid FEP-ef61 compatible identifier {href}: {error}",
+        { href, error },
+      );
+      return null;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Gets the origin of the WebFinger server that {@link lookupWebFinger} asks
+ * for the identifier, which is also the first gateway of a portable actor.
+ */
+function getWebFingerGateway(identifier: URL): URL | undefined {
+  let url: URL;
+  if (identifier.protocol === "acct:") {
+    const host = extractHandleHost(identifier.pathname);
+    if (host == null) return undefined;
+    url = new URL(`https://${host}/`);
+  } else if (
+    identifier.protocol === "http:" || identifier.protocol === "https:"
+  ) {
+    url = new URL(identifier.origin);
+  } else {
+    return undefined;
+  }
+  return url.username === "" && url.password === "" ? url : undefined;
+}
+
+/**
+ * Looks up a portable object through FEP-ef61 gateways.
+ * @param gateways The gateways to ask in order.  If omitted, the location
+ *                 hints in the IRI are used, and if there are none, the
+ *                 portable IRI itself is passed to the document loader.
+ */
+async function lookupPortableObject(
+  lookup: PortableLookup,
+  id: URL,
+  gateways: readonly URL[] | undefined,
+): Promise<Object | null> {
+  const { options } = lookup;
+  const iri = formatIri(id);
+  if (options.verifyPortableObject == null) {
+    logger.debug(
+      "Cannot look up the portable object {iri}, as the " +
+        "verifyPortableObject option is not given.",
+      { iri },
+    );
+    return null;
+  }
+  const canonicalId = canonicalizePortableUri(iri);
+  let candidates: URL[];
+  if (gateways == null) {
+    candidates = getPortableGatewayCandidates(id);
+    if (candidates.length < 1) {
+      // No gateway to ask; a custom document loader may know how to
+      // retrieve the portable IRI itself:
+      const key = `${canonicalId} `;
+      if (lookup.remaining < 1 || lookup.attempted.has(key)) return null;
+      lookup.attempted.add(key);
+      lookup.remaining--;
+      return await dereference(lookup, id, []);
+    }
+  } else {
+    candidates = [...gateways];
+  }
+  const selected: URL[] = [];
+  for (const gateway of candidates) {
+    if (selected.length >= lookup.remaining) break;
+    const key = `${canonicalId} ${gateway.href}`;
+    if (lookup.attempted.has(key)) continue;
+    lookup.attempted.add(key);
+    selected.push(gateway);
+  }
+  if (selected.length < 1) return null;
+  lookup.remaining -= selected.length;
+  return await dereference(lookup, id, selected);
+}
+
+async function dereference(
+  { options, documentLoader }: PortableLookup,
+  id: URL,
+  gateways: readonly URL[],
+): Promise<Object | null> {
+  const tracerProvider = options.tracerProvider ?? trace.getTracerProvider();
+  try {
+    return await dereferencePortableIri(id, {
+      documentLoader,
+      contextLoader: options.contextLoader ??
+        getDocumentLoader({ userAgent: options.userAgent }),
+      tracerProvider,
+      gateways,
+      verifyPortableObject: options.verifyPortableObject,
+      crossOrigin: options.crossOrigin === "throw" ? "throw" : "ignore",
+      signal: options.signal,
+      parse: (document, { contextLoader, baseUrl }) =>
+        Object.fromJsonLd(document, {
+          documentLoader,
+          contextLoader,
+          tracerProvider,
+          baseUrl,
+        }),
+    });
+  } catch (error) {
+    if (error instanceof PortableObjectRejectedError) throw error;
+    logger.debug(
+      "Failed to look up the portable object {iri}:\n{error}",
+      { iri: formatIri(id), error },
+    );
+    return null;
+  }
+}
+
 /**
  * Options for the {@link traverseCollection} function.
  * @since 1.1.0