@sdxc/activitypub 0.0.0-pre.1

package/dist/federation.js

@@ -0,0 +1,513 @@
+import { currentLog } from "@sdxc/logger";
+import { failure, isFailure, success } from "@sdxc/result";
+import { orderedCollection, orderedCollectionPage } from "./collections.js";
+import { lookup } from "./discovery.js";
+import { ActivityPubError, FederationError } from "./errors.js";
+import { fanOut, MAX_ACTIVITY_BYTES } from "./lib/delivery-fan-out.js";
+import { deliver, DELIVERY_BACKOFF } from "./lib/delivery-post.js";
+import { handle } from "./lib/inbox-handle.js";
+import { receive, verifyFetch } from "./lib/inbox-receive.js";
+import { summarize } from "./lib/inbox-summarize.js";
+import { MESSAGE } from "./lib/messages.js";
+import { respond, wantsActivity } from "./lib/response.js";
+import { stringify } from "./lib/stringify.js";
+import { RemoteResolver } from "./remote.js";
+/** Followers listed per page of the followers collection. */
+const DEFAULT_COLLECTION_PAGE_SIZE = 50;
+/** The handler key of `handle` each registrable activity type reaches. */
+const HANDLER_KEYS = {
+    Follow: "follow",
+    Undo: "undo",
+    Create: "create",
+    Update: "update",
+    Delete: "delete",
+    Like: "like",
+    Announce: "announce",
+    Accept: "accept",
+    Reject: "reject",
+    Move: "move",
+};
+/**
+ * Federates one local actor. Construct it wherever the stores are at hand (per request or
+ * per job is fine: it holds no state beyond its options and handlers), route the actor's
+ * URLs through `fetch`, and hand every queued message to `process`.
+ *
+ * @example
+ * let federation = new Federation({ actor, keys, stores, cache, userAgent, queue });
+ * federation.on("Create", async (ctx) => saveReply(ctx.summary()));
+ */
+export class Federation {
+    /**
+     * The Standard Schema of every message federation enqueues (`inbox`, `fanOut` and
+     * `deliver`, told apart by `kind`), so one job declared with it carries all three.
+     *
+     * @example federation: job({ input: Federation.MESSAGE })
+     */
+    static MESSAGE = MESSAGE;
+    /**
+     * Fetches remote actors, keys and objects through the app's cache, signing every GET
+     * with the local actor's keys unless `resolver.signed` is `false`.
+     */
+    resolver;
+    #options;
+    #keys;
+    #blocked;
+    #backoff;
+    #now;
+    #handlers = new Map();
+    /** @param options - The local actor, its keys, the stores, the cache and the queue. */
+    constructor(options) {
+        this.#options = options;
+        this.#keys = providerOf(options.keys);
+        this.#blocked = options.blocked ?? (() => false);
+        this.#backoff = options.backoff ?? DELIVERY_BACKOFF;
+        this.#now = options.now ?? (() => new Date());
+        this.resolver = new RemoteResolver({
+            cache: options.cache,
+            userAgent: options.userAgent,
+            ...(options.resolver?.signed === false
+                ? {}
+                : { signer: { actor: options.actor.id, keys: options.keys } }),
+            ...(options.resolver?.ttl === undefined ? {} : { ttl: options.resolver.ttl }),
+            ...(options.resolver?.timeout === undefined ? {} : { timeout: options.resolver.timeout }),
+            ...(options.resolver?.maxBytes === undefined ? {} : { maxBytes: options.resolver.maxBytes }),
+        });
+    }
+    /**
+     * Registers the app's handler for one or more activity types, called once the package
+     * has done the work the protocol requires (followers kept, Accept sent, ownership and
+     * relevance checked). A later registration for a type replaces the earlier one.
+     *
+     * A handler answers nothing or a `Result`; a failure, or an exception, retries the
+     * message, so a handler tolerates seeing an activity twice. A `Follow` handler may
+     * answer `"accept"`, `"reject"` or `"pending"`. `Like` handlers also receive Pleroma's
+     * `EmojiReact`.
+     *
+     * @param type - The activity type, or several sharing one handler.
+     * @param handler - Receives the verified activity and its `summary()`.
+     * @returns The federation, so registrations chain.
+     * @example federation.on(["Like", "Announce"], async (ctx) => saveResponse(ctx.summary()));
+     */
+    on(type, handler) {
+        let types = typeof type === "string" ? [type] : type;
+        for (let one of types)
+            this.#handlers.set(one, handler);
+        return this;
+    }
+    /**
+     * Answers the local actor's own URLs, as its document names them: the actor (with
+     * `publicKey` from its keys), a `POST` to `inbox` or `endpoints.sharedInbox`, `outbox`,
+     * `followers` and `following`. Any other URL answers `null`, so the app routes it on.
+     *
+     * An inbox `POST` is verified here, inside the request, and answers `202` once its
+     * message is queued, or the status of the check it failed. With `authorizedFetch`, the
+     * collections require a signed GET; the actor document always answers unsigned.
+     *
+     * @param request - Any incoming request.
+     * @returns The response, or `null` for a URL that is not one of the actor's.
+     * @example let response = await federation.fetch(request); if (response) return response;
+     */
+    async fetch(request) {
+        let actor = this.#options.actor;
+        let path = pathOf(request.url);
+        if (path === null)
+            return null;
+        let method = request.method.toUpperCase();
+        let reads = method === "GET" || method === "HEAD";
+        let isInbox = path === pathOf(actor.inbox) || path === pathOf(actor.endpoints.sharedInbox);
+        if (isInbox && method === "POST")
+            return this.#receive(request);
+        let route = this.#documentRoute(path);
+        if (route !== null && reads) {
+            if (route !== "actor" && this.#options.authorizedFetch === true) {
+                let verified = await this.verify(request);
+                if (isFailure(verified))
+                    return verified.error.toResponse();
+            }
+            return this.#serve(route, request);
+        }
+        if (isInbox)
+            return notAllowed("POST");
+        if (route !== null)
+            return notAllowed("GET, HEAD");
+        return null;
+    }
+    /**
+     * Answers `document` as ActivityStreams when the request prefers it over HTML, for a
+     * URL that serves both, such as a post's page. The response carries `Vary: Accept`, an
+     * `ETag` with `304` revalidation, a public 5-minute cache unless stated, and `410` for a
+     * `Tombstone`. With `authorizedFetch`, the request must carry a valid signature.
+     *
+     * @param request - The incoming request.
+     * @param document - The object, actor or collection the URL names.
+     * @param options - The cache policy, extra headers and status.
+     * @returns The response, or `null` when HTML wins and the app renders its page.
+     * @example let response = await federation.respond(request, article); if (response) return response;
+     */
+    async respond(request, document, options = {}) {
+        if (!wantsActivity(request))
+            return null;
+        if (this.#options.authorizedFetch === true) {
+            let verified = await this.verify(request);
+            if (isFailure(verified))
+                return verified.error.toResponse();
+        }
+        return respond(document, { ...options, request, vary: true });
+    }
+    /**
+     * Verifies the signature on a GET (authorized fetch): the blocked host of the key, the
+     * signature's age, and the key, refetched once when it no longer verifies. The local
+     * actor's document passes unsigned, because remote servers read its key from there.
+     *
+     * @param request - The GET.
+     * @returns The signer, or an `InboxError` whose `toResponse()` refuses the request.
+     * @example let verified = await federation.verify(request); if (isFailure(verified)) return verified.error.toResponse();
+     */
+    verify(request) {
+        let maxAge = this.#options.inbox?.maxAge;
+        return verifyFetch(request, {
+            resolver: this.resolver,
+            blocked: this.#blocked,
+            actors: [this.#options.actor.id],
+            now: this.#now(),
+            ...(maxAge === undefined ? {} : { maxAge }),
+        });
+    }
+    /**
+     * Runs one queued message: an inbox activity through the protocol's checks and the
+     * app's handlers, a fan-out into one `deliver` message per distinct inbox, or one signed
+     * delivery. Accept and Reject replies are queued as deliveries, and an inbox answering
+     * `410` drops every follower reached through it.
+     *
+     * @param message - What the queue handed back, read through `Federation.MESSAGE`.
+     * @param options - The job's attempt, starting at 1, which spaces retries.
+     * @returns What happened, or a `FederationError` whose `retryable` and `delay` say
+     *   whether and when to retry.
+     * @example
+     * let processed = await federation.process(ctx.input, { attempts: ctx.attempts });
+     * if (isFailure(processed) && processed.error.retryable) ctx.retry({ delay: processed.error.delay });
+     */
+    async process(message, options = {}) {
+        let attempts = options.attempts ?? 1;
+        if (message.kind === "inbox")
+            return this.#processInbox(message, attempts);
+        if (message.kind === "fanOut")
+            return this.#processFanOut(message, attempts);
+        return this.#processDelivery(message, attempts);
+    }
+    /**
+     * Queues the fan-out of an activity by the local actor to everyone it addresses: its
+     * followers when the followers collection is in `to` or `cc`, and every other addressed
+     * actor's inbox.
+     *
+     * @param activity - The activity, as a document or as JSON text already serialized.
+     * @returns `too-large` for an activity over 120 KB, which no delivery message can carry,
+     *   or a retryable `enqueue` failure.
+     * @example await federation.publish({ id: `${post.url}#create`, type: "Create", actor: ACTOR_ID, object: article, to: [PUBLIC], cc: [FOLLOWERS_ID] });
+     */
+    async publish(activity) {
+        let text = typeof activity === "string" ? activity : stringify(activity);
+        let size = new TextEncoder().encode(text).byteLength;
+        if (size > MAX_ACTIVITY_BYTES) {
+            return failure(new ActivityPubError("too-large", `The activity is ${size} bytes, over the ${MAX_ACTIVITY_BYTES} a delivery can carry`));
+        }
+        return this.#enqueue([{ kind: "fanOut", actor: this.#options.actor.id, activity: text }]);
+    }
+    /**
+     * 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, whose own host must confirm
+     * the handle when it differs from the actor's canonical one.
+     *
+     * @param handle - `@user@host`, `user@host` or `acct:user@host`.
+     * @returns The actor; `not-found` when WebFinger names no actor, `id-mismatch` when the
+     *   actor's host does not confirm the handle.
+     * @example let actor = await federation.lookup("@someone@mastodon.social");
+     */
+    lookup(handle) {
+        let timeout = this.#options.resolver?.timeout;
+        return lookup(handle, {
+            resolver: this.resolver,
+            userAgent: this.#options.userAgent,
+            ...(timeout === undefined ? {} : { timeout }),
+        });
+    }
+    /** Verifies an inbox POST and queues it; the status says what the sender does next. */
+    async #receive(request) {
+        let inbox = this.#options.inbox;
+        let received = await receive(request, {
+            resolver: this.resolver,
+            blocked: this.#blocked,
+            cache: this.#options.cache,
+            now: this.#now(),
+            ...(inbox?.maxBytes === undefined ? {} : { maxBytes: inbox.maxBytes }),
+            ...(inbox?.maxAge === undefined ? {} : { maxAge: inbox.maxAge }),
+        });
+        if (isFailure(received)) {
+            currentLog()?.note("activitypub.inbox.refused", {
+                code: received.error.code,
+                reason: received.error.message,
+            });
+            return received.error.toResponse();
+        }
+        let queued = await this.#enqueue([{ kind: "inbox", ...received.data }]);
+        if (isFailure(queued)) {
+            currentLog()?.warn("activitypub.inbox.unqueued", { reason: queued.error.message });
+            return unavailable();
+        }
+        return new Response(null, { status: 202 });
+    }
+    /** Which of the actor's documents `path` names, or `null` for none. */
+    #documentRoute(path) {
+        let actor = this.#options.actor;
+        if (path === pathOf(actor.id))
+            return "actor";
+        if (path === pathOf(actor.outbox))
+            return "outbox";
+        if (path === pathOf(actor.followers))
+            return "followers";
+        if (path === pathOf(actor.following))
+            return "following";
+        return null;
+    }
+    /** Answers one of the actor's documents; a failing store answers `503`. */
+    async #serve(route, request) {
+        let document = await this.#document(route, new URL(request.url));
+        if (isFailure(document)) {
+            currentLog()?.warn("activitypub.document.unavailable", {
+                route,
+                reason: document.error.message,
+            });
+            return unavailable();
+        }
+        return respond(document.data, { request });
+    }
+    /** The document a route answers with, built from the actor, its keys and the stores. */
+    async #document(route, url) {
+        let actor = this.#options.actor;
+        if (route === "actor") {
+            let keys = await this.#keys.keysOf(actor.id);
+            let publicKey = !isFailure(keys) && keys.data !== null ? keys.data.publicKey : actor.publicKey;
+            return success({ ...actor, publicKey });
+        }
+        let id = url.origin + url.pathname;
+        let paged = url.searchParams.has("page") || url.searchParams.has("cursor");
+        let cursor = url.searchParams.get("cursor");
+        if (route === "following")
+            return success(orderedCollection({ id, totalItems: 0 }));
+        if (route === "followers") {
+            if (!paged) {
+                let count = await this.#options.stores.followers.count(actor.id);
+                if (isFailure(count))
+                    return count;
+                return success(orderedCollection({ id, totalItems: count.data, first: pageUrl(id, null) }));
+            }
+            let listed = await this.#options.stores.followers.list(actor.id, {
+                cursor,
+                limit: this.#options.collections?.pageSize ?? DEFAULT_COLLECTION_PAGE_SIZE,
+            });
+            if (isFailure(listed))
+                return listed;
+            return success(orderedCollectionPage({
+                id: pageUrl(id, cursor),
+                partOf: id,
+                orderedItems: listed.data.items.map((follower) => follower.id),
+                next: listed.data.next === null ? null : pageUrl(id, listed.data.next),
+            }));
+        }
+        let outbox = this.#options.outbox;
+        if (outbox === undefined)
+            return success(orderedCollection({ id, totalItems: 0 }));
+        let page = await outbox(paged ? cursor : null);
+        if (isFailure(page))
+            return page;
+        if (!paged) {
+            return success(orderedCollection({
+                id,
+                totalItems: page.data.totalItems ?? null,
+                first: pageUrl(id, null),
+            }));
+        }
+        return success(orderedCollectionPage({
+            id: pageUrl(id, cursor),
+            partOf: id,
+            orderedItems: page.data.items,
+            next: page.data.next === null ? null : pageUrl(id, page.data.next),
+        }));
+    }
+    /** Runs an inbox activity through `handle` with the app's handlers. */
+    async #processInbox(message, attempts) {
+        let stores = this.#options.stores;
+        let handled = await handle(message, {
+            actor: this.#options.actor,
+            keys: this.#keys,
+            followers: stores.followers,
+            seen: stores.seen,
+            objects: stores.objects,
+            resolver: this.resolver,
+            blocked: this.#blocked,
+            send: (activity, inbox) => this.#enqueue([{ kind: "deliver", actor: this.#options.actor.id, activity, inbox }]),
+            on: this.#handlerTable(),
+            attempts,
+            ...(this.#options.seenTtl === undefined ? {} : { seenTtl: this.#options.seenTtl }),
+        });
+        if (isFailure(handled))
+            return this.#failed("inbox", handled.error, attempts, null);
+        return success({ kind: "inbox", ...handled.data });
+    }
+    /** Turns a published activity into one `deliver` message per distinct inbox. */
+    async #processFanOut(message, attempts) {
+        let pageSize = this.#options.delivery?.pageSize;
+        let planned = await fanOut({ actor: message.actor, activity: message.activity }, {
+            actor: this.#options.actor,
+            followers: this.#options.stores.followers,
+            resolver: this.resolver,
+            blocked: this.#blocked,
+            cache: this.#options.cache,
+            enqueue: (deliveries) => this.#enqueue(deliveries.map((delivery) => ({ kind: "deliver", ...delivery }))),
+            now: this.#now,
+            ...(pageSize === undefined ? {} : { pageSize }),
+        });
+        if (isFailure(planned))
+            return this.#failed("fanOut", planned.error, attempts, null);
+        return success({ kind: "fanOut", ...planned.data });
+    }
+    /** Signs and POSTs one delivery, dropping the followers behind an inbox that is gone. */
+    async #processDelivery(message, attempts) {
+        let timeout = this.#options.delivery?.timeout;
+        let sent = await deliver({ actor: message.actor, activity: message.activity, inbox: message.inbox }, {
+            keys: this.#keys,
+            cache: this.#options.cache,
+            userAgent: this.#options.userAgent,
+            now: this.#now,
+            ...(timeout === undefined ? {} : { timeout }),
+        });
+        if (!isFailure(sent))
+            return success({ kind: "deliver", ...sent.data });
+        if (sent.error.code === "gone") {
+            let removed = await this.#options.stores.followers.removeInbox(message.inbox);
+            if (isFailure(removed)) {
+                let error = new ActivityPubError("store", removed.error.message, {
+                    retryable: true,
+                    cause: removed.error,
+                });
+                return this.#failed("deliver", error, attempts, null);
+            }
+        }
+        return this.#failed("deliver", sent.error, attempts, sent.error.retryAfter);
+    }
+    /**
+     * A failed message, with the wait before its retry: the backoff step for this attempt,
+     * or the inbox's `Retry-After` when that is longer.
+     */
+    #failed(kind, error, attempts, retryAfter) {
+        let delay = Math.max(retryAfter ?? 0, this.#backoff.delay(attempts));
+        return failure(new FederationError(kind, error, delay));
+    }
+    /**
+     * Writes messages to the app's queue, through `enqueueMany` when it has one. A failure,
+     * or an exception, answers a retryable `enqueue` error.
+     */
+    async #enqueue(messages) {
+        let queue = this.#options.queue;
+        let written = undefined;
+        try {
+            if (queue.enqueueMany !== undefined && messages.length > 1) {
+                written = await queue.enqueueMany(messages);
+            }
+            else {
+                for (let message of messages) {
+                    written = await queue.enqueue(message);
+                    if (isResult(written) && isFailure(written))
+                        break;
+                }
+            }
+        }
+        catch (cause) {
+            return failure(enqueueFailed(cause));
+        }
+        if (isResult(written) && isFailure(written))
+            return failure(enqueueFailed(written.error));
+        return success(undefined);
+    }
+    /** The registered handlers in the shape `handle` calls, each given its context. */
+    #handlerTable() {
+        let table = {};
+        for (let [type, handler] of this.#handlers) {
+            let call = (inbound) => invoke(handler, contextOf(inbound));
+            Object.assign(table, { [HANDLER_KEYS[type]]: call });
+        }
+        return table;
+    }
+}
+/** The provider every internal step reads keys through, built from a single actor's keys. */
+function providerOf(keys) {
+    if ("keysOf" in keys)
+        return keys;
+    return { keysOf: async (actor) => success(actor === keys.actor ? keys : null) };
+}
+/** The origin and path an IRI names, which is what a request URL is routed by. */
+function pathOf(iri) {
+    if (iri === null)
+        return null;
+    let url = URL.parse(iri);
+    return url === null ? null : url.origin + url.pathname;
+}
+/** The URL of a collection page: `?page=true`, plus the store's cursor past the first. */
+function pageUrl(id, cursor) {
+    let url = new URL(id);
+    url.searchParams.set("page", "true");
+    if (cursor !== null)
+        url.searchParams.set("cursor", cursor);
+    return url.href;
+}
+/** The answer to a method the URL does not serve. */
+function notAllowed(allow) {
+    return new Response(null, { status: 405, headers: { allow } });
+}
+/** The answer when a store or the queue failed, which a sender or crawler retries. */
+function unavailable() {
+    return new Response("The server could not complete the request.", {
+        status: 503,
+        headers: { "content-type": "text/plain; charset=utf-8", "retry-after": "60" },
+    });
+}
+/** Whether a value is a `Result`, which handlers and queues may answer instead of nothing. */
+function isResult(value) {
+    if (typeof value !== "object" || value === null || !("status" in value))
+        return false;
+    return ((value.status === "success" && "data" in value) ||
+        (value.status === "failure" && "error" in value));
+}
+/** A retryable `enqueue` failure wrapping what the queue raised. */
+function enqueueFailed(cause) {
+    let reason = cause instanceof Error ? cause.message : String(cause);
+    return new ActivityPubError("enqueue", `Could not enqueue: ${reason}`, {
+        retryable: true,
+        cause,
+    });
+}
+/**
+ * The context a handler receives: the inbound activity and its summary. A `Delete`
+ * summarizes as nothing.
+ */
+function contextOf(inbound) {
+    if ("deleted" in inbound)
+        return { ...inbound, summary: () => null };
+    return { ...inbound, summary: () => summarize(inbound) };
+}
+/**
+ * Calls a handler and reads its answer as a `Result`: a plain value succeeds and an
+ * exception fails, which `handle` retries like any handler failure.
+ */
+async function invoke(handler, ctx) {
+    let returned;
+    try {
+        returned = await handler(ctx);
+    }
+    catch (cause) {
+        return failure(cause instanceof Error ? cause : new Error(String(cause)));
+    }
+    if (isResult(returned))
+        return returned;
+    return success(returned ?? null);
+}

package/dist/fixtures/gotosocial.d.ts

@@ -0,0 +1,114 @@
+/** A GoToSocial account that approves followers by hand. */
+export declare const GOTOSOCIAL_ACTOR: {
+    "@context": (string | {
+        discoverable: string;
+        featured: {
+            "@id": string;
+            "@type": string;
+        };
+        manuallyApprovesFollowers: string;
+        toot: string;
+    })[];
+    discoverable: boolean;
+    endpoints: {
+        sharedInbox: string;
+    };
+    featured: string;
+    followers: string;
+    following: string;
+    icon: {
+        mediaType: string;
+        type: string;
+        url: string;
+    };
+    id: string;
+    inbox: string;
+    manuallyApprovesFollowers: boolean;
+    name: string;
+    outbox: string;
+    preferredUsername: string;
+    publicKey: {
+        id: string;
+        owner: string;
+        publicKeyPem: string;
+    };
+    published: string;
+    summary: string;
+    tag: never[];
+    type: string;
+    url: string;
+};
+/** A reply addressed to one audience entry each, written as plain values. */
+export declare const GOTOSOCIAL_CREATE_NOTE: {
+    "@context": (string | {
+        sensitive: string;
+    })[];
+    actor: string;
+    cc: string;
+    id: string;
+    object: {
+        attachment: never[];
+        attributedTo: string;
+        cc: string[];
+        content: string;
+        contentMap: {
+            en: string;
+        };
+        id: string;
+        inReplyTo: string;
+        interactionPolicy: {
+            canAnnounce: {
+                always: string[];
+                approvalRequired: never[];
+            };
+            canLike: {
+                always: string[];
+                approvalRequired: never[];
+            };
+            canReply: {
+                always: string[];
+                approvalRequired: never[];
+            };
+        };
+        published: string;
+        replies: {
+            first: {
+                id: string;
+                next: string;
+                partOf: string;
+                type: string;
+            };
+            id: string;
+            type: string;
+        };
+        sensitive: boolean;
+        summary: string;
+        tag: {
+            href: string;
+            name: string;
+            type: string;
+        };
+        to: string;
+        type: string;
+        url: string;
+    };
+    published: string;
+    to: string;
+    type: string;
+};
+/** A follow of the local actor, written with a string `@context`. */
+export declare const GOTOSOCIAL_FOLLOW: {
+    "@context": string;
+    actor: string;
+    id: string;
+    object: string;
+    type: string;
+};
+/** Pinned posts: an ordered collection whose items are IRIs. */
+export declare const GOTOSOCIAL_FEATURED: {
+    "@context": string;
+    id: string;
+    orderedItems: string[];
+    totalItems: number;
+    type: string;
+};