@fedify/vocab 2.0.0-dev.0

package/src/lookup.ts

@@ -0,0 +1,318 @@
+import type { GetUserAgentOptions } from "@fedify/vocab-runtime";
+import {
+  type DocumentLoader,
+  getDocumentLoader,
+  type RemoteDocument,
+} from "@fedify/vocab-runtime";
+import { lookupWebFinger } from "@fedify/webfinger";
+import { getLogger } from "@logtape/logtape";
+import { SpanStatusCode, trace, type TracerProvider } from "@opentelemetry/api";
+import { delay } from "es-toolkit";
+import metadata from "../deno.json" with { type: "json" };
+import { toAcctUrl } from "./handle.ts";
+import { getTypeId } from "./type.ts";
+import { type Collection, type Link, Object } from "./vocab.ts";
+
+const logger = getLogger(["fedify", "vocab", "lookup"]);
+
+/**
+ * Options for the {@link lookupObject} function.
+ *
+ * @since 0.2.0
+ */
+export interface LookupObjectOptions {
+  /**
+   * The document loader for loading remote JSON-LD documents.
+   */
+  documentLoader?: DocumentLoader;
+
+  /**
+   * The context loader for loading remote JSON-LD contexts.
+   * @since 0.8.0
+   */
+  contextLoader?: DocumentLoader;
+
+  /**
+   * Whether to allow fetching an object with an `@id` having a different
+   * origin than the object's URL.  This is not recommended, as it may
+   * lead to security issues.  Only use this option if you know what you
+   * are doing.
+   *
+   * How to handle the case when an object's `@id` has a different origin
+   * than the object's URL:
+   *
+   *  -  `"ignore"` (default): Do not return the object, and log a warning.
+   *  -  `"throw"`: Throw an error.
+   *  -  `"trust"`: Bypass the check and return the object anyway.  This
+   *     is not recommended, as it may lead to security issues.  Only use
+   *     this option if you know what you are doing.
+   *
+   * @since 1.9.0
+   */
+  crossOrigin?: "ignore" | "throw" | "trust";
+
+  /**
+   * The options for making `User-Agent` header.
+   * If a string is given, it is used as the `User-Agent` header value.
+   * If an object is given, it is passed to {@link getUserAgent} to generate
+   * the `User-Agent` header value.
+   * @since 1.3.0
+   */
+  userAgent?: GetUserAgentOptions | string;
+
+  /**
+   * The OpenTelemetry tracer provider.  If omitted, the global tracer provider
+   * is used.
+   * @since 1.3.0
+   */
+  tracerProvider?: TracerProvider;
+
+  /**
+   * AbortSignal for cancelling the request.
+   * @since 1.8.0
+   */
+  signal?: AbortSignal;
+}
+
+/**
+ * Looks up an ActivityStreams object by its URI (including `acct:` URIs)
+ * or a fediverse handle (e.g., `@user@server` or `user@server`).
+ *
+ * @example
+ * ``` typescript
+ * // Look up an actor by its fediverse handle:
+ * await lookupObject("@hongminhee@fosstodon.org");
+ * // returning a `Person` object.
+ *
+ * // A fediverse handle can omit the leading '@':
+ * await lookupObject("hongminhee@fosstodon.org");
+ * // returning a `Person` object.
+ *
+ * // A `acct:` URI can be used as well:
+ * await lookupObject("acct:hongminhee@fosstodon.org");
+ * // returning a `Person` object.
+ *
+ * // Look up an object by its URI:
+ * await lookupObject("https://todon.eu/@hongminhee/112060633798771581");
+ * // returning a `Note` object.
+ *
+ * // It can be a `URL` object as well:
+ * await lookupObject(new URL("https://todon.eu/@hongminhee/112060633798771581"));
+ * // returning a `Note` object.
+ * ```
+ *
+ * @param identifier The URI or fediverse handle to look up.
+ * @param options Lookup options.
+ * @returns The object, or `null` if not found.
+ * @since 0.2.0
+ */
+export async function lookupObject(
+  identifier: string | URL,
+  options: LookupObjectOptions = {},
+): Promise<Object | null> {
+  const tracerProvider = options.tracerProvider ?? trace.getTracerProvider();
+  const tracer = tracerProvider.getTracer(
+    metadata.name,
+    metadata.version,
+  );
+  return await tracer.startActiveSpan(
+    "activitypub.lookup_object",
+    async (span) => {
+      try {
+        const result = await lookupObjectInternal(identifier, options);
+        if (result == null) span.setStatus({ code: SpanStatusCode.ERROR });
+        else {
+          if (result.id != null) {
+            span.setAttribute("activitypub.object.id", result.id.href);
+          }
+          span.setAttribute("activitypub.object.type", getTypeId(result).href);
+          if (result.replyTargetIds.length > 0) {
+            span.setAttribute(
+              "activitypub.object.in_reply_to",
+              result.replyTargetIds.map((id) => id.href),
+            );
+          }
+
+          // Record the fetched object details
+          span.addEvent("activitypub.object.fetched", {
+            "activitypub.object.type": getTypeId(result).href,
+            "activitypub.object.json": JSON.stringify(
+              await result.toJsonLd(options),
+            ),
+          });
+        }
+        return result;
+      } catch (error) {
+        span.recordException(error as Error);
+        span.setStatus({
+          code: SpanStatusCode.ERROR,
+          message: String(error),
+        });
+        throw error;
+      } finally {
+        span.end();
+      }
+    },
+  );
+}
+
+async function lookupObjectInternal(
+  identifier: string | URL,
+  options: LookupObjectOptions = {},
+): Promise<Object | null> {
+  const documentLoader = options.documentLoader ??
+    getDocumentLoader({ userAgent: options.userAgent });
+  if (typeof identifier === "string") {
+    identifier = toAcctUrl(identifier) ?? new URL(identifier);
+  }
+  let remoteDoc: RemoteDocument | null = null;
+  if (identifier.protocol === "http:" || identifier.protocol === "https:") {
+    try {
+      remoteDoc = await documentLoader(identifier.href, {
+        signal: options.signal,
+      });
+    } catch (error) {
+      logger.debug("Failed to fetch remote document:\n{error}", { error });
+    }
+  }
+  if (remoteDoc == null) {
+    const jrd = await lookupWebFinger(identifier, {
+      userAgent: options.userAgent,
+      tracerProvider: options.tracerProvider,
+      allowPrivateAddress: "allowPrivateAddress" in options &&
+        options.allowPrivateAddress === true,
+      signal: options.signal,
+    });
+    if (jrd?.links == null) return null;
+    for (const l of jrd.links) {
+      if (
+        l.type !== "application/activity+json" &&
+          !l.type?.match(
+            /application\/ld\+json;\s*profile="https:\/\/www.w3.org\/ns\/activitystreams"/,
+          ) || l.rel !== "self" || l.href == null
+      ) continue;
+      try {
+        remoteDoc = await documentLoader(l.href, {
+          signal: options.signal,
+        });
+        break;
+      } catch (error) {
+        logger.debug("Failed to fetch remote document:\n{error}", { error });
+        continue;
+      }
+    }
+  }
+  if (remoteDoc == null) return null;
+  let object: Object;
+  try {
+    object = await Object.fromJsonLd(remoteDoc.document, {
+      documentLoader,
+      contextLoader: options.contextLoader,
+      tracerProvider: options.tracerProvider,
+      baseUrl: new URL(remoteDoc.documentUrl),
+    });
+  } catch (error) {
+    if (error instanceof TypeError) {
+      logger.debug(
+        "Failed to parse JSON-LD document: {error}\n{document}",
+        { ...remoteDoc, error },
+      );
+      return null;
+    }
+    throw error;
+  }
+  if (
+    options.crossOrigin !== "trust" && object.id != null &&
+    object.id.origin !== new URL(remoteDoc.documentUrl).origin
+  ) {
+    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;
+  }
+  return object;
+}
+
+/**
+ * Options for the {@link traverseCollection} function.
+ * @since 1.1.0
+ */
+export interface TraverseCollectionOptions {
+  /**
+   * The document loader for loading remote JSON-LD documents.
+   */
+  documentLoader?: DocumentLoader;
+
+  /**
+   * The context loader for loading remote JSON-LD contexts.
+   */
+  contextLoader?: DocumentLoader;
+
+  /**
+   * Whether to suppress errors when fetching pages.  If `true`,
+   * errors will be logged but not thrown.  Defaults to `false`.
+   */
+  suppressError?: boolean;
+
+  /**
+   * The interval to wait between fetching pages.  Zero or negative
+   * values will disable the interval.  Disabled by default.
+   *
+   * @default `{ seconds: 0 }`
+   */
+  interval?: Temporal.Duration | Temporal.DurationLike;
+}
+
+/**
+ * Traverses a collection, yielding each item in the collection.
+ * If the collection is paginated, it will fetch the next page
+ * automatically.
+ *
+ * @example
+ * ``` typescript
+ * const collection = await lookupObject(collectionUrl);
+ * if (collection instanceof Collection) {
+ *   for await (const item of traverseCollection(collection)) {
+ *     console.log(item.id?.href);
+ *   }
+ * }
+ * ```
+ *
+ * @param collection The collection to traverse.
+ * @param options Options for traversing the collection.
+ * @returns An async iterable of each item in the collection.
+ * @since 1.1.0
+ */
+export async function* traverseCollection(
+  collection: Collection,
+  options: TraverseCollectionOptions = {},
+): AsyncIterable<Object | Link> {
+  if (collection.firstId == null) {
+    for await (const item of collection.getItems(options)) {
+      yield item;
+    }
+  } else {
+    const interval = Temporal.Duration.from(options.interval ?? { seconds: 0 })
+      .total("millisecond");
+    let page = await collection.getFirst(options);
+    while (page != null) {
+      for await (const item of page.getItems(options)) {
+        yield item;
+      }
+      if (interval > 0) await delay(interval);
+      page = await page.getNext(options);
+    }
+  }
+}

package/src/mention.yaml

@@ -0,0 +1,9 @@
+$schema: ../../vocab-tools/schema.yaml
+name: Mention
+compactName: Mention
+uri: "https://www.w3.org/ns/activitystreams#Mention"
+extends: "https://www.w3.org/ns/activitystreams#Link"
+entity: false
+description:  A specialized {@link Link} that represents an @mention.
+defaultContext: "https://www.w3.org/ns/activitystreams"
+properties: []

package/src/mod.ts

@@ -0,0 +1,57 @@
+/**
+ * A set of type-safe object mappings for the [Activity
+ * Vocabulary](https://www.w3.org/TR/activitystreams-vocabulary/).
+ *
+ * Each class in this module represents a type of object in the Activity
+ * Vocabulary.  For example, the {@link Note} class represents the
+ * [`Note` type](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-note)
+ * in the Activity Vocabulary.
+ *
+ * There are two ways to instantiate an object of a class in this module.
+ * The first way is to use the constructor of the class.  For example:
+ *
+ * ``` typescript
+ * const note = new Note({
+ *   attributedTo: new URL("https://example.com/user"),
+ *   content: "Hello, world!",
+ * });
+ * const create = new Create({
+ *   actor: new URL("https://example.com/user"),
+ *   object: note,
+ * });
+ * ```
+ *
+ * The second way is to deserialize an object from a JSON-LD document using
+ * the `fromJsonLd()` method of the class.  For example:
+ *
+ * ``` typescript
+ * const create = await Create.fromJsonLd({
+ *   "@context": "https://www.w3.org/ns/activitystreams",
+ *   "type": "Create",
+ *   "actor": "https://example.com/user",
+ *   "object": {
+ *     "type": "Note",
+ *     "attributedTo": "https://example.com/user",
+ *     "content": "Hello, world!",
+ *   },
+ * });
+ * ```
+ *
+ * In order to serialize an object to a JSON-LD document, use the `toJsonLd()`
+ * method of the object.  For example:
+ *
+ * ``` typescript
+ * const jsonLd = await create.toJsonLd();
+ * ```
+ *
+ * Note that both `fromJsonLd()` and `toJsonLd()` are asynchronous methods
+ * that return a `Promise`.
+ *
+ * @module
+ */
+export * from "./actor.ts";
+export * from "./constants.ts";
+export * from "./handle.ts";
+export * from "./lookup.ts";
+export * from "./type.ts";
+export * from "./vocab.ts";

package/src/move.yaml

@@ -0,0 +1,15 @@
+$schema: ../../vocab-tools/schema.yaml
+name: Move
+compactName: Move
+uri: "https://www.w3.org/ns/activitystreams#Move"
+extends: "https://www.w3.org/ns/activitystreams#Activity"
+entity: true
+description: |
+  Indicates that the `actor` has moved `object` from `origin` to `target`.
+  If the `origin` or `target` are not specified,
+  either can be determined by context.
+defaultContext:
+- "https://w3id.org/identity/v1"
+- "https://www.w3.org/ns/activitystreams"
+- "https://w3id.org/security/data-integrity/v1"
+properties: []

package/src/multikey.yaml

@@ -0,0 +1,36 @@
+$schema: ../../vocab-tools/schema.yaml
+name: Multikey
+compactName: Multikey
+uri: "https://w3id.org/security#Multikey"
+entity: true
+description: |
+  Represents a key owned by an actor according to [FEP-521a: Representing
+  actor's public keys.][1]
+
+  [1]: https://w3id.org/fep/521a
+defaultContext: "https://w3id.org/security/multikey/v1"
+
+properties:
+- singularName: controller
+  functional: true
+  compactName: controller
+  uri: "https://w3id.org/security#controller"
+  description: An actor who owns this key.
+  range:
+  - "https://www.w3.org/ns/activitystreams#Application"
+  - "https://www.w3.org/ns/activitystreams#Group"
+  - "https://www.w3.org/ns/activitystreams#Organization"
+  - "https://www.w3.org/ns/activitystreams#Person"
+  - "https://www.w3.org/ns/activitystreams#Service"
+
+- singularName: publicKey
+  functional: true
+  compactName: publicKeyMultibase
+  uri: "https://w3id.org/security#publicKeyMultibase"
+  description: |
+    A [Multibase]-encoded value of a [Multicodec] prefix and the key.
+
+    [Multibase]: https://www.w3.org/TR/vc-data-integrity/#multibase-0
+    [Multicodec]: https://github.com/multiformats/multicodec/
+  range:
+  - "fedify:multibaseKey"

package/src/note.yaml

@@ -0,0 +1,48 @@
+$schema: ../../vocab-tools/schema.yaml
+name: Note
+compactName: Note
+uri: "https://www.w3.org/ns/activitystreams#Note"
+extends: "https://www.w3.org/ns/activitystreams#Object"
+entity: true
+description: |
+  Represents a short written work typically less than a single paragraph in
+  length.
+defaultContext:
+- "https://www.w3.org/ns/activitystreams"
+- "https://w3id.org/security/data-integrity/v1"
+- toot: "http://joinmastodon.org/ns#"
+  misskey: "https://misskey-hub.net/ns#"
+  fedibird: "http://fedibird.com/ns#"
+  sensitive: "as:sensitive"
+  Emoji: "toot:Emoji"
+  Hashtag: "as:Hashtag"
+  quoteUrl: "as:quoteUrl"
+  _misskey_quote: "misskey:_misskey_quote"
+  quoteUri: "fedibird:quoteUri"
+  emojiReactions:
+    "@id": "fedibird:emojiReactions"
+    "@type": "@id"
+
+properties:
+- singularName: quoteUrl
+  functional: true
+  compactName: quoteUrl
+  uri: "https://www.w3.org/ns/activitystreams#quoteUrl"
+  redundantProperties:
+  - compactName: _misskey_quote
+    uri: "https://misskey-hub.net/ns#_misskey_quote"
+  - compactName: quoteUri
+    uri: "http://fedibird.com/ns#quoteUri"
+  description: |
+    The URI of the ActivityStreams object that this object quotes.
+
+    This property sets three JSON-LD properties at once under the hood:
+
+    1. https://www.w3.org/ns/activitystreams#quoteUrl
+    2. https://misskey-hub.net/ns#_misskey_quote
+    3. http://fedibird.com/ns#quoteUri
+
+    When a JSON-LD object is parsed, this property is filled with one of
+    the values of those three properties in order.
+  range:
+  - "fedify:url"