@fedify/vocab 2.4.0-dev.2056 → 2.4.0-dev.2065

package/src/lookup.ts

@@ -6,7 +6,6 @@ import {
   canonicalizePortableUri,
   type DocumentLoader,
   formatIri,
-  fromCompatibleEf61Id,
   getDocumentLoader,
   haveSameFe34Origin,
   haveSameIriOrigin,
@@ -14,9 +13,12 @@ import {
   type RemoteDocument,
 } from "@fedify/vocab-runtime";
 import {
+  createSnapshotContextLoader,
   dereferencePortableIri,
   getPortableGatewayCandidates,
+  getPortableResponseClaim,
   isPortableIri,
+  parseCompatibleEf61Reference,
   PortableObjectRejectedError,
 } from "@fedify/vocab-runtime/internal/portable-dereference";
 import { lookupWebFinger } from "@fedify/webfinger";
@@ -193,8 +195,11 @@ export interface LookupObjectOptions {
    * 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.
+   * portable object and this function accepts it.  A document fetched from
+   * an ordinary HTTP(S) URL is checked the same way if its final URL or its
+   * `@id` is a portable or compatible identifier, instead of being trusted
+   * because of its origin.  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
@@ -434,52 +439,82 @@ async function lookupObjectInternal(
     }
   }
   if (remoteDoc == null) return null;
-  let object: Object;
-  let documentUrl: URL;
+  // With verifyPortableObject, the document may turn out to be a portable
+  // object, which has to be verified with the same context documents:
+  const snapshot = options.verifyPortableObject == null
+    ? null
+    : createSnapshotContextLoader(
+      options.contextLoader ??
+        getDocumentLoader({ userAgent: options.userAgent }),
+    );
   try {
-    documentUrl = parseIri(remoteDoc.documentUrl);
-    object = await Object.fromJsonLd(remoteDoc.document, {
-      documentLoader,
-      contextLoader: options.contextLoader,
-      tracerProvider: options.tracerProvider,
-      baseUrl: documentUrl,
-    });
-  } catch (error) {
-    if (error instanceof TypeError) {
-      logger.debug(
-        "Failed to parse JSON-LD document: {error}\n{document}",
-        { ...remoteDoc, error },
-      );
-      return null;
+    let object: Object;
+    let documentUrl: URL;
+    try {
+      documentUrl = parseIri(remoteDoc.documentUrl);
+      object = await Object.fromJsonLd(remoteDoc.document, {
+        documentLoader,
+        contextLoader: snapshot?.loader ?? options.contextLoader,
+        tracerProvider: options.tracerProvider,
+        baseUrl: documentUrl,
+      });
+    } catch (error) {
+      if (error instanceof TypeError) {
+        logger.debug(
+          "Failed to parse JSON-LD document: {error}\n{document}",
+          { ...remoteDoc, error },
+        );
+        return null;
+      }
+      throw error;
     }
-    throw error;
-  }
-  if (
-    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)
-  ) {
-    if (options.crossOrigin === "throw") {
-      throw new Error(
-        `The object's @id (${object.id.href}) has a different origin than ` +
-          `the document URL (${remoteDoc.documentUrl}); refusing to return ` +
-          `the object.  If you want to bypass this check and are aware of ` +
-          `the security implications, set the crossOrigin option to "trust".`,
+    if (snapshot != null) {
+      // A document whose final URL or @id stands for a portable object is
+      // verified as one instead of being trusted because of its origin:
+      const claim = getPortableResponseClaim(remoteDoc.documentUrl, object.id);
+      if (claim === null) {
+        logger.debug(
+          "Refusing the document {documentUrl}, as it claims to be " +
+            "a portable object with a malformed compatible identifier.",
+          { documentUrl: remoteDoc.documentUrl },
+        );
+        return null;
+      } else if (claim != null) {
+        return await dereference(portable, claim.id, claim.inferredGateways, {
+          response: remoteDoc,
+          contextLoader: snapshot.loader,
+        });
+      }
+    }
+    if (
+      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)
+    ) {
+      if (options.crossOrigin === "throw") {
+        throw new Error(
+          `The object's @id (${object.id.href}) has a different origin than ` +
+            `the document URL (${remoteDoc.documentUrl}); refusing to return ` +
+            `the object.  If you want to bypass this check and are aware of ` +
+            `the security implications, set the crossOrigin option to "trust".`,
+        );
+      }
+      logger.warn(
+        "The object's @id ({objectId}) has a different origin than the " +
+          "document URL ({documentUrl}); refusing to return the object.  If " +
+          "you want to bypass this check and are aware of the security " +
+          'implications, set the crossOrigin option to "trust".',
+        { ...remoteDoc, objectId: object.id.href },
       );
+      return null;
     }
-    logger.warn(
-      "The object's @id ({objectId}) has a different origin than the document " +
-        "URL ({documentUrl}); refusing to return the object.  If you want to " +
-        "bypass this check and are aware of the security implications, " +
-        'set the crossOrigin option to "trust".',
-      { ...remoteDoc, objectId: object.id.href },
-    );
-    return null;
+    return object;
+  } finally {
+    snapshot?.release();
   }
-  return object;
 }
 
 const PORTABLE_IRI_PATTERN = /^ap(?:\+ef61)?:/i;
@@ -534,25 +569,9 @@ function parsePortableCandidate(iri: string): URL | null {
 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;
-  }
+): { readonly id: URL; readonly gateway: URL } | null | undefined {
+  if (options.verifyPortableObject == null) return undefined;
+  return parseCompatibleEf61Reference(href);
 }
 
 /**
@@ -629,15 +648,20 @@ async function dereference(
   { options, documentLoader }: PortableLookup,
   id: URL,
   gateways: readonly URL[],
+  extra: { response?: RemoteDocument; contextLoader?: DocumentLoader } = {},
 ): Promise<Object | null> {
   const tracerProvider = options.tracerProvider ?? trace.getTracerProvider();
   try {
     return await dereferencePortableIri(id, {
       documentLoader,
-      contextLoader: options.contextLoader ??
+      contextLoader: extra.contextLoader ?? options.contextLoader ??
         getDocumentLoader({ userAgent: options.userAgent }),
       tracerProvider,
-      gateways,
+      // Gateways are inferred from the identifier, WebFinger, or location
+      // hints, rather than given by the caller, so they are reported to the
+      // verifier as hints:
+      inferredGateways: gateways,
+      response: extra.response,
       verifyPortableObject: options.verifyPortableObject,
       crossOrigin: options.crossOrigin === "throw" ? "throw" : "ignore",
       signal: options.signal,
@@ -687,6 +711,31 @@ export interface TraverseCollectionOptions {
    * @default `{ seconds: 0 }`
    */
   interval?: Temporal.Duration | Temporal.DurationLike;
+  /**
+   * Whether to trust objects whose origin differs from the collection or page
+   * that refers to them.  See the `crossOrigin` option of property accessors
+   * such as `Collection.getItems()`.
+   * @since 2.4.0
+   */
+  crossOrigin?: "ignore" | "throw" | "trust";
+
+  /**
+   * The [FEP-ef61] gateways to fetch portable (`ap:`/`ap+ef61:`) pages and
+   * items through, in order.  See the `gateways` option of property
+   * accessors.
+   *
+   * [FEP-ef61]: https://w3id.org/fep/ef61
+   * @since 2.4.0
+   */
+  gateways?: readonly (string | URL)[];
+
+  /**
+   * The policy to apply to portable pages and items fetched through
+   * gateways, typically `verifyPortableObject()` from `@fedify/fedify`.
+   * Portable pages and items are not fetched without it.
+   * @since 2.4.0
+   */
+  verifyPortableObject?: PortableObjectVerifier;
 }
 
 /**

package/src/portable-lookup.test.ts

@@ -4,6 +4,7 @@ import {
   FetchError,
   parseIri,
   type PortableObjectVerifier,
+  type PortableObjectVerifierOptions,
   type RemoteDocument,
 } from "@fedify/vocab-runtime";
 import fetchMock from "fetch-mock";
@@ -455,3 +456,135 @@ test("getActorHandle() with FEP-ef61 portable actors", {
     fetchMock.hardReset();
   }
 });
+
+test("lookupObject() reports inferred gateways as hints", async () => {
+  const calls: PortableObjectVerifierOptions[] = [];
+  // deno-lint-ignore require-await
+  const verifyPortableObject: PortableObjectVerifier = async (_, options) => {
+    calls.push(options);
+    return { verified: true };
+  };
+  const actor = await lookupObject(compatibleId, {
+    documentLoader: createLoader({ [compatibleId]: person() }),
+    contextLoader: mockDocumentLoader,
+    verifyPortableObject,
+  });
+  assertInstanceOf(actor, Person);
+  deepStrictEqual(calls.length, 1);
+  deepStrictEqual(calls[0].gateways, undefined);
+  deepStrictEqual(calls[0].gatewayHints, [new URL("https://example.com")]);
+});
+
+test("lookupObject() verifies fetched documents that stand for portable objects", async (t) => {
+  const plainUrl = "https://example.com/users/alice";
+  const redirectingLoader = (
+    documentUrl: string,
+    document: Record<string, unknown>,
+  ): DocumentLoader & { readonly fetched: string[] } => {
+    const fetched: string[] = [];
+    // deno-lint-ignore require-await
+    const loader = async (url: string): Promise<RemoteDocument> => {
+      fetched.push(url);
+      if (url !== plainUrl) {
+        throw new FetchError(
+          url,
+          "HTTP 404",
+          new globalThis.Response(null, { status: 404 }),
+        );
+      }
+      return { contextUrl: null, documentUrl, document };
+    };
+    return Object.assign(loader, { fetched });
+  };
+
+  await t.step("a redirect to a compatible identifier", async () => {
+    const calls: PortableObjectVerifierOptions[] = [];
+    const documentLoader = redirectingLoader(compatibleId, person());
+    const actor = await lookupObject(plainUrl, {
+      documentLoader,
+      contextLoader: mockDocumentLoader,
+      // deno-lint-ignore require-await
+      verifyPortableObject: async (_, options) => {
+        calls.push(options);
+        return { verified: true };
+      },
+    });
+    assertInstanceOf(actor, Person);
+    deepStrictEqual(actor.id, parseIri(actorId));
+    // Verified in place, without another request:
+    deepStrictEqual(documentLoader.fetched, [plainUrl]);
+    deepStrictEqual(calls.length, 1);
+    deepStrictEqual(calls[0].documentUrl, new URL(compatibleId));
+    deepStrictEqual(calls[0].gatewayHints, [new URL("https://example.com")]);
+    equal(
+      await lookupObject(plainUrl, {
+        documentLoader,
+        contextLoader: mockDocumentLoader,
+        verifyPortableObject: createVerifier(false),
+      }),
+      null,
+    );
+    // A document that claims another object:
+    equal(
+      await lookupObject(plainUrl, {
+        documentLoader: redirectingLoader(
+          compatibleId,
+          person(`ap://${did}/other`),
+        ),
+        contextLoader: mockDocumentLoader,
+        verifyPortableObject: createVerifier(),
+      }),
+      null,
+    );
+  });
+
+  await t.step("a compatible @id", async () => {
+    const documentLoader = redirectingLoader(plainUrl, person(compatibleId));
+    const verifyPortableObject = createVerifier();
+    equal(
+      await lookupObject(plainUrl, {
+        documentLoader,
+        contextLoader: mockDocumentLoader,
+        verifyPortableObject,
+      }),
+      null,
+    );
+    deepStrictEqual(verifyPortableObject.documents, []);
+    // Without verifyPortableObject, it is fetched as before:
+    const actor = await lookupObject(plainUrl, {
+      documentLoader,
+      contextLoader: mockDocumentLoader,
+    });
+    assertInstanceOf(actor, Person);
+    deepStrictEqual(actor.id, new URL(compatibleId));
+  });
+
+  await t.step("a portable @id", async () => {
+    const documentLoader = redirectingLoader(plainUrl, person());
+    const actor = await lookupObject(plainUrl, {
+      documentLoader,
+      contextLoader: mockDocumentLoader,
+      verifyPortableObject: createVerifier(),
+    });
+    assertInstanceOf(actor, Person);
+    deepStrictEqual(actor.id, parseIri(actorId));
+    equal(
+      await lookupObject(plainUrl, {
+        documentLoader,
+        contextLoader: mockDocumentLoader,
+        verifyPortableObject: createVerifier(false),
+      }),
+      null,
+    );
+    await rejects(
+      () =>
+        lookupObject(plainUrl, {
+          documentLoader,
+          contextLoader: mockDocumentLoader,
+          verifyPortableObject: createVerifier(false),
+          crossOrigin: "throw",
+        }),
+      /No gateway returned a valid portable object/,
+    );
+  });
+});