@sdxc/activitypub 0.0.0-pre.1

package/dist/lib/fetch.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The one way this package reads a remote document: through `@sdxc/outbound`, so every
+ * hop is checked and resolved to public addresses, within a deadline and a size cap, with
+ * the response status mapped to the `ActivityPubFetchError` code a caller branches on.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { DurationInput } from "@sdxc/duration";
+import type { Result } from "@sdxc/result";
+import { ActivityPubFetchError } from "../errors.js";
+/** Long enough for a slow instance, short enough that an inbox request still answers. */
+export declare const DEFAULT_TIMEOUT: DurationInput;
+/** An actor with a long bio and many profile fields stays far below a megabyte. */
+export declare const DEFAULT_MAX_BYTES: number;
+/** How a document is requested. */
+export interface FetchTextOptions {
+    /** Sent on every hop of the redirect chain. */
+    headers: Headers;
+    timeout: DurationInput;
+    maxBytes: number;
+}
+/** A successful response's body, and the URL the redirect chain ended at. */
+export interface FetchedText {
+    text: string;
+    url: URL;
+}
+/** The final response of a chain whose status may not be a success, before its body is read. */
+export interface Answered {
+    response: Response;
+    url: URL;
+}
+/**
+ * Requests a URL and answers the final response whatever its status, with every hop's
+ * host resolved and refused unless all its addresses are public.
+ *
+ * @param url - The URL to request.
+ * @param options - The headers, deadline and cap.
+ */
+export declare function request(url: string, options: FetchTextOptions): Promise<Result<Answered, ActivityPubFetchError>>;
+/**
+ * Reads a successful response's body within the cap, and fails any other status with the
+ * code that says what a caller does next: forget the resource on `gone`, sign the request
+ * on `unauthorized`, retry on a `5xx` or `429` under `http`.
+ *
+ * @param url - The URL that was asked for, which the error names.
+ * @param answered - The final response and where the chain ended.
+ * @param maxBytes - The body cap.
+ */
+export declare function readSuccess(url: string, answered: Answered, maxBytes: number): Promise<Result<FetchedText, ActivityPubFetchError>>;
+/**
+ * Requests a URL and reads its body when it answers with a success.
+ *
+ * @param url - The URL to request.
+ * @param options - The headers, deadline and cap.
+ */
+export declare function fetchText(url: string, options: FetchTextOptions): Promise<Result<FetchedText, ActivityPubFetchError>>;
+/**
+ * Decodes a body as one JSON object, the only shape an ActivityStreams or JRD document has.
+ *
+ * @param url - The document's URL, for the error.
+ * @param text - The body.
+ */
+export declare function decodeObject(url: string, text: string): Result<Record<string, unknown>, ActivityPubFetchError>;

package/dist/lib/fetch.js

@@ -0,0 +1,103 @@
+import { follow, readText, release } from "@sdxc/outbound";
+import { failure, isFailure, success } from "@sdxc/result";
+import { ActivityPubFetchError } from "../errors.js";
+/** Long enough for a slow instance, short enough that an inbox request still answers. */
+export const DEFAULT_TIMEOUT = "10 seconds";
+/** An actor with a long bio and many profile fields stays far below a megabyte. */
+export const DEFAULT_MAX_BYTES = 1024 * 1024;
+/**
+ * Requests a URL and answers the final response whatever its status, with every hop's
+ * host resolved and refused unless all its addresses are public.
+ *
+ * @param url - The URL to request.
+ * @param options - The headers, deadline and cap.
+ */
+export async function request(url, options) {
+    let followed = await follow(url, {
+        headers: options.headers,
+        timeout: options.timeout,
+        resolve: true,
+    });
+    if (isFailure(followed))
+        return failure(fromOutbound(url, followed.error));
+    return success({ response: followed.data.response, url: followed.data.url });
+}
+/**
+ * Reads a successful response's body within the cap, and fails any other status with the
+ * code that says what a caller does next: forget the resource on `gone`, sign the request
+ * on `unauthorized`, retry on a `5xx` or `429` under `http`.
+ *
+ * @param url - The URL that was asked for, which the error names.
+ * @param answered - The final response and where the chain ended.
+ * @param maxBytes - The body cap.
+ */
+export async function readSuccess(url, answered, maxBytes) {
+    let { response } = answered;
+    if (!response.ok) {
+        release(response.body);
+        let status = response.status;
+        return failure(new ActivityPubFetchError(statusCode(status), url, `${url} answered ${status}`, { status }));
+    }
+    let body = await readText(response, { maxBytes });
+    if (isFailure(body))
+        return failure(fromOutbound(url, body.error, response.status));
+    return success({ text: body.data.text, url: answered.url });
+}
+/**
+ * Requests a URL and reads its body when it answers with a success.
+ *
+ * @param url - The URL to request.
+ * @param options - The headers, deadline and cap.
+ */
+export async function fetchText(url, options) {
+    let answered = await request(url, options);
+    if (isFailure(answered))
+        return answered;
+    return readSuccess(url, answered.data, options.maxBytes);
+}
+/**
+ * Decodes a body as one JSON object, the only shape an ActivityStreams or JRD document has.
+ *
+ * @param url - The document's URL, for the error.
+ * @param text - The body.
+ */
+export function decodeObject(url, text) {
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch (cause) {
+        return failure(new ActivityPubFetchError("invalid-document", url, `${url} is not JSON`, { cause }));
+    }
+    if (typeof json !== "object" || json === null || Array.isArray(json)) {
+        return failure(new ActivityPubFetchError("invalid-document", url, `${url} is not a JSON object`));
+    }
+    return success(json);
+}
+/** The code a non-success status maps to. */
+function statusCode(status) {
+    if (status === 410)
+        return "gone";
+    if (status === 404)
+        return "not-found";
+    if (status === 401 || status === 403)
+        return "unauthorized";
+    return "http";
+}
+/**
+ * Maps an outbound refusal or transport failure to the fetch error, keeping the status
+ * when a response had already arrived.
+ *
+ * @param url - The URL that was asked for.
+ * @param error - What `@sdxc/outbound` answered.
+ * @param status - The response status, when the failure came while reading its body.
+ */
+function fromOutbound(url, error, status) {
+    let code = error.code === "too-large" || error.code === "timeout" || error.code === "network"
+        ? error.code
+        : "refused-url";
+    return new ActivityPubFetchError(code, url, error.message, {
+        status: status ?? null,
+        cause: error,
+    });
+}

package/dist/lib/inbox-error.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Why an inbound request was refused: one code per verification step, each with the HTTP
+ * status the inbox answers, so a sender learns from a `401` to fall back to another
+ * signature scheme while the log keeps the reason the response leaves out.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { ActivityPubError } from "../errors.js";
+/**
+ * The step of `receive` or `verifyFetch` that stopped a request. `ignored` is the one code
+ * answered with `202`: a `Delete` of an account whose key is gone, which no one can verify
+ * and every retry would repeat.
+ */
+export type InboxErrorCode = "unsupported-media-type" | "too-large" | "invalid-activity" | "blocked" | "unsigned" | "digest-mismatch" | "stale-signature" | "invalid-signature" | "key-unavailable" | "actor-mismatch" | "ignored";
+/**
+ * The text a response carries for each code. It names the failed rule and nothing a
+ * sender could probe the verifier with; the error's own `message` and `cause` hold the rest.
+ */
+export declare const PUBLIC_MESSAGE: Record<InboxErrorCode, string>;
+/**
+ * A request the inbox refuses, with the status to answer it with. It never retries: the
+ * same request fails the same way, and only the sender can change it.
+ */
+export declare class InboxError extends ActivityPubError<InboxErrorCode> {
+    name: string;
+    /** The HTTP status `toResponse` answers with. */
+    readonly status: number;
+    /**
+     * @param code - The step that failed.
+     * @param message - The explanation a log shows; responses carry a fixed text instead.
+     * @param options - The underlying error.
+     */
+    constructor(code: InboxErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+    /**
+     * The response that refuses the request: the error's status and a fixed text per code,
+     * so a sender sees which rule failed and never how the verifier failed. `ignored`
+     * answers an empty `202`.
+     *
+     * @example if (isFailure(verified)) return verified.error.toResponse();
+     */
+    toResponse(): Response;
+}

package/dist/lib/inbox-error.js

@@ -0,0 +1,74 @@
+/**
+ * Why an inbound request was refused: one code per verification step, each with the HTTP
+ * status the inbox answers, so a sender learns from a `401` to fall back to another
+ * signature scheme while the log keeps the reason the response leaves out.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { ActivityPubError } from "../errors.js";
+/** The status each code is answered with. */
+const STATUS = {
+    "unsupported-media-type": 415,
+    "too-large": 413,
+    "invalid-activity": 400,
+    blocked: 403,
+    unsigned: 401,
+    "digest-mismatch": 401,
+    "stale-signature": 401,
+    "invalid-signature": 401,
+    "key-unavailable": 401,
+    "actor-mismatch": 401,
+    ignored: 202,
+};
+/**
+ * The text a response carries for each code. It names the failed rule and nothing a
+ * sender could probe the verifier with; the error's own `message` and `cause` hold the rest.
+ */
+export const PUBLIC_MESSAGE = {
+    "unsupported-media-type": "The body must be application/activity+json or application/ld+json.",
+    "too-large": "The body is too large.",
+    "invalid-activity": "The body is not an ActivityStreams activity.",
+    blocked: "Requests from this server are not accepted.",
+    unsigned: "The request must carry an HTTP signature.",
+    "digest-mismatch": "The body does not match the signed digest.",
+    "stale-signature": "The signature is outside the accepted time window.",
+    "invalid-signature": "The signature could not be verified.",
+    "key-unavailable": "The signature could not be verified.",
+    "actor-mismatch": "The signature does not belong to the activity's actor.",
+    ignored: "",
+};
+/**
+ * A request the inbox refuses, with the status to answer it with. It never retries: the
+ * same request fails the same way, and only the sender can change it.
+ */
+export class InboxError extends ActivityPubError {
+    name = "InboxError";
+    /** The HTTP status `toResponse` answers with. */
+    status;
+    /**
+     * @param code - The step that failed.
+     * @param message - The explanation a log shows; responses carry a fixed text instead.
+     * @param options - The underlying error.
+     */
+    constructor(code, message, options = {}) {
+        super(code, message, { cause: options.cause });
+        this.status = STATUS[code];
+    }
+    /**
+     * The response that refuses the request: the error's status and a fixed text per code,
+     * so a sender sees which rule failed and never how the verifier failed. `ignored`
+     * answers an empty `202`.
+     *
+     * @example if (isFailure(verified)) return verified.error.toResponse();
+     */
+    toResponse() {
+        let text = PUBLIC_MESSAGE[this.code];
+        if (text === "")
+            return new Response(null, { status: this.status });
+        return new Response(text, {
+            status: this.status,
+            headers: { "content-type": "text/plain; charset=utf-8" },
+        });
+    }
+}

package/dist/lib/inbox-handle.d.ts

@@ -0,0 +1,119 @@
+/**
+ * The background half of an inbox: the work the protocol itself requires for each verified
+ * activity (followers kept, Accept sent, ownership and relevance checked) before the app's
+ * own handler sees it, so an app writes only what it does with a reply, a like or a boost.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { DurationInput } from "@sdxc/duration";
+import type { Result } from "@sdxc/result";
+import type { Resolver } from "../remote.js";
+import type { FollowerStore, KeyProvider, LocalObjects, SeenActivities } from "../store.js";
+import { ActivityPubError } from "../errors.js";
+import type { BlockedCheck, Received, Verification } from "./inbox-receive.js";
+import type { ActivityPub } from "./types.js";
+/** What the app answers a Follow with: approve it, refuse it, or decide later. */
+export type FollowDecision = "accept" | "reject" | "pending";
+/** A verified activity as an app's handler receives it, after the package's own checks. */
+export interface Inbound<A extends ActivityPub.Activity = ActivityPub.Activity> {
+    activity: A;
+    /** The sender, fetched through the resolver; trusted, unlike any actor the activity embeds. */
+    actor: ActivityPub.Actor;
+    /** The origin of the actor, which every ownership check compared against. */
+    origin: string;
+    verification: Verification;
+    /**
+     * What the activity acts on, already trusted: a Create's or Update's object, the local
+     * object a Like or Announce names, the activity an Undo reverts, the Follow an Accept
+     * answers, a Move's target actor. `null` when there is nothing to resolve.
+     */
+    object: ActivityPub.Object | null;
+    /** The local object or actor the activity concerns, which a reply or like attaches to. */
+    target: string | null;
+    receivedAt: Date;
+}
+/**
+ * A verified `Delete`. A deleted account's own document is usually gone already, so
+ * `actor` is `null` when it could not be fetched.
+ */
+export interface DeleteInbound extends Omit<Inbound, "actor"> {
+    actor: ActivityPub.Actor | null;
+    /** What was deleted: one object by its id, or the whole account. */
+    deleted: {
+        kind: "object" | "actor";
+        id: string;
+    };
+}
+/**
+ * The app's side of each activity, each called once the package has done the protocol's
+ * work. A failure is retried, so a handler must tolerate seeing an activity twice.
+ */
+export interface Handlers {
+    /** Answers the Follow; `null` keeps the default, which `manuallyApprovesFollowers` sets. */
+    follow(inbound: Inbound): Promise<Result<FollowDecision | null, Error>>;
+    /** An Undo whose reverted activity was the sender's own; a Follow is already removed. */
+    undo(inbound: Inbound): Promise<Result<void, Error>>;
+    /** A post by the sender that replies to, quotes or mentions something local. */
+    create(inbound: Inbound): Promise<Result<void, Error>>;
+    /** An edit of such a post, or of the sender's own actor (then `object` is the actor). */
+    update(inbound: Inbound): Promise<Result<void, Error>>;
+    delete(inbound: DeleteInbound): Promise<Result<void, Error>>;
+    /** A Like of a local object; Pleroma's `EmojiReact` arrives here too. */
+    like(inbound: Inbound): Promise<Result<void, Error>>;
+    /** A boost of a local object. */
+    announce(inbound: Inbound): Promise<Result<void, Error>>;
+    /** A remote actor approved a Follow a local actor sent. */
+    accept(inbound: Inbound): Promise<Result<void, Error>>;
+    reject(inbound: Inbound): Promise<Result<void, Error>>;
+    /** The sender moved to `object`, which lists it in `alsoKnownAs` and that it names in `movedTo`. */
+    move(inbound: Inbound): Promise<Result<void, Error>>;
+}
+/** What `handle` needs: the local actor, the app's stores, and how to send an answer. */
+export interface HandleOptions {
+    /** The local actor's document, which Follows name and Accepts are sent as. */
+    actor: ActivityPub.Actor;
+    /** Tells a local actor from a remote one, beyond `actor` itself. */
+    keys: KeyProvider;
+    followers: FollowerStore;
+    seen: SeenActivities;
+    objects: LocalObjects;
+    resolver: Resolver;
+    blocked: BlockedCheck;
+    /** Queues a serialized activity for delivery to one inbox, usually as a delivery job. */
+    send: (activity: string, inbox: string) => Promise<Result<void, Error>>;
+    on?: Partial<Handlers>;
+    /** @default "1 day" */
+    seenTtl?: DurationInput;
+    /**
+     * The job's attempt, starting at 1. Past the first the claim is skipped, so a retry of
+     * a failed attempt is never mistaken for a redelivery. @default 1
+     */
+    attempts?: number;
+}
+/** Why an activity was acknowledged without reaching a handler, or how a Follow ended. */
+export type HandleReason = "blocked" | "actor-unavailable" | "not-addressed" | "not-owner" | "unrelated" | "unverifiable" | "unhandled" | "rejected" | "pending";
+/** What `handle` did with an activity; every outcome is acknowledged, never retried. */
+export interface HandleOutcome {
+    /** `processed` ran the package's work and the handler, `duplicate` was claimed before. */
+    status: "processed" | "duplicate" | "ignored";
+    type: string;
+    reason: HandleReason | null;
+}
+/**
+ * Processes a verified activity. It claims the id in `seen` (a store failure is logged and
+ * processing goes on, since every step is idempotent), re-reads the activity, does the work
+ * the protocol requires for its type, then calls the app's handler for it.
+ *
+ * The sender is the document whose id is the activity's actor, and an object another
+ * origin embeds is fetched from its own origin (FEP-c7d3). A failure is retryable when a
+ * remote server, a store, a handler or `send` failed transiently; any other is acknowledged.
+ *
+ * @param input - What `receive` answered, as the job read it back from the queue.
+ * @param options - The local actor, the stores, the resolver, `send` and the handlers.
+ * @returns What happened to the activity.
+ * @example
+ * let outcome = await handle(ctx.input, { actor, keys, followers, seen, objects, resolver, blocked, send, on });
+ * if (isFailure(outcome) && outcome.error.retryable) return ctx.retry({ cause: outcome.error });
+ */
+export declare function handle(input: Received, options: HandleOptions): Promise<Result<HandleOutcome, ActivityPubError>>;