@sdxc/activitypub 0.0.0-pre.1

package/dist/errors.d.ts

@@ -0,0 +1,115 @@
+/**
+ * The failures this package answers inside a `Result`: a base with a code and a retry
+ * verdict that a job consumer acts on, the parse failure every `parse*` returns, and the
+ * fetch failure discovery and the remote resolver return, and the failure a queued
+ * federation message ends with.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Every failure of this package. `code` is stable for a caller to branch on, and
+ * `retryable` tells a job consumer whether asking again later can change the outcome.
+ *
+ * @template Code - The codes a subclass can carry.
+ */
+export declare class ActivityPubError<Code extends string = string> extends Error {
+    name: string;
+    /** Machine-readable cause, stable across releases of a subclass. */
+    readonly code: Code;
+    /** Whether a later attempt can succeed, so a job retries it rather than acknowledging. */
+    readonly retryable: boolean;
+    /**
+     * @param code - Why the operation failed.
+     * @param message - The explanation a log shows.
+     * @param options - Whether a retry can help, and the underlying error.
+     */
+    constructor(code: Code, message: string, options?: ActivityPubError.Options);
+}
+export declare namespace ActivityPubError {
+    /** How a failure is classified beyond its code. */
+    interface Options {
+        /** @default false */
+        retryable?: boolean;
+        cause?: unknown;
+    }
+}
+/**
+ * A document that is not the ActivityStreams shape asked for. Every issue found is
+ * listed with a JSON Pointer into the received document, and `message` summarizes the
+ * first; a resent copy of the same document fails the same way, so it never retries.
+ */
+export declare class ActivityPubParseError extends ActivityPubError<"invalid-document"> {
+    name: string;
+    /** What was being read: `activity`, `actor`, `object` or `collection`. */
+    readonly kind: ActivityPubParseError.Kind;
+    readonly issues: ActivityPubParseError.Issue[];
+    /**
+     * @param kind - What was being read.
+     * @param issues - Every problem found, at least one.
+     */
+    constructor(kind: ActivityPubParseError.Kind, issues: ActivityPubParseError.Issue[]);
+}
+export declare namespace ActivityPubParseError {
+    /** The document reader that failed. */
+    type Kind = "activity" | "actor" | "object" | "collection";
+    /** One place a document breaks the shape asked for. */
+    interface Issue {
+        /** A JSON Pointer into the received document; `""` for the document as a whole. */
+        at: string;
+        message: string;
+    }
+}
+/**
+ * Why a remote ActivityPub or WebFinger document could not be used. `gone` means the
+ * server answered `410` or a `Tombstone`, so a caller forgets the resource; `timeout`,
+ * `network` and a `5xx` or `429` under `http` are the outcomes a retry can change.
+ */
+export type ActivityPubFetchErrorCode = "gone" | "not-found" | "unauthorized" | "refused-url" | "too-large" | "timeout" | "network" | "invalid-document" | "id-mismatch" | "http";
+/**
+ * A remote document that could not be fetched or trusted. `url` is the document that
+ * failed, and `status` the HTTP status when a response arrived at all.
+ */
+export declare class ActivityPubFetchError extends ActivityPubError<ActivityPubFetchErrorCode> {
+    name: string;
+    readonly url: string;
+    /** The response status, or `null` when the request was refused, timed out or never connected. */
+    readonly status: number | null;
+    /**
+     * `retryable` defaults from the code and status: `timeout` and `network` always, and
+     * `http` for a `5xx` or `429`; every other outcome repeats on a retry.
+     *
+     * @param code - Why the document could not be used.
+     * @param url - The document's URL.
+     * @param message - The explanation a log shows.
+     * @param options - The status, an explicit retry verdict, and the underlying error.
+     */
+    constructor(code: ActivityPubFetchErrorCode, url: string, message: string, options?: ActivityPubFetchError.Options);
+}
+export declare namespace ActivityPubFetchError {
+    /** How a fetch failure is classified beyond its code. */
+    interface Options extends ActivityPubError.Options {
+        status?: number | null;
+    }
+}
+/**
+ * Why `Federation#process` could not finish a queued message. `retryable` and `delay` are
+ * all a job needs (retry after `delay` milliseconds, or acknowledge); `code` and `cause`
+ * keep the failure underneath, such as a `DeliveryError` or an `ActivityPubFetchError`.
+ */
+export declare class FederationError extends ActivityPubError {
+    name: string;
+    /** Which kind of message failed. */
+    readonly kind: "inbox" | "fanOut" | "deliver";
+    /**
+     * Milliseconds to wait before the retry: the backoff step for this attempt, or longer
+     * when the inbox named a `Retry-After`. `0` when the failure is not retryable.
+     */
+    readonly delay: number;
+    /**
+     * @param kind - Which kind of message failed.
+     * @param cause - The failure underneath, whose code, message and verdict this one keeps.
+     * @param delay - The wait before a retry, in milliseconds.
+     */
+    constructor(kind: FederationError["kind"], cause: ActivityPubError, delay: number);
+}

package/dist/errors.js

@@ -0,0 +1,124 @@
+/**
+ * The failures this package answers inside a `Result`: a base with a code and a retry
+ * verdict that a job consumer acts on, the parse failure every `parse*` returns, and the
+ * fetch failure discovery and the remote resolver return, and the failure a queued
+ * federation message ends with.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Every failure of this package. `code` is stable for a caller to branch on, and
+ * `retryable` tells a job consumer whether asking again later can change the outcome.
+ *
+ * @template Code - The codes a subclass can carry.
+ */
+export class ActivityPubError extends Error {
+    name = "ActivityPubError";
+    /** Machine-readable cause, stable across releases of a subclass. */
+    code;
+    /** Whether a later attempt can succeed, so a job retries it rather than acknowledging. */
+    retryable;
+    /**
+     * @param code - Why the operation failed.
+     * @param message - The explanation a log shows.
+     * @param options - Whether a retry can help, and the underlying error.
+     */
+    constructor(code, message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.code = code;
+        this.retryable = options.retryable ?? false;
+    }
+}
+/**
+ * A document that is not the ActivityStreams shape asked for. Every issue found is
+ * listed with a JSON Pointer into the received document, and `message` summarizes the
+ * first; a resent copy of the same document fails the same way, so it never retries.
+ */
+export class ActivityPubParseError extends ActivityPubError {
+    name = "ActivityPubParseError";
+    /** What was being read: `activity`, `actor`, `object` or `collection`. */
+    kind;
+    issues;
+    /**
+     * @param kind - What was being read.
+     * @param issues - Every problem found, at least one.
+     */
+    constructor(kind, issues) {
+        let first = issues[0];
+        let where = first === undefined || first.at === "" ? "" : ` at ${first.at}`;
+        let more = issues.length > 1 ? ` (and ${issues.length - 1} more)` : "";
+        super("invalid-document", `Invalid ${kind}${where}: ${first?.message ?? "the document is invalid."}${more}`);
+        this.kind = kind;
+        this.issues = issues;
+    }
+}
+/** Codes a later attempt can clear regardless of status: the deadline and the transport. */
+const RETRYABLE_FETCH_CODES = new Set(["timeout", "network"]);
+/**
+ * A remote document that could not be fetched or trusted. `url` is the document that
+ * failed, and `status` the HTTP status when a response arrived at all.
+ */
+export class ActivityPubFetchError extends ActivityPubError {
+    name = "ActivityPubFetchError";
+    url;
+    /** The response status, or `null` when the request was refused, timed out or never connected. */
+    status;
+    /**
+     * `retryable` defaults from the code and status: `timeout` and `network` always, and
+     * `http` for a `5xx` or `429`; every other outcome repeats on a retry.
+     *
+     * @param code - Why the document could not be used.
+     * @param url - The document's URL.
+     * @param message - The explanation a log shows.
+     * @param options - The status, an explicit retry verdict, and the underlying error.
+     */
+    constructor(code, url, message, options = {}) {
+        let status = options.status ?? null;
+        super(code, message, {
+            retryable: options.retryable ?? isRetryableFetch(code, status),
+            cause: options.cause,
+        });
+        this.url = url;
+        this.status = status;
+    }
+}
+/**
+ * Whether a fetch failure can clear on its own: a deadline, a dropped connection, a
+ * server error or a rate limit.
+ *
+ * @param code - The failure's code.
+ * @param status - The response status, when one arrived.
+ */
+function isRetryableFetch(code, status) {
+    if (RETRYABLE_FETCH_CODES.has(code))
+        return true;
+    if (code !== "http" || status === null)
+        return false;
+    return status === 429 || status >= 500;
+}
+/**
+ * Why `Federation#process` could not finish a queued message. `retryable` and `delay` are
+ * all a job needs (retry after `delay` milliseconds, or acknowledge); `code` and `cause`
+ * keep the failure underneath, such as a `DeliveryError` or an `ActivityPubFetchError`.
+ */
+export class FederationError extends ActivityPubError {
+    name = "FederationError";
+    /** Which kind of message failed. */
+    kind;
+    /**
+     * Milliseconds to wait before the retry: the backoff step for this attempt, or longer
+     * when the inbox named a `Retry-After`. `0` when the failure is not retryable.
+     */
+    delay;
+    /**
+     * @param kind - Which kind of message failed.
+     * @param cause - The failure underneath, whose code, message and verdict this one keeps.
+     * @param delay - The wait before a retry, in milliseconds.
+     */
+    constructor(kind, cause, delay) {
+        super(cause.code, cause.message, { retryable: cause.retryable, cause });
+        this.kind = kind;
+        this.delay = cause.retryable ? delay : 0;
+    }
+}

package/dist/federation.d.ts

@@ -0,0 +1,281 @@
+/**
+ * The ActivityPub runtime of one local actor: its documents and inbox served from `fetch`,
+ * every queued step (inbox processing, fan-out, delivery) run by `process`, and the app's
+ * handlers registered with `on`, so the actor, keys, stores and queue are wired once.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Backoff } from "@sdxc/backoff";
+import type { Cache } from "@sdxc/cache";
+import type { DurationInput } from "@sdxc/duration";
+import type { Result } from "@sdxc/result";
+import type { Schema } from "remix/data-schema";
+import type { CollectionItem } from "./collections.js";
+import type { ActivityPubFetchError } from "./errors.js";
+import type { ActorKeys } from "./keys.js";
+import type { Delivered } from "./lib/delivery-post.js";
+import type { InboxError } from "./lib/inbox-error.js";
+import type { DeleteInbound, FollowDecision, HandleOutcome, Inbound } from "./lib/inbox-handle.js";
+import type { BlockedCheck, VerifiedFetch } from "./lib/inbox-receive.js";
+import type { Summary } from "./lib/inbox-summarize.js";
+import type { Message as QueueMessage } from "./lib/messages.js";
+import type { RespondOptions as DocumentRespondOptions } from "./lib/response.js";
+import type { ActivityPub } from "./lib/types.js";
+import type { ResolverTtl } from "./remote.js";
+import type { FollowerStore, KeyProvider, LocalObjects, SeenActivities } from "./store.js";
+import { ActivityPubError, FederationError } from "./errors.js";
+import { RemoteResolver } from "./remote.js";
+/**
+ * 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 declare class Federation {
+    #private;
+    /**
+     * 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 readonly MESSAGE: Schema<unknown, Federation.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`.
+     */
+    readonly resolver: RemoteResolver;
+    /** @param options - The local actor, its keys, the stores, the cache and the queue. */
+    constructor(options: Federation.Options);
+    /**
+     * 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<T extends Federation.HandledType>(type: T | readonly T[], handler: (ctx: Federation.ContextOf<T>) => Federation.HandlerReturn<Federation.AnswerOf<T>>): 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;
+     */
+    fetch(request: Request): Promise<Response | 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;
+     */
+    respond(request: Request, document: ActivityPub.Draft<ActivityPub.Document>, options?: Federation.RespondOptions): Promise<Response | null>;
+    /**
+     * 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: Request): Promise<Result<VerifiedFetch, InboxError>>;
+    /**
+     * 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 });
+     */
+    process(message: Federation.Message, options?: Federation.ProcessOptions): Promise<Result<Federation.Outcome, FederationError>>;
+    /**
+     * 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] });
+     */
+    publish(activity: ActivityPub.Draft<ActivityPub.Activity> | string): Promise<Result<void, ActivityPubError>>;
+    /**
+     * 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: string): Promise<Result<ActivityPub.Actor, ActivityPubFetchError>>;
+}
+export declare namespace Federation {
+    /** What a `Federation` is built from. */
+    interface Options {
+        /**
+         * The local actor's document. Its `inbox`, `endpoints.sharedInbox`, `outbox`,
+         * `followers`, `following` and `id` are the URLs `fetch` answers, and Follows of it
+         * are what the inbox keeps followers for.
+         */
+        actor: ActivityPub.Actor;
+        /** The actor's keys, or a provider holding the keys of every actor the app hosts. */
+        keys: ActorKeys | KeyProvider;
+        stores: Stores;
+        /** Remote documents, accepted signature schemes and failing origins; a failing cache costs a fetch. */
+        cache: Cache;
+        /** Sent on every outbound request; some instances refuse requests without one. */
+        userAgent: string;
+        /** Where inbox, fan-out and delivery messages go; the app hands each back to `process`. */
+        queue: Queue;
+        /**
+         * Whether requests from a host are refused: it cannot deliver, follow, or receive.
+         * @default () => false
+         */
+        blocked?: BlockedCheck;
+        /** Pages of the outbox collection; without it the outbox is empty. */
+        outbox?: (cursor: string | null) => Promise<Result<OutboxPage, Error>>;
+        /** Requires a signed GET for the collections and for `respond` (secure mode). @default false */
+        authorizedFetch?: boolean;
+        inbox?: InboxOptions;
+        resolver?: ResolverOptions;
+        delivery?: DeliveryOptions;
+        collections?: CollectionOptions;
+        /**
+         * The wait before each retry of a failed message, by attempt. The default covers about
+         * 21 hours over five retries.
+         * @default DELIVERY_BACKOFF
+         */
+        backoff?: Backoff;
+        /** How long a processed activity id is remembered to skip redeliveries. @default "1 day" */
+        seenTtl?: DurationInput;
+        /** The clock signatures, failure windows and `receivedAt` are read from. @default () => new Date() */
+        now?: () => Date;
+    }
+    /** The app's storage, each implementing the interface the package calls. */
+    interface Stores {
+        followers: FollowerStore;
+        seen: SeenActivities;
+        objects: LocalObjects;
+    }
+    /**
+     * The app's queue. Each message is plain JSON under 128 KB, and a job declared with
+     * `Federation.MESSAGE` reads it back. A failure or an exception makes the step that
+     * enqueued it fail as retryable.
+     */
+    interface Queue {
+        enqueue(message: Message): Promise<Result<void, Error> | void>;
+        /** Writes a fan-out's deliveries in one call; without it they go one by one. */
+        enqueueMany?(messages: Message[]): Promise<Result<void, Error> | void>;
+    }
+    /** One page of the outbox, newest first. */
+    interface OutboxPage {
+        /** Activities, usually each post's `Create`, or their IRIs. */
+        items: CollectionItem[];
+        /** The cursor of the following page, `null` on the last one. */
+        next: string | null;
+        /** The outbox's size, published on the collection. */
+        totalItems?: number | null;
+    }
+    /** How the inbox reads a POST. */
+    interface InboxOptions {
+        /** Bodies past this answer `413`. @default 102400 */
+        maxBytes?: number;
+        /** How old a signature may be, plus five minutes of clock skew. @default "1 hour" */
+        maxAge?: DurationInput;
+    }
+    /** How remote documents are fetched. */
+    interface ResolverOptions {
+        /** Signs every GET with the actor's keys, as GoToSocial and secure-mode Mastodon require. @default true */
+        signed?: boolean;
+        ttl?: ResolverTtl;
+        /** @default "10 seconds" */
+        timeout?: DurationInput;
+        /** @default 1048576 */
+        maxBytes?: number;
+    }
+    /** How activities are delivered. */
+    interface DeliveryOptions {
+        /** The deadline of each POST. @default "15 seconds" */
+        timeout?: DurationInput;
+        /** Followers' inboxes read per store page, and the most deliveries per enqueue. @default 100 */
+        pageSize?: number;
+    }
+    /** How the actor's collections are served. */
+    interface CollectionOptions {
+        /** Followers per page of the followers collection. @default 50 */
+        pageSize?: number;
+    }
+    /** How `process` runs a message. */
+    interface ProcessOptions {
+        /** The job's attempt, starting at 1. Past the first, a redelivery check is skipped. @default 1 */
+        attempts?: number;
+    }
+    /** How `respond` answers a document. */
+    type RespondOptions = Pick<DocumentRespondOptions, "cache" | "headers" | "status">;
+    /** Every message federation enqueues, told apart by `kind`. */
+    type Message = QueueMessage;
+    /** The activity types the app can register a handler for. */
+    type HandledType = "Follow" | "Undo" | "Create" | "Update" | "Delete" | "Like" | "Announce" | "Accept" | "Reject" | "Move";
+    /** A verified activity as a handler receives it, with its response summary. */
+    interface Context<A extends ActivityPub.Activity = ActivityPub.Activity> extends Inbound<A> {
+        /**
+         * A reply, mention, like or boost of local content in the shape a Webmention is
+         * stored in, with remote HTML sanitized; `null` for any other activity.
+         */
+        summary(): Summary | null;
+    }
+    /** A verified `Delete`; `actor` is `null` when the deleted account's document is gone. */
+    interface DeleteContext extends DeleteInbound {
+        /** A deletion summarizes as nothing, so this is always `null`. */
+        summary(): Summary | null;
+    }
+    /** The context a handler for `T` receives. */
+    type ContextOf<T extends HandledType> = T extends "Delete" ? DeleteContext : Context;
+    /** What a handler for `T` answers: a Follow decision, or nothing. */
+    type AnswerOf<T extends HandledType> = T extends "Follow" ? FollowDecision | null : void;
+    /** A handler's return: the answer or a `Result` of it, sync or async. */
+    type HandlerReturn<T> = T | Result<T, Error> | Promise<T | Result<T, Error>>;
+    /** What `process` did with a message. */
+    type Outcome = ({
+        kind: "inbox";
+    } & HandleOutcome) | {
+        kind: "fanOut";
+        inboxes: number;
+        skipped: number;
+    } | ({
+        kind: "deliver";
+    } & Delivered);
+}