@fedify/vocab 2.0.0-dev.0

package/src/accept.yaml

@@ -0,0 +1,15 @@
+$schema: ../../vocab-tools/schema.yaml
+name: Accept
+compactName: Accept
+uri: "https://www.w3.org/ns/activitystreams#Accept"
+extends: "https://www.w3.org/ns/activitystreams#Activity"
+entity: true
+description: |
+  Indicates that the `actor` accepts the `object`.  The `target` property can be
+  used in certain circumstances to indicate the context into which the `object`
+  has been accepted.
+defaultContext:
+- "https://w3id.org/identity/v1"
+- "https://www.w3.org/ns/activitystreams"
+- "https://w3id.org/security/data-integrity/v1"
+properties: []

package/src/activity.yaml

@@ -0,0 +1,98 @@
+$schema: ../../vocab-tools/schema.yaml
+name: Activity
+compactName: Activity
+uri: "https://www.w3.org/ns/activitystreams#Activity"
+extends: "https://www.w3.org/ns/activitystreams#Object"
+entity: true
+description: |
+  An Activity is a subtype of {@link Object} that describes some form of action
+  that may happen, is currently happening, or has already happened.
+  The {@link Activity} type itself serves as an abstract base type for all types
+  of activities.  It is important to note that the {@link Activity} type itself
+  does not carry any specific semantics about the kind of action being taken.
+defaultContext:
+- "https://w3id.org/identity/v1"
+- "https://www.w3.org/ns/activitystreams"
+- "https://w3id.org/security/v1"
+- "https://w3id.org/security/data-integrity/v1"
+
+properties:
+- pluralName: actors
+  singularName: actor
+  singularAccessor: true
+  compactName: actor
+  uri: "https://www.w3.org/ns/activitystreams#actor"
+  subpropertyOf: "https://www.w3.org/ns/activitystreams#attributedTo"
+  description: |
+    Describes one or more entities that either performed or are expected to
+    perform the activity.  Any single activity can have multiple actors.
+    The actor MAY be specified using an indirect {@link Link}.
+  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"
+
+- pluralName: objects
+  singularName: object
+  singularAccessor: true
+  compactName: object
+  uri: "https://www.w3.org/ns/activitystreams#object"
+  description: |
+    When used within an {@link Activity}, describes the direct object of
+    the activity.  For instance, in the activity "John added a movie to his
+    wishlist", the object of the activity is the movie added.
+  range:
+  - "https://www.w3.org/ns/activitystreams#Object"
+
+- pluralName: targets
+  singularName: target
+  singularAccessor: true
+  compactName: target
+  uri: "https://www.w3.org/ns/activitystreams#target"
+  description: |
+    Describes the indirect object, or target, of the activity.  The precise
+    meaning of the target is largely dependent on the type of action being
+    described but will often be the object of the English preposition "to".
+    For instance, in the activity "John added a movie to his wishlist",
+    the target of the activity is John's wishlist.  An activity can have more
+    than one target. 
+  range:
+  - "https://www.w3.org/ns/activitystreams#Object"
+
+- pluralName: results
+  singularName: result
+  singularAccessor: true
+  compactName: result
+  uri: "https://www.w3.org/ns/activitystreams#result"
+  description: |
+    Describes the result of the activity.  For instance, if a particular action
+    results in the creation of a new resource, the result property can be used
+    to describe that new resource. 
+  range:
+  - "https://www.w3.org/ns/activitystreams#Object"
+
+- pluralName: origins
+  singularName: origin
+  singularAccessor: true
+  compactName: origin
+  uri: "https://www.w3.org/ns/activitystreams#origin"
+  description: |
+    Describes an indirect object of the activity from which the activity is
+    directed.  The precise meaning of the origin is the object of the English
+    preposition "from". For instance, in the activity "John moved an item to
+    List B from List A", the origin of the activity is "List A".
+  range:
+  - "https://www.w3.org/ns/activitystreams#Object"
+
+- pluralName: instruments
+  singularName: instrument
+  singularAccessor: true
+  compactName: instrument
+  uri: "https://www.w3.org/ns/activitystreams#instrument"
+  description: |
+    Identifies one or more objects used (or to be used) in the completion of
+    an {@link Activity}.
+  range:
+  - "https://www.w3.org/ns/activitystreams#Object"

package/src/actor.test.ts

@@ -0,0 +1,263 @@
+import { test } from "@fedify/fixture";
+import * as fc from "fast-check";
+import fetchMock from "fetch-mock";
+import {
+  deepStrictEqual,
+  ok,
+  rejects,
+  strictEqual,
+  throws,
+} from "node:assert/strict";
+import {
+  type Actor,
+  getActorClassByTypeName,
+  getActorHandle,
+  getActorTypeName,
+  isActor,
+  normalizeActorHandle,
+} from "./actor.ts";
+import { Application, Group, Organization, Person, Service } from "./vocab.ts";
+
+function actorClass(): fc.Arbitrary<
+  | typeof Application
+  | typeof Group
+  | typeof Organization
+  | typeof Person
+  | typeof Service
+> {
+  return fc.constantFrom(Application, Group, Organization, Person, Service);
+}
+
+function actorClassAndInstance(): fc.Arbitrary<
+  | [typeof Application, Application]
+  | [typeof Group, Group]
+  | [typeof Organization, Organization]
+  | [typeof Person, Person]
+  | [typeof Service, Service]
+> {
+  return actorClass().map((cls) =>
+    [cls, new cls({})] as (
+      | [typeof Application, Application]
+      | [typeof Group, Group]
+      | [typeof Organization, Organization]
+      | [typeof Person, Person]
+      | [typeof Service, Service]
+    )
+  );
+}
+
+function actor(): fc.Arbitrary<Actor> {
+  return actorClassAndInstance().map(([, instance]) => instance);
+}
+
+test("isActor()", () => {
+  fc.assert(fc.property(actor(), (actor) => ok(isActor(actor))));
+  fc.assert(
+    fc.property(
+      fc.anything({
+        withBigInt: true,
+        withBoxedValues: true,
+        withDate: true,
+        withMap: true,
+        withNullPrototype: true,
+        withObjectString: true,
+        withSet: true,
+        withTypedArray: true,
+        withSparseArray: true,
+      }),
+      (nonActor) => ok(!isActor(nonActor)),
+    ),
+  );
+});
+
+test("getActorTypeName()", () => {
+  fc.assert(
+    fc.property(
+      actorClassAndInstance(),
+      ([cls, instance]) =>
+        deepStrictEqual(getActorTypeName(instance), cls.name),
+    ),
+  );
+});
+
+test("getActorClassByTypeName()", () => {
+  fc.assert(
+    fc.property(
+      actorClassAndInstance(),
+      ([cls, instance]) =>
+        strictEqual(
+          getActorClassByTypeName(getActorTypeName(instance)),
+          cls,
+        ),
+    ),
+  );
+});
+
+test({
+  name: "getActorHandle()",
+  permissions: { env: true, read: true },
+  async fn(t) {
+    fetchMock.spyGlobal();
+
+    fetchMock.get(
+      "begin:https://foo.example.com/.well-known/webfinger?",
+      {
+        body: { subject: "acct:johndoe@foo.example.com" },
+        headers: { "Content-Type": "application/jrd+json" },
+      },
+    );
+
+    const actorId = new URL("https://foo.example.com/@john");
+    const actor = new Person({
+      id: actorId,
+      preferredUsername: "john",
+    });
+
+    await t.step("WebFinger subject", async () => {
+      deepStrictEqual(await getActorHandle(actor), "@johndoe@foo.example.com");
+      deepStrictEqual(
+        await getActorHandle(actor, { trimLeadingAt: true }),
+        "johndoe@foo.example.com",
+      );
+      deepStrictEqual(
+        await getActorHandle(actorId),
+        "@johndoe@foo.example.com",
+      );
+      deepStrictEqual(
+        await getActorHandle(actorId, { trimLeadingAt: true }),
+        "johndoe@foo.example.com",
+      );
+    });
+
+    fetchMock.removeRoutes();
+    fetchMock.get(
+      "begin:https://foo.example.com/.well-known/webfinger?",
+      {
+        body: {
+          subject: "https://foo.example.com/@john",
+          aliases: [
+            "acct:john@bar.example.com",
+            "acct:johndoe@foo.example.com",
+          ],
+        },
+        headers: { "Content-Type": "application/jrd+json" },
+      },
+    );
+
+    await t.step("WebFinger aliases", async () => {
+      deepStrictEqual(await getActorHandle(actor), "@johndoe@foo.example.com");
+      deepStrictEqual(
+        await getActorHandle(actor, { trimLeadingAt: true }),
+        "johndoe@foo.example.com",
+      );
+      deepStrictEqual(
+        await getActorHandle(actorId),
+        "@johndoe@foo.example.com",
+      );
+      deepStrictEqual(
+        await getActorHandle(actorId, { trimLeadingAt: true }),
+        "johndoe@foo.example.com",
+      );
+    });
+
+    fetchMock.get(
+      "begin:https://bar.example.com/.well-known/webfinger?",
+      {
+        body: {
+          subject: "acct:john@bar.example.com",
+          aliases: [
+            "https://foo.example.com/@john",
+          ],
+        },
+        headers: { "Content-Type": "application/jrd+json" },
+      },
+    );
+
+    await t.step("cross-origin WebFinger resources", async () => {
+      deepStrictEqual(await getActorHandle(actor), "@john@bar.example.com");
+    });
+
+    fetchMock.removeRoutes();
+    fetchMock.get(
+      "begin:https://foo.example.com/.well-known/webfinger?",
+      { status: 404 },
+    );
+
+    await t.step("no WebFinger", async () => {
+      deepStrictEqual(await getActorHandle(actor), "@john@foo.example.com");
+      rejects(() => getActorHandle(actorId), TypeError);
+    });
+
+    fetchMock.hardReset();
+  },
+});
+
+test("normalizeActorHandle()", () => {
+  deepStrictEqual(normalizeActorHandle("@foo@BAR.COM"), "@foo@bar.com");
+  deepStrictEqual(normalizeActorHandle("@BAZ@☃-⌘.com"), "@BAZ@☃-⌘.com");
+  deepStrictEqual(
+    normalizeActorHandle("@qux@xn--maana-pta.com"),
+    "@qux@mañana.com",
+  );
+  deepStrictEqual(
+    normalizeActorHandle("@quux@XN--MAANA-PTA.COM"),
+    "@quux@mañana.com",
+  );
+  deepStrictEqual(
+    normalizeActorHandle("@quux@MAÑANA.COM"),
+    "@quux@mañana.com",
+  );
+
+  deepStrictEqual(
+    normalizeActorHandle("@foo@BAR.COM", { trimLeadingAt: true }),
+    "foo@bar.com",
+  );
+  deepStrictEqual(
+    normalizeActorHandle("@BAZ@☃-⌘.com", { trimLeadingAt: true }),
+    "BAZ@☃-⌘.com",
+  );
+  deepStrictEqual(
+    normalizeActorHandle("@qux@xn--maana-pta.com", { trimLeadingAt: true }),
+    "qux@mañana.com",
+  );
+  deepStrictEqual(
+    normalizeActorHandle("@quux@XN--MAANA-PTA.COM", { trimLeadingAt: true }),
+    "quux@mañana.com",
+  );
+  deepStrictEqual(
+    normalizeActorHandle("@quux@MAÑANA.COM", { trimLeadingAt: true }),
+    "quux@mañana.com",
+  );
+
+  deepStrictEqual(
+    normalizeActorHandle("@foo@BAR.COM", { punycode: true }),
+    "@foo@bar.com",
+  );
+  deepStrictEqual(
+    normalizeActorHandle("@BAZ@☃-⌘.com", { punycode: true }),
+    "@BAZ@xn----dqo34k.com",
+  );
+  deepStrictEqual(
+    normalizeActorHandle("@qux@xn--maana-pta.com", { punycode: true }),
+    "@qux@xn--maana-pta.com",
+  );
+  deepStrictEqual(
+    normalizeActorHandle("@quux@XN--MAANA-PTA.COM", { punycode: true }),
+    "@quux@xn--maana-pta.com",
+  );
+  deepStrictEqual(
+    normalizeActorHandle("@quux@MAÑANA.COM", { punycode: true }),
+    "@quux@xn--maana-pta.com",
+  );
+
+  throws(() => normalizeActorHandle(""));
+  throws(() => normalizeActorHandle("@"));
+  throws(() => normalizeActorHandle("foo"));
+  throws(() => normalizeActorHandle("@foo"));
+  throws(() => normalizeActorHandle("@@foo.com"));
+  throws(() => normalizeActorHandle("@foo@"));
+  throws(() => normalizeActorHandle("foo@bar.com@baz.com"));
+  throws(() => normalizeActorHandle("@foo@bar.com@baz.com"));
+});
+
+// cSpell: ignore maana

package/src/actor.ts

@@ -0,0 +1,293 @@
+import type { GetUserAgentOptions } from "@fedify/vocab-runtime";
+import { lookupWebFinger } from "@fedify/webfinger";
+import { SpanStatusCode, trace, type TracerProvider } from "@opentelemetry/api";
+import { domainToASCII, domainToUnicode } from "node:url";
+import metadata from "../deno.json" with { type: "json" };
+import { getTypeId } from "./type.ts";
+import { Application, Group, Organization, Person, Service } from "./vocab.ts";
+
+/**
+ * Actor types are {@link Object} types that are capable of performing
+ * activities.
+ */
+export type Actor = Application | Group | Organization | Person | Service;
+
+/**
+ * Checks if the given object is an {@link Actor}.
+ * @param object The object to check.
+ * @returns `true` if the given object is an {@link Actor}.
+ */
+export function isActor(object: unknown): object is Actor {
+  return (
+    object instanceof Application ||
+    object instanceof Group ||
+    object instanceof Organization ||
+    object instanceof Person ||
+    object instanceof Service
+  );
+}
+
+/**
+ * A string representation of an actor type name.
+ */
+export type ActorTypeName =
+  | "Application"
+  | "Group"
+  | "Organization"
+  | "Person"
+  | "Service";
+
+/**
+ * Gets the type name of the given actor.
+ * @param actor The actor to get the type name of.
+ * @returns The type name of the given actor.
+ */
+export function getActorTypeName(
+  actor: Actor,
+): ActorTypeName {
+  if (actor instanceof Application) return "Application";
+  else if (actor instanceof Group) return "Group";
+  else if (actor instanceof Organization) return "Organization";
+  else if (actor instanceof Person) return "Person";
+  else if (actor instanceof Service) return "Service";
+  throw new Error("Unknown actor type.");
+}
+
+/**
+ * Gets the actor class by the given type name.
+ * @param typeName The type name to get the actor class by.
+ * @returns The actor class by the given type name.
+ */
+export function getActorClassByTypeName(
+  typeName: ActorTypeName,
+):
+  | typeof Application
+  | typeof Group
+  | typeof Organization
+  | typeof Person
+  | typeof Service {
+  switch (typeName) {
+    case "Application":
+      return Application;
+    case "Group":
+      return Group;
+    case "Organization":
+      return Organization;
+    case "Person":
+      return Person;
+    case "Service":
+      return Service;
+  }
+  throw new Error("Unknown actor type name.");
+}
+
+/**
+ * Options for {@link getActorHandle}.
+ * @since 1.3.0
+ */
+export interface GetActorHandleOptions extends NormalizeActorHandleOptions {
+  /**
+   * 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;
+}
+
+/**
+ * Gets the actor handle, of the form `@username@domain`, from the given actor
+ * or an actor URI.
+ *
+ * @example
+ * ``` typescript
+ * // Get the handle of an actor object:
+ * await getActorHandle(
+ *   new Person({ id: new URL("https://fosstodon.org/users/hongminhee") })
+ * );
+ *
+ * // Get the handle of an actor URI:
+ * await getActorHandle(new URL("https://fosstodon.org/users/hongminhee"));
+ * ```
+ *
+ * @param actor The actor or actor URI to get the handle from.
+ * @param options The extra options for getting the actor handle.
+ * @returns The actor handle.  It starts with `@` and is followed by the
+ *          username and domain, separated by `@` by default (it can be
+ *          customized with the options).
+ * @throws {TypeError} If the actor does not have enough information to get the
+ *                     handle.
+ * @since 0.4.0
+ */
+export async function getActorHandle(
+  actor: Actor | URL,
+  options: GetActorHandleOptions = {},
+): Promise<`@${string}@${string}` | `${string}@${string}`> {
+  const tracerProvider = options.tracerProvider ?? trace.getTracerProvider();
+  const tracer = tracerProvider.getTracer(
+    metadata.name,
+    metadata.version,
+  );
+  return await tracer.startActiveSpan(
+    "activitypub.get_actor_handle",
+    async (span) => {
+      if (isActor(actor)) {
+        if (actor.id != null) {
+          span.setAttribute("activitypub.actor.id", actor.id.href);
+        }
+        span.setAttribute("activitypub.actor.type", getTypeId(actor).href);
+      }
+      try {
+        return await getActorHandleInternal(actor, options);
+      } catch (error) {
+        span.setStatus({
+          code: SpanStatusCode.ERROR,
+          message: String(error),
+        });
+        throw error;
+      } finally {
+        span.end();
+      }
+    },
+  );
+}
+
+async function getActorHandleInternal(
+  actor: Actor | URL,
+  options: GetActorHandleOptions = {},
+): Promise<`@${string}@${string}` | `${string}@${string}`> {
+  const actorId = actor instanceof URL ? actor : actor.id;
+  if (actorId != null) {
+    const result = await lookupWebFinger(actorId, {
+      userAgent: options.userAgent,
+      tracerProvider: options.tracerProvider,
+    });
+    if (result != null) {
+      const aliases = [...(result.aliases ?? [])];
+      if (result.subject != null) aliases.unshift(result.subject);
+      for (const alias of aliases) {
+        const match = alias.match(/^acct:([^@]+)@([^@]+)$/);
+        if (match != null) {
+          const hostname = new URL(`https://${match[2]}/`).hostname;
+          if (
+            hostname !== actorId.hostname &&
+            !await verifyCrossOriginActorHandle(
+              actorId.href,
+              alias,
+              options.userAgent,
+              options.tracerProvider,
+            )
+          ) {
+            continue;
+          }
+          return normalizeActorHandle(`@${match[1]}@${match[2]}`, options);
+        }
+      }
+    }
+  }
+  if (
+    !(actor instanceof URL) && actor.preferredUsername != null &&
+    actor.id != null
+  ) {
+    return normalizeActorHandle(
+      `@${actor.preferredUsername}@${actor.id.host}`,
+      options,
+    );
+  }
+  throw new TypeError(
+    "Actor does not have enough information to get the handle.",
+  );
+}
+
+async function verifyCrossOriginActorHandle(
+  actorId: string,
+  alias: string,
+  userAgent: GetUserAgentOptions | string | undefined,
+  tracerProvider: TracerProvider | undefined,
+): Promise<boolean> {
+  const response = await lookupWebFinger(alias, { userAgent, tracerProvider });
+  if (response == null) return false;
+  for (const alias of response.aliases ?? []) {
+    if (new URL(alias).href === actorId) return true;
+  }
+  return false;
+}
+
+/**
+ * Options for {@link normalizeActorHandle}.
+ * @since 0.9.0
+ */
+export interface NormalizeActorHandleOptions {
+  /**
+   * Whether to trim the leading `@` from the actor handle.  Turned off by
+   * default.
+   */
+  trimLeadingAt?: boolean;
+
+  /**
+   * Whether to convert the domain part of the actor handle to punycode, if it
+   * is an internationalized domain name.  Turned off by default.
+   */
+  punycode?: boolean;
+}
+
+/**
+ * Normalizes the given actor handle.
+ * @param handle The full handle of the actor to normalize.
+ * @param options The options for normalizing the actor handle.
+ * @returns The normalized actor handle.
+ * @throws {TypeError} If the actor handle is invalid.
+ * @since 0.9.0
+ */
+export function normalizeActorHandle(
+  handle: string,
+  options: NormalizeActorHandleOptions = {},
+): `@${string}@${string}` | `${string}@${string}` {
+  handle = handle.replace(/^@/, "");
+  const atPos = handle.indexOf("@");
+  if (atPos < 1) throw new TypeError("Invalid actor handle.");
+  let domain = handle.substring(atPos + 1);
+  if (domain.length < 1 || domain.includes("@")) {
+    throw new TypeError("Invalid actor handle.");
+  }
+  domain = domain.toLowerCase();
+  domain = options.punycode ? domainToASCII(domain) : domainToUnicode(domain);
+  domain = domain.toLowerCase();
+  const user = handle.substring(0, atPos);
+  return options.trimLeadingAt ? `${user}@${domain}` : `@${user}@${domain}`;
+}
+
+/**
+ * The object that can be a recipient of an activity.
+ *
+ * Note that every {@link Actor} is also a {@link Recipient}.
+ */
+export interface Recipient {
+  /**
+   * The URI of the actor.
+   */
+  readonly id: URL | null;
+
+  /**
+   * The URI of the actor's inbox.
+   */
+  readonly inboxId: URL | null;
+
+  /**
+   * The endpoints of the actor.
+   */
+  readonly endpoints?: {
+    /**
+     * The URI of the actor's shared inbox.
+     */
+    sharedInbox: URL | null;
+  } | null;
+}

package/src/add.yaml

@@ -0,0 +1,16 @@
+$schema: ../../vocab-tools/schema.yaml
+name: Add
+compactName: Add
+uri: "https://www.w3.org/ns/activitystreams#Add"
+extends: "https://www.w3.org/ns/activitystreams#Activity"
+entity: true
+description: |
+  Indicates that the `actor` has added the `object` to the `target`.
+  If the `target` property is not explicitly specified, the target would need
+  to be determined implicitly by context.  The `origin` can be used to identify
+  the context from which the `object` originated.
+defaultContext:
+- "https://w3id.org/identity/v1"
+- "https://www.w3.org/ns/activitystreams"
+- "https://w3id.org/security/data-integrity/v1"
+properties: []