@sdxc/activitypub 0.0.0-pre.1

package/dist/collections.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Builders for the collections an ActivityPub server serves (outbox, followers,
+ * following, featured), so an app turns whatever it pages with into the documents
+ * `stringify` and `respond` write, with every member it leaves out written as absent.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { ActivityPub } from "./lib/types.js";
+/** An entry of a collection as an app authors it: an IRI, or the document itself. */
+export type CollectionItem = ActivityPub.Draft<ActivityPub.Item>;
+/** A collection as an app authors it; every member besides `id` is optional. */
+export interface CollectionInit {
+    id: string;
+    /** Alone, with no `first`, it answers the count and hides the members. */
+    totalItems?: number | null;
+    /** The first page's IRI; with `totalItems` and no items, the shape a paged collection serves. */
+    first?: string | null;
+    last?: string | null;
+}
+/** A page as an app authors it. */
+export interface PageInit {
+    id: string;
+    /** The collection this page belongs to. */
+    partOf: string;
+    next?: string | null;
+    prev?: string | null;
+    totalItems?: number | null;
+}
+/**
+ * An ordered collection: reverse chronological, as ActivityPub §5 requires of an outbox
+ * and of followers and following.
+ *
+ * @param init - The id, count, pages, and inline items for a short collection.
+ * @example
+ * orderedCollection({ id: FOLLOWERS_ID, totalItems: count, first: `${FOLLOWERS_ID}?page=1` });
+ */
+export declare function orderedCollection(init: CollectionInit & {
+    orderedItems?: CollectionItem[];
+}): ActivityPub.Draft<ActivityPub.OrderedCollection>;
+/**
+ * One page of an ordered collection. A `null` `next` marks the last page, which is how a
+ * crawler knows to stop.
+ *
+ * @param init - The page id, its collection, its neighbours and its items.
+ * @example
+ * orderedCollectionPage({ id: pageUrl, partOf: OUTBOX_ID, orderedItems: creates, next });
+ */
+export declare function orderedCollectionPage(init: PageInit & {
+    orderedItems: CollectionItem[];
+}): ActivityPub.Draft<ActivityPub.OrderedCollectionPage>;
+/**
+ * An unordered collection, such as an object's `replies` or `likes`.
+ *
+ * @param init - The id, count, pages, and inline items.
+ */
+export declare function collection(init: CollectionInit & {
+    items?: CollectionItem[];
+}): ActivityPub.Draft<ActivityPub.Collection>;
+/**
+ * One page of an unordered collection.
+ *
+ * @param init - The page id, its collection, its neighbours and its items.
+ */
+export declare function collectionPage(init: PageInit & {
+    items: CollectionItem[];
+}): ActivityPub.Draft<ActivityPub.CollectionPage>;

package/dist/collections.js

@@ -0,0 +1,38 @@
+/**
+ * An ordered collection: reverse chronological, as ActivityPub §5 requires of an outbox
+ * and of followers and following.
+ *
+ * @param init - The id, count, pages, and inline items for a short collection.
+ * @example
+ * orderedCollection({ id: FOLLOWERS_ID, totalItems: count, first: `${FOLLOWERS_ID}?page=1` });
+ */
+export function orderedCollection(init) {
+    return { ...init, type: "OrderedCollection" };
+}
+/**
+ * One page of an ordered collection. A `null` `next` marks the last page, which is how a
+ * crawler knows to stop.
+ *
+ * @param init - The page id, its collection, its neighbours and its items.
+ * @example
+ * orderedCollectionPage({ id: pageUrl, partOf: OUTBOX_ID, orderedItems: creates, next });
+ */
+export function orderedCollectionPage(init) {
+    return { ...init, type: "OrderedCollectionPage" };
+}
+/**
+ * An unordered collection, such as an object's `replies` or `likes`.
+ *
+ * @param init - The id, count, pages, and inline items.
+ */
+export function collection(init) {
+    return { ...init, type: "Collection" };
+}
+/**
+ * One page of an unordered collection.
+ *
+ * @param init - The page id, its collection, its neighbours and its items.
+ */
+export function collectionPage(init) {
+    return { ...init, type: "CollectionPage" };
+}

package/dist/conformance.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The suites that say what each store the package calls is, registered as Vitest tests
+ * against whatever the app constructs. An app runs them over its own D1, KV or Durable Object
+ * implementations, which is what lets the package rely on the contracts its interfaces state.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { FollowerStore, KeyProvider, LocalObjects, SeenActivities } from "./store.js";
+/** What the follower store suite needs. */
+export interface FollowerStoreConformanceOptions {
+    /** Implementation name, which labels the registered suite. */
+    name: string;
+    /** Builds an empty store; called for every test, so each starts clean. */
+    create: () => FollowerStore | Promise<FollowerStore>;
+}
+/** What the seen-activities suite needs. */
+export interface SeenActivitiesConformanceOptions {
+    /** Implementation name, which labels the registered suite. */
+    name: string;
+    /** Builds a store with nothing claimed; called for every test, so each starts clean. */
+    create: () => SeenActivities | Promise<SeenActivities>;
+    /**
+     * Moves the store's clock forward in milliseconds, which registers the expiry assertion. A
+     * store whose TTL only passes in real time leaves it out.
+     */
+    advance?: (ms: number) => void | Promise<void>;
+}
+/** What the local objects suite needs. */
+export interface LocalObjectsConformanceOptions {
+    /** Implementation name, which labels the registered suite. */
+    name: string;
+    create: () => LocalObjects | Promise<LocalObjects>;
+    /** Ids of objects the store built by `create` serves, at least one. */
+    served: string[];
+}
+/** What the key provider suite needs. */
+export interface KeyProviderConformanceOptions {
+    /** Implementation name, which labels the registered suite. */
+    name: string;
+    create: () => KeyProvider | Promise<KeyProvider>;
+    /** Ids of actors the provider built by `create` hosts, at least one. */
+    hosted: string[];
+}
+/**
+ * Registers the suite every `FollowerStore` has to pass: idempotent writes keyed by
+ * `(actor, id)`, accepted-only listings, and cursors that visit each follower and inbox once.
+ *
+ * @param options The implementation under test.
+ *
+ * @example followerStoreConformance({ name: "d1", create: () => new D1FollowerStore(db) });
+ */
+export declare function followerStoreConformance({ name, create }: FollowerStoreConformanceOptions): void;
+/**
+ * Registers the suite every `SeenActivities` has to pass: a claim answers `true` once per id
+ * within its TTL, and, when the clock can be moved, again after the TTL has passed.
+ *
+ * @param options The implementation under test.
+ *
+ * @example seenActivitiesConformance({ name: "kv", create: () => new KvSeenActivities(env.KV) });
+ */
+export declare function seenActivitiesConformance({ name, create, advance, }: SeenActivitiesConformanceOptions): void;
+/**
+ * Registers the suite every `LocalObjects` has to pass: each served id finds its object, and
+ * any other IRI finds `null`.
+ *
+ * @param options The implementation under test and the ids it serves.
+ *
+ * @example localObjectsConformance({ name: "posts", create: () => posts(db), served: [POST_ID] });
+ */
+export declare function localObjectsConformance({ name, create, served, }: LocalObjectsConformanceOptions): void;
+/**
+ * Registers the suite every `KeyProvider` has to pass: each hosted actor answers its own keys,
+ * and any other actor answers `null`.
+ *
+ * @param options The implementation under test and the actors it hosts.
+ *
+ * @example keyProviderConformance({ name: "secrets", create: () => keys(env), hosted: [ACTOR] });
+ */
+export declare function keyProviderConformance({ name, create, hosted, }: KeyProviderConformanceOptions): void;

package/dist/conformance.js

@@ -0,0 +1,313 @@
+/**
+ * The suites that say what each store the package calls is, registered as Vitest tests
+ * against whatever the app constructs. An app runs them over its own D1, KV or Durable Object
+ * implementations, which is what lets the package rely on the contracts its interfaces state.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { unwrap } from "@sdxc/result";
+import { describe, expect, test } from "vitest";
+/** The local actor most tests follow, and a second one that proves followers are per actor. */
+const ACTOR = "https://local.com/users/author";
+const OTHER_ACTOR = "https://local.com/users/editor";
+/** A TTL long enough that nothing expires mid-test, and the same length in milliseconds. */
+const TTL = "1 hour";
+const TTL_MS = 3_600_000;
+/** A follower of `actor` on `server`, accepted, delivered to through its personal inbox. */
+function follower(server, name, overrides = {}) {
+    return {
+        actor: ACTOR,
+        id: `${server}/users/${name}`,
+        inbox: `${server}/users/${name}/inbox`,
+        sharedInbox: null,
+        followId: `${server}/follows/${name}`,
+        state: "accepted",
+        ...overrides,
+    };
+}
+/** Every item of a listing, read page by page with `limit`, failing on a page larger than it. */
+async function drain(read, limit) {
+    let items = [];
+    let cursor = null;
+    let pages = 0;
+    do {
+        let current = await read(cursor);
+        expect(current.items.length).toBeLessThanOrEqual(limit);
+        items.push(...current.items);
+        cursor = current.next;
+        pages += 1;
+        expect(pages, "the cursor reaches the end of the listing").toBeLessThan(100);
+    } while (cursor !== null);
+    return items;
+}
+/**
+ * Registers the suite every `FollowerStore` has to pass: idempotent writes keyed by
+ * `(actor, id)`, accepted-only listings, and cursors that visit each follower and inbox once.
+ *
+ * @param options The implementation under test.
+ *
+ * @example followerStoreConformance({ name: "d1", create: () => new D1FollowerStore(db) });
+ */
+export function followerStoreConformance({ name, create }) {
+    describe(`${name} FollowerStore conformance`, () => {
+        test("reads a follower back as it was put", async () => {
+            let store = await create();
+            let alice = follower("https://one.com", "alice", { sharedInbox: "https://one.com/inbox" });
+            unwrap(await store.put(alice));
+            expect(unwrap(await store.get(ACTOR, alice.id))).toStrictEqual(alice);
+        });
+        test("answers null for an actor that follows nobody here", async () => {
+            let store = await create();
+            expect(unwrap(await store.get(ACTOR, "https://one.com/users/nobody"))).toBeNull();
+        });
+        test("a repeated put replaces the follower, refreshing inbox and followId", async () => {
+            let store = await create();
+            let alice = follower("https://one.com", "alice");
+            let refreshed = {
+                ...alice,
+                inbox: "https://one.com/new/inbox",
+                sharedInbox: "https://one.com/inbox",
+                followId: "https://one.com/follows/again",
+            };
+            unwrap(await store.put(alice));
+            unwrap(await store.put(refreshed));
+            expect(unwrap(await store.get(ACTOR, alice.id))).toStrictEqual(refreshed);
+            expect(unwrap(await store.count(ACTOR))).toBe(1);
+            expect(unwrap(await store.list(ACTOR, { cursor: null, limit: 10 })).items).toStrictEqual([
+                refreshed,
+            ]);
+        });
+        test("a put moves a pending follower to accepted", async () => {
+            let store = await create();
+            let alice = follower("https://one.com", "alice", { state: "pending" });
+            unwrap(await store.put(alice));
+            unwrap(await store.put({ ...alice, state: "accepted" }));
+            expect(unwrap(await store.get(ACTOR, alice.id))?.state).toBe("accepted");
+            expect(unwrap(await store.count(ACTOR))).toBe(1);
+        });
+        test("keys followers by (actor, id), so following two local actors is two followers", async () => {
+            let store = await create();
+            let alice = follower("https://one.com", "alice");
+            let ofEditor = { ...alice, actor: OTHER_ACTOR, followId: "https://one.com/follows/editor" };
+            unwrap(await store.put(alice));
+            unwrap(await store.put(ofEditor));
+            expect(unwrap(await store.get(ACTOR, alice.id))).toStrictEqual(alice);
+            expect(unwrap(await store.get(OTHER_ACTOR, alice.id))).toStrictEqual(ofEditor);
+            expect(unwrap(await store.count(ACTOR))).toBe(1);
+            expect(unwrap(await store.count(OTHER_ACTOR))).toBe(1);
+            unwrap(await store.remove(ACTOR, alice.id));
+            expect(unwrap(await store.get(ACTOR, alice.id))).toBeNull();
+            expect(unwrap(await store.get(OTHER_ACTOR, alice.id))).toStrictEqual(ofEditor);
+        });
+        test("keeps a pending follower readable by get and out of list, count and inboxes", async () => {
+            let store = await create();
+            let alice = follower("https://one.com", "alice");
+            let bob = follower("https://two.com", "bob", { state: "pending" });
+            unwrap(await store.put(alice));
+            unwrap(await store.put(bob));
+            expect(unwrap(await store.get(ACTOR, bob.id))).toStrictEqual(bob);
+            expect(unwrap(await store.list(ACTOR, { cursor: null, limit: 10 })).items).toStrictEqual([
+                alice,
+            ]);
+            expect(unwrap(await store.count(ACTOR))).toBe(1);
+            expect(unwrap(await store.inboxes(ACTOR, { cursor: null, limit: 10 })).items).toStrictEqual([
+                alice.inbox,
+            ]);
+        });
+        test("answers an empty listing and a zero count for an actor nobody follows", async () => {
+            let store = await create();
+            unwrap(await store.put(follower("https://one.com", "alice")));
+            expect(unwrap(await store.list(OTHER_ACTOR, { cursor: null, limit: 10 }))).toStrictEqual({
+                items: [],
+                next: null,
+            });
+            expect(unwrap(await store.count(OTHER_ACTOR))).toBe(0);
+            expect(unwrap(await store.inboxes(OTHER_ACTOR, { cursor: null, limit: 10 }))).toStrictEqual({
+                items: [],
+                next: null,
+            });
+        });
+        test("narrows list to followers whose id has the given origin", async () => {
+            let store = await create();
+            let alice = follower("https://one.com", "alice");
+            let bob = follower("https://two.com", "bob");
+            let carol = follower("https://one.com", "carol");
+            for (let one of [alice, bob, carol])
+                unwrap(await store.put(one));
+            let items = unwrap(await store.list(ACTOR, { cursor: null, limit: 10, origin: "https://one.com" })).items;
+            expect(items).toHaveLength(2);
+            expect(new Set(items.map((one) => one.id))).toStrictEqual(new Set([alice.id, carol.id]));
+        });
+        test("pages through list with limit and cursor, visiting each follower once", async () => {
+            let store = await create();
+            let all = Array.from({ length: 7 }, (_, index) => follower(`https://server${index}.com`, `user${index}`));
+            for (let one of all)
+                unwrap(await store.put(one));
+            let seen = await drain(async (cursor) => unwrap(await store.list(ACTOR, { cursor, limit: 3 })), 3);
+            expect(seen).toHaveLength(all.length);
+            expect(new Set(seen.map((one) => one.id))).toStrictEqual(new Set(all.map((one) => one.id)));
+        });
+        test("answers next null on the page that reaches the end", async () => {
+            let store = await create();
+            unwrap(await store.put(follower("https://one.com", "alice")));
+            unwrap(await store.put(follower("https://two.com", "bob")));
+            expect(unwrap(await store.list(ACTOR, { cursor: null, limit: 5 })).next).toBeNull();
+            expect(unwrap(await store.inboxes(ACTOR, { cursor: null, limit: 5 })).next).toBeNull();
+        });
+        test("lists each delivery target once, preferring the shared inbox", async () => {
+            let store = await create();
+            let shared = "https://one.com/inbox";
+            unwrap(await store.put(follower("https://one.com", "alice", { sharedInbox: shared })));
+            unwrap(await store.put(follower("https://one.com", "carol", { sharedInbox: shared })));
+            unwrap(await store.put(follower("https://two.com", "bob")));
+            let targets = unwrap(await store.inboxes(ACTOR, { cursor: null, limit: 10 })).items;
+            expect(targets).toHaveLength(2);
+            expect(new Set(targets)).toStrictEqual(new Set([shared, "https://two.com/users/bob/inbox"]));
+        });
+        test("pages through inboxes with limit and cursor, visiting each target once", async () => {
+            let store = await create();
+            let expected = [];
+            for (let index = 0; index < 5; index += 1) {
+                let server = `https://server${index}.com`;
+                let shared = `${server}/inbox`;
+                expected.push(shared);
+                unwrap(await store.put(follower(server, "alice", { sharedInbox: shared })));
+                unwrap(await store.put(follower(server, "bob", { sharedInbox: shared })));
+            }
+            unwrap(await store.put(follower("https://solo.com", "carol")));
+            expected.push("https://solo.com/users/carol/inbox");
+            let seen = await drain(async (cursor) => unwrap(await store.inboxes(ACTOR, { cursor, limit: 2 })), 2);
+            expect(seen).toHaveLength(expected.length);
+            expect(new Set(seen)).toStrictEqual(new Set(expected));
+        });
+        test("removeInbox drops every follower delivered through that personal inbox", async () => {
+            let store = await create();
+            let alice = follower("https://one.com", "alice");
+            let bob = follower("https://two.com", "bob");
+            unwrap(await store.put(alice));
+            unwrap(await store.put({ ...alice, actor: OTHER_ACTOR }));
+            unwrap(await store.put(bob));
+            unwrap(await store.removeInbox(alice.inbox));
+            expect(unwrap(await store.get(ACTOR, alice.id))).toBeNull();
+            expect(unwrap(await store.get(OTHER_ACTOR, alice.id))).toBeNull();
+            expect(unwrap(await store.get(ACTOR, bob.id))).toStrictEqual(bob);
+        });
+        test("removeInbox drops every follower whose shared inbox it is", async () => {
+            let store = await create();
+            let shared = "https://one.com/inbox";
+            let alice = follower("https://one.com", "alice", { sharedInbox: shared });
+            let carol = follower("https://one.com", "carol", { sharedInbox: shared, state: "pending" });
+            let bob = follower("https://two.com", "bob");
+            for (let one of [alice, carol, bob])
+                unwrap(await store.put(one));
+            unwrap(await store.removeInbox(shared));
+            expect(unwrap(await store.get(ACTOR, alice.id))).toBeNull();
+            expect(unwrap(await store.get(ACTOR, carol.id))).toBeNull();
+            expect(unwrap(await store.count(ACTOR))).toBe(1);
+            expect(unwrap(await store.inboxes(ACTOR, { cursor: null, limit: 10 })).items).toStrictEqual([
+                bob.inbox,
+            ]);
+        });
+        test("remove deletes the follower, and succeeds again once it is gone", async () => {
+            let store = await create();
+            let alice = follower("https://one.com", "alice");
+            unwrap(await store.put(alice));
+            unwrap(await store.remove(ACTOR, alice.id));
+            unwrap(await store.remove(ACTOR, alice.id));
+            unwrap(await store.remove(ACTOR, "https://one.com/users/nobody"));
+            expect(unwrap(await store.get(ACTOR, alice.id))).toBeNull();
+            expect(unwrap(await store.count(ACTOR))).toBe(0);
+        });
+        test("removeInbox succeeds for an inbox no follower uses", async () => {
+            let store = await create();
+            let alice = follower("https://one.com", "alice");
+            unwrap(await store.put(alice));
+            unwrap(await store.removeInbox("https://three.com/inbox"));
+            expect(unwrap(await store.count(ACTOR))).toBe(1);
+        });
+    });
+}
+/**
+ * Registers the suite every `SeenActivities` has to pass: a claim answers `true` once per id
+ * within its TTL, and, when the clock can be moved, again after the TTL has passed.
+ *
+ * @param options The implementation under test.
+ *
+ * @example seenActivitiesConformance({ name: "kv", create: () => new KvSeenActivities(env.KV) });
+ */
+export function seenActivitiesConformance({ name, create, advance, }) {
+    describe(`${name} SeenActivities conformance`, () => {
+        test("answers true for the first claim and false for a repeat within the TTL", async () => {
+            let seen = await create();
+            let id = "https://one.com/activities/1";
+            expect(unwrap(await seen.claim(id, TTL))).toBe(true);
+            expect(unwrap(await seen.claim(id, TTL))).toBe(false);
+            expect(unwrap(await seen.claim(id, TTL))).toBe(false);
+        });
+        test("claims each id on its own", async () => {
+            let seen = await create();
+            expect(unwrap(await seen.claim("https://one.com/activities/1", TTL))).toBe(true);
+            expect(unwrap(await seen.claim("https://one.com/activities/2", TTL))).toBe(true);
+        });
+        if (advance) {
+            test("answers true again once the TTL has passed", async () => {
+                let seen = await create();
+                let id = "https://one.com/activities/1";
+                expect(unwrap(await seen.claim(id, TTL))).toBe(true);
+                await advance(TTL_MS - 1);
+                expect(unwrap(await seen.claim(id, TTL))).toBe(false);
+                await advance(1);
+                expect(unwrap(await seen.claim(id, TTL))).toBe(true);
+                expect(unwrap(await seen.claim(id, TTL))).toBe(false);
+            });
+        }
+    });
+}
+/**
+ * Registers the suite every `LocalObjects` has to pass: each served id finds its object, and
+ * any other IRI finds `null`.
+ *
+ * @param options The implementation under test and the ids it serves.
+ *
+ * @example localObjectsConformance({ name: "posts", create: () => posts(db), served: [POST_ID] });
+ */
+export function localObjectsConformance({ name, create, served, }) {
+    describe(`${name} LocalObjects conformance`, () => {
+        test("finds every served object under its own id", async () => {
+            let objects = await create();
+            expect(served.length, "the suite needs at least one served id").toBeGreaterThan(0);
+            for (let id of served)
+                expect(unwrap(await objects.find(id))?.id).toBe(id);
+        });
+        test("answers null for an IRI it serves nothing under", async () => {
+            let objects = await create();
+            expect(unwrap(await objects.find(`https://remote.com/${crypto.randomUUID()}`))).toBeNull();
+        });
+    });
+}
+/**
+ * Registers the suite every `KeyProvider` has to pass: each hosted actor answers its own keys,
+ * and any other actor answers `null`.
+ *
+ * @param options The implementation under test and the actors it hosts.
+ *
+ * @example keyProviderConformance({ name: "secrets", create: () => keys(env), hosted: [ACTOR] });
+ */
+export function keyProviderConformance({ name, create, hosted, }) {
+    describe(`${name} KeyProvider conformance`, () => {
+        test("answers each hosted actor's keys, naming that actor", async () => {
+            let provider = await create();
+            expect(hosted.length, "the suite needs at least one hosted actor").toBeGreaterThan(0);
+            for (let actor of hosted) {
+                let keys = unwrap(await provider.keysOf(actor));
+                expect(keys?.actor).toBe(actor);
+                expect(keys?.rsa.id).toEqual(expect.any(String));
+            }
+        });
+        test("answers null for an actor it does not host", async () => {
+            let provider = await create();
+            expect(unwrap(await provider.keysOf(`https://remote.com/users/${crypto.randomUUID()}`))).toBeNull();
+        });
+    });
+}

package/dist/discovery.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Discovery of ActivityPub actors through WebFinger: the `self` link that points a
+ * handle such as `acct:user@host` at the actor document, which Mastodon follows to
+ * resolve an account, and `lookup`, which resolves a remote handle the same way.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { DurationInput } from "@sdxc/duration";
+import type { Result } from "@sdxc/result";
+import type { JrdLink } from "@sdxc/well-known/webfinger";
+import type { ActivityPub } from "./lib/types.js";
+import type { Resolver } from "./remote.js";
+import { ActivityPubFetchError } from "./errors.js";
+/** What `lookup` resolves the actor through. */
+export interface LookupOptions {
+    /** Fetches the actor the WebFinger `self` link names. */
+    resolver: Resolver;
+    /** Sent with the WebFinger request; some instances refuse requests without one. */
+    userAgent?: string;
+    /** @default "10 seconds" */
+    timeout?: DurationInput;
+}
+/**
+ * The WebFinger link to an actor document: `rel="self"` typed
+ * `application/activity+json`, which Mastodon requires before it fetches the actor. WebFinger
+ * for `preferredUsername@<actor host>` must answer this link for the reverse check.
+ *
+ * @param actorId - The actor document's id.
+ * @example
+ * let jrd = { subject: "acct:hello@example.com", aliases: [], properties: {}, links: [actorLink(ACTOR_ID)] };
+ */
+export declare function actorLink(actorId: string): JrdLink;
+/**
+ * Resolves a handle to its actor the way Mastodon does: WebFinger on the handle's host, the
+ * `self` link typed as ActivityStreams, then the actor through `resolver`. The actor's
+ * canonical handle is `preferredUsername@<actor host>`; unless it equals the given handle,
+ * WebFinger on the actor's host must point that canonical handle back at the same actor.
+ *
+ * @param handle - `@user@host`, `user@host` or `acct:user@host`.
+ * @param options - The resolver, and the `User-Agent` and deadline of the WebFinger requests.
+ * @returns The actor; `not-found` when WebFinger names no actor link, `id-mismatch` when the
+ * actor's host does not confirm the handle, `refused-url` for a handle that names no host.
+ * @example let actor = await lookup("@someone@mastodon.social", { resolver });
+ */
+export declare function lookup(handle: string, options: LookupOptions): Promise<Result<ActivityPub.Actor, ActivityPubFetchError>>;

package/dist/discovery.js

@@ -0,0 +1,105 @@
+import { failure, isFailure, success } from "@sdxc/result";
+import { MEDIA_TYPE, parse } from "@sdxc/well-known/webfinger";
+import { ActivityPubFetchError } from "./errors.js";
+import { ACTIVITY_JSON, AS2_CONTEXT, LD_JSON } from "./lib/constants.js";
+import { DEFAULT_TIMEOUT, fetchText } from "./lib/fetch.js";
+/** A JRD names a handful of links; anything near this size is not a WebFinger answer. */
+const MAX_JRD_BYTES = 64 * 1024;
+/** `acct:user@host`, `user@host` or `@user@host`; the host may carry a port. */
+const HANDLE_PATTERN = /^(?:acct:|@)?([^@\s/]+)@([^@\s/?#]+)$/u;
+/**
+ * The WebFinger link to an actor document: `rel="self"` typed
+ * `application/activity+json`, which Mastodon requires before it fetches the actor. WebFinger
+ * for `preferredUsername@<actor host>` must answer this link for the reverse check.
+ *
+ * @param actorId - The actor document's id.
+ * @example
+ * let jrd = { subject: "acct:hello@example.com", aliases: [], properties: {}, links: [actorLink(ACTOR_ID)] };
+ */
+export function actorLink(actorId) {
+    return { rel: "self", type: ACTIVITY_JSON, href: actorId, titles: {}, properties: {} };
+}
+/**
+ * Resolves a handle to its actor the way Mastodon does: WebFinger on the handle's host, the
+ * `self` link typed as ActivityStreams, then the actor through `resolver`. The actor's
+ * canonical handle is `preferredUsername@<actor host>`; unless it equals the given handle,
+ * WebFinger on the actor's host must point that canonical handle back at the same actor.
+ *
+ * @param handle - `@user@host`, `user@host` or `acct:user@host`.
+ * @param options - The resolver, and the `User-Agent` and deadline of the WebFinger requests.
+ * @returns The actor; `not-found` when WebFinger names no actor link, `id-mismatch` when the
+ * actor's host does not confirm the handle, `refused-url` for a handle that names no host.
+ * @example let actor = await lookup("@someone@mastodon.social", { resolver });
+ */
+export async function lookup(handle, options) {
+    let match = HANDLE_PATTERN.exec(handle.trim());
+    let user = match?.[1];
+    let host = match?.[2];
+    if (user === undefined || host === undefined || !URL.canParse(`https://${host}/`)) {
+        return failure(new ActivityPubFetchError("refused-url", handle, `${handle} is not a user@host handle`));
+    }
+    let self = await selfLink(user, host, options);
+    if (isFailure(self))
+        return self;
+    let actor = await options.resolver.actor(self.data);
+    if (isFailure(actor))
+        return actor;
+    let actorId = actor.data.id;
+    let actorHost = new URL(actorId).host;
+    let username = actor.data.preferredUsername;
+    let sameHost = actorHost === new URL(`https://${host}/`).host;
+    if (sameHost && username.toLowerCase() === user.toLowerCase())
+        return actor;
+    let canonical = `${username}@${actorHost}`;
+    let reverse = await selfLink(username, actorHost, options);
+    if (isFailure(reverse) && reverse.error.retryable)
+        return reverse;
+    if (isFailure(reverse) || reverse.data !== actorId) {
+        return failure(new ActivityPubFetchError("id-mismatch", actorId, `${actorId} is ${canonical}, whose WebFinger does not confirm ${user}@${host}`, { cause: isFailure(reverse) ? reverse.error : undefined }));
+    }
+    return actor;
+}
+/**
+ * The `self` link typed as ActivityStreams that WebFinger on `host` answers for
+ * `acct:user@host`; `not-found` when it names none.
+ */
+async function selfLink(user, host, options) {
+    let account = `acct:${user}@${host}`;
+    let url = new URL(`https://${host}/.well-known/webfinger`);
+    url.searchParams.set("resource", account);
+    let headers = new Headers({ accept: MEDIA_TYPE });
+    if (options.userAgent !== undefined)
+        headers.set("user-agent", options.userAgent);
+    let body = await fetchText(url.href, {
+        headers,
+        timeout: options.timeout ?? DEFAULT_TIMEOUT,
+        maxBytes: MAX_JRD_BYTES,
+    });
+    if (isFailure(body))
+        return body;
+    let jrd = parse(body.data.text);
+    if (isFailure(jrd)) {
+        return failure(new ActivityPubFetchError("invalid-document", url.href, jrd.error.message, {
+            cause: jrd.error,
+        }));
+    }
+    let self = jrd.data.links.find((link) => link.rel === "self" && isActivityType(link.type));
+    if (self === undefined || self.href === null) {
+        return failure(new ActivityPubFetchError("not-found", url.href, `${account} names no ActivityPub actor`));
+    }
+    return success(self.href);
+}
+/**
+ * Whether a link's media type is ActivityStreams: `application/activity+json`, or
+ * `application/ld+json` with the AS2 profile, which some servers write instead.
+ */
+function isActivityType(type) {
+    if (type === null || type === undefined)
+        return false;
+    let [essence = "", ...parameters] = type.split(";").map((part) => part.trim());
+    if (essence.toLowerCase() === ACTIVITY_JSON)
+        return true;
+    if (essence.toLowerCase() !== LD_JSON)
+        return false;
+    return parameters.some((parameter) => parameter.replaceAll('"', "") === `profile=${AS2_CONTEXT}`);
+}