@fedify/vocab-runtime 2.4.0-dev.2056 → 2.4.0-dev.2063

package/src/internal/portable-dereference.ts

@@ -7,10 +7,15 @@ import {
 import preloadedContexts from "../contexts.ts";
 import type { DocumentLoader, RemoteDocument } from "../docloader.ts";
 import jsonld from "../jsonld.ts";
-import type { PortableObjectVerifier } from "../portable.ts";
+import type {
+  PortableObjectReferrer,
+  PortableObjectVerification,
+  PortableObjectVerifier,
+} from "../portable.ts";
 import {
   canonicalizePortableUri,
   formatIri,
+  fromCompatibleEf61Id,
   parseIri,
   toCompatibleEf61Id,
 } from "../url.ts";
@@ -38,6 +43,225 @@ const BASELINE_CONTEXT_URLS: ReadonlySet<string> = new Set([
   "https://w3id.org/security/data-integrity/v1",
 ]);
 
+/**
+ * The maximum number of links in a referrer chain passed to a
+ * {@link PortableObjectVerifier}.  Longer chains are cut off and marked as
+ * truncated.
+ */
+const MAX_REFERRER_CHAIN_LENGTH = 32;
+
+/**
+ * Where a vocabulary object came from, as far as portable objects are
+ * concerned.
+ */
+interface Provenance {
+  /**
+   * How the object was accepted by a portable object verifier, if it was
+   * returned by {@link dereferencePortableIri}.
+   */
+  readonly acceptance?: "verified" | "unsecured";
+
+  /**
+   * The opaque collection context that the verifier attached to the object.
+   */
+  readonly collectionContext?: unknown;
+
+  /**
+   * The object and property through which the object was obtained.
+   */
+  readonly referrer?: { readonly object: object; readonly property: string };
+}
+
+// Kept outside the objects so that they cannot be forged through vocabulary
+// constructors or JSON-LD, and so that they do not show up in serialization:
+const provenances = new WeakMap<object, Provenance>();
+
+/**
+ * A reference from a vocabulary object's property, which generated
+ * accessors pass to {@link dereferencePortableIri}.
+ *
+ * @internal
+ */
+export interface PortableReferrerLink {
+  readonly object: object;
+  readonly property: string;
+}
+
+function getObjectId(object: unknown): URL | null {
+  if (object == null || typeof object !== "object" || !("id" in object)) {
+    return null;
+  }
+  const id = object.id;
+  return id instanceof URL ? id : null;
+}
+
+/**
+ * Checks whether a vocabulary object is part of a chain of portable objects,
+ * i.e., whether it has a portable ID or was obtained from a portable object.
+ *
+ * @internal Technically exported for generated vocabulary classes, but not
+ * part of the public API contract.  This is not considered public API for
+ * Semantic Versioning decisions.
+ */
+export function isInPortableChain(object: object): boolean {
+  if (provenances.has(object)) return true;
+  const id = getObjectId(object);
+  return id != null && isPortableIri(id);
+}
+
+/**
+ * Checks whether a vocabulary object was accepted without an integrity
+ * proof, e.g., as an unsecured portable collection served by a trusted
+ * gateway.  Objects embedded in such an object must not be trusted because
+ * of their origin.
+ *
+ * @internal Technically exported for generated vocabulary classes, but not
+ * part of the public API contract.  This is not considered public API for
+ * Semantic Versioning decisions.
+ */
+export function isUnsecuredPortableObject(object: object): boolean {
+  return provenances.get(object)?.acceptance === "unsecured";
+}
+
+/**
+ * Checks whether a URL is an FEP-ef61 compatible identifier, i.e., an HTTP(S)
+ * URL under a gateway's `/.well-known/apgateway/` path that stands for
+ * a portable object.  Malformed compatible identifiers count as compatible
+ * identifiers too.
+ *
+ * @internal Technically exported for generated vocabulary classes, but not
+ * part of the public API contract.  This is not considered public API for
+ * Semantic Versioning decisions.
+ */
+export function isCompatibleEf61Iri(url: URL | string): boolean {
+  try {
+    return fromCompatibleEf61Id(url) != null;
+  } catch (error) {
+    if (error instanceof TypeError) return true;
+    throw error;
+  }
+}
+
+/**
+ * Records that a vocabulary object returned by a property accessor was
+ * obtained through the given property of a portable object, so that later
+ * dereferences from it can tell where it came from.  Nothing is recorded if
+ * the parent is not in a portable chain, or if the child already has its
+ * provenance.
+ *
+ * @internal Technically exported for generated vocabulary classes, but not
+ * part of the public API contract.  This is not considered public API for
+ * Semantic Versioning decisions.
+ */
+export function recordPortableReferrer(
+  parent: object,
+  child: unknown,
+  property: string,
+): void {
+  if (child == null || typeof child !== "object") return;
+  if (provenances.has(child) || !isInPortableChain(parent)) return;
+  provenances.set(child, { referrer: { object: parent, property } });
+}
+
+/**
+ * Copies the provenance of a vocabulary object to its clone.  The clone
+ * keeps where the original came from and the restriction on unsecured
+ * objects, but not a positive verification status nor a collection context,
+ * since the clone may have different property values.
+ *
+ * @internal Technically exported for generated vocabulary classes, but not
+ * part of the public API contract.  This is not considered public API for
+ * Semantic Versioning decisions.
+ */
+export function copyPortableProvenance(from: object, to: object): void {
+  const provenance = provenances.get(from);
+  if (provenance == null) return;
+  provenances.set(to, {
+    referrer: provenance.referrer,
+    ...(provenance.acceptance === "unsecured"
+      ? { acceptance: "unsecured" }
+      : {}),
+  });
+}
+
+/**
+ * Rejects a reference from a portable object that would be dereferenced as
+ * an ordinary HTTP(S) object although it stands for a portable object, i.e.,
+ * an FEP-ef61 compatible identifier, or a document whose final URL or `@id`
+ * is a compatible identifier or a portable IRI.  Such a document would skip
+ * the portable object policy, so it is rejected regardless of the
+ * `crossOrigin` option, except that `crossOrigin: "throw"` makes it throw.
+ *
+ * @param url The rejected URL, for the log message.
+ * @param crossOrigin The `crossOrigin` option of the accessor.
+ * @returns Always `null`.
+ * @throws {Error} If `crossOrigin` is `"throw"`.
+ * @internal Technically exported for generated vocabulary classes, but not
+ * part of the public API contract.  This is not considered public API for
+ * Semantic Versioning decisions.
+ */
+export function rejectPortableChainReference(
+  url: string,
+  crossOrigin: "ignore" | "throw" | "trust" | undefined,
+): null {
+  const message = "Refusing to dereference {url} from a portable object as " +
+    "an ordinary HTTP(S) object, because it stands for an FEP-ef61 portable " +
+    "object that is not verified this way.";
+  if (crossOrigin === "throw") {
+    throw new Error(message.replace("{url}", url));
+  }
+  logger.warn(message, { url });
+  return null;
+}
+
+/**
+ * Logs that an embedded object without `@id` in an object accepted without
+ * an integrity proof is dropped, because it cannot be dereferenced and
+ * verified on its own.
+ *
+ * @internal Technically exported for generated vocabulary classes, but not
+ * part of the public API contract.  This is not considered public API for
+ * Semantic Versioning decisions.
+ */
+export function warnUnverifiableEmbeddedObject(
+  parent: object,
+  property: string,
+): void {
+  logger.warn(
+    "Dropping an embedded object without @id in the {property} property of " +
+      "{parentId}, because the parent was accepted without an integrity " +
+      "proof and the embedded object cannot be verified on its own.",
+    { property, parentId: getObjectId(parent)?.href ?? null },
+  );
+}
+
+function buildReferrerChain(
+  link: PortableReferrerLink | undefined,
+  depth = 0,
+): PortableObjectReferrer | undefined {
+  if (link == null) return undefined;
+  const provenance = provenances.get(link.object);
+  const base = {
+    object: link.object,
+    id: getObjectId(link.object),
+    property: link.property,
+    ...(provenance?.acceptance == null
+      ? {}
+      : { acceptance: provenance.acceptance }),
+    ...(provenance?.collectionContext === undefined
+      ? {}
+      : { collectionContext: provenance.collectionContext }),
+  };
+  if (provenance?.referrer == null) return base;
+  if (depth + 1 >= MAX_REFERRER_CHAIN_LENGTH) {
+    return { ...base, truncated: true };
+  }
+  return {
+    ...base,
+    referrer: buildReferrerChain(provenance.referrer, depth + 1),
+  };
+}
+
 /**
  * Checks whether a URL is an FEP-ef61 portable ActivityPub IRI.
  *
@@ -179,6 +403,7 @@ export interface DereferencePortableIriOptions<T> {
   tracerProvider: TracerProvider;
   gateways?: readonly (string | URL)[];
   verifyPortableObject?: PortableObjectVerifier;
+  referrer?: PortableReferrerLink;
   suppressError?: boolean;
   crossOrigin?: "ignore" | "throw" | "trust";
   /**
@@ -287,6 +512,11 @@ export async function dereferencePortableIri<T extends { id: URL | null }>(
   const contextLoader = snapshot.loader;
   const attempts: Attempt[] = [];
   const { signal } = options;
+  const explicitGateways = options.gateways == null ? undefined : gateways;
+  const gatewayHints = options.gateways == null && gateways.length > 0
+    ? gateways
+    : undefined;
+  const referrer = buildReferrerChain(options.referrer);
   try {
     for (const { url: requestUrl, gateway } of requestUrls) {
       signal?.throwIfAborted();
@@ -309,12 +539,22 @@ export async function dereferencePortableIri<T extends { id: URL | null }>(
       const { document } = remoteDocument;
       try {
         await checkPortableObjectId(document, expectedId, contextLoader);
-        let result: { readonly verified: boolean };
+        let documentUrl: URL | undefined;
+        try {
+          documentUrl = parseIri(remoteDocument.documentUrl);
+        } catch {
+          documentUrl = undefined;
+        }
+        let result: PortableObjectVerification;
         try {
           result = await verify(document, {
             documentLoader: options.documentLoader,
             contextLoader,
             tracerProvider: options.tracerProvider,
+            ...(documentUrl == null ? {} : { documentUrl }),
+            ...(explicitGateways == null ? {} : { gateways: explicitGateways }),
+            ...(gatewayHints == null ? {} : { gatewayHints }),
+            ...(referrer == null ? {} : { referrer }),
           });
         } catch (error) {
           throw new PortableObjectRejection(
@@ -333,6 +573,15 @@ export async function dereferencePortableIri<T extends { id: URL | null }>(
           baseUrl: url,
         });
         signal?.throwIfAborted();
+        if (object != null && typeof object === "object") {
+          provenances.set(object, {
+            acceptance: result.unsecured === true ? "unsecured" : "verified",
+            ...(result.collectionContext === undefined
+              ? {}
+              : { collectionContext: result.collectionContext }),
+            ...(options.referrer == null ? {} : { referrer: options.referrer }),
+          });
+        }
         if (gateway != null) {
           span?.setAttribute("activitypub.gateway", gateway.href);
         }

package/src/mod.ts

@@ -46,6 +46,8 @@ export {
 } from "./digest.ts";
 export { LanguageString } from "./langstr.ts";
 export type {
+  PortableObjectReferrer,
+  PortableObjectVerification,
   PortableObjectVerifier,
   PortableObjectVerifierOptions,
 } from "./portable.ts";

package/src/portable.ts

@@ -23,30 +23,154 @@ export interface PortableObjectVerifierOptions {
    * 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 taken from the `@gateway` location hints of the reference,
+   * in order, when the caller did not pass the `gateways` option.
+   * @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;
 }
 
 /**
- * A function that applies the [FEP-ef61] proof policy to a portable object
+ * 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 carries a valid
- * [FEP-8b32] Object Integrity Proof made by the DID in its portable ID.
- * `verifyPortableObjectProof()` from `@fedify/fedify` satisfies this type, so
- * it can be passed as the `verifyPortableObject` option of generated
+ * 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 and tracing options for verification.
+ * @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 proof policy.  Other properties, such as
+ *          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<{ readonly verified: boolean }>;
+) => Promise<PortableObjectVerification>;

package/dist/portable-CduElToy.d.ts

@@ -1,52 +0,0 @@
-/// <reference lib="esnext.temporal" />
-import { n as DocumentLoader } from "./docloader-Dr8wEkif.js";
-import { TracerProvider } from "@opentelemetry/api";
-
-//#region src/portable.d.ts
-/**
-* Options passed to a {@link PortableObjectVerifier}.
-* @since 2.4.0
-*/
-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;
-}
-/**
-* A function that applies the [FEP-ef61] proof 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 carries a valid
-* [FEP-8b32] Object Integrity Proof made by the DID in its portable ID.
-* `verifyPortableObjectProof()` from `@fedify/fedify` satisfies this type, so
-* it 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 and tracing options for verification.
-* @returns An object whose `verified` property is `true` if and only if the
-*          document satisfies the proof policy.  Other properties, such as
-*          a failure reason, are logged when verification fails.
-* @since 2.4.0
-*/
-type PortableObjectVerifier = (document: unknown, options: PortableObjectVerifierOptions) => Promise<{
-  readonly verified: boolean;
-}>;
-//#endregion
-export { PortableObjectVerifierOptions as n, PortableObjectVerifier as t };

package/dist/portable-DxF2Ut-Z.d.cts

@@ -1,52 +0,0 @@
-/// <reference lib="esnext.temporal" />
-import { n as DocumentLoader } from "./docloader-Dr8wEkif.cjs";
-import { TracerProvider } from "@opentelemetry/api";
-
-//#region src/portable.d.ts
-/**
-* Options passed to a {@link PortableObjectVerifier}.
-* @since 2.4.0
-*/
-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;
-}
-/**
-* A function that applies the [FEP-ef61] proof 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 carries a valid
-* [FEP-8b32] Object Integrity Proof made by the DID in its portable ID.
-* `verifyPortableObjectProof()` from `@fedify/fedify` satisfies this type, so
-* it 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 and tracing options for verification.
-* @returns An object whose `verified` property is `true` if and only if the
-*          document satisfies the proof policy.  Other properties, such as
-*          a failure reason, are logged when verification fails.
-* @since 2.4.0
-*/
-type PortableObjectVerifier = (document: unknown, options: PortableObjectVerifierOptions) => Promise<{
-  readonly verified: boolean;
-}>;
-//#endregion
-export { PortableObjectVerifierOptions as n, PortableObjectVerifier as t };