@sdxc/activitypub 0.0.0-pre.1

package/dist/memory.js

@@ -0,0 +1,146 @@
+/**
+ * In-memory implementations of every store the package calls, for tests and for a local
+ * server that needs no persistence. They pass the conformance suite, so a test that runs
+ * against them exercises the same contracts a production store is held to.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { toMs } from "@sdxc/duration";
+import { failure, success } from "@sdxc/result";
+/** Matches a cursor this module wrote: the decimal offset of the next item. */
+const OFFSET_CURSOR = /^(0|[1-9]\d*)$/;
+/**
+ * The page of `items` a cursor and limit select. The cursor is the offset of the page's first
+ * item, so pages over a list nobody writes to visit every item exactly once.
+ */
+function page(items, cursor, limit) {
+    if (!Number.isInteger(limit) || limit < 1) {
+        return failure(new RangeError(`A page limit must be a positive integer, got ${limit}.`));
+    }
+    let start = 0;
+    if (cursor !== null) {
+        if (!OFFSET_CURSOR.test(cursor)) {
+            return failure(new TypeError(`"${cursor}" is not a cursor this store wrote.`));
+        }
+        start = Number(cursor);
+    }
+    let end = start + limit;
+    return success({
+        items: items.slice(start, end),
+        next: end < items.length ? String(end) : null,
+    });
+}
+/** The origin of `url`, or `null` for a string no follower id from a parsed actor could be. */
+function originOf(url) {
+    return URL.parse(url)?.origin ?? null;
+}
+/**
+ * Followers held in insertion order, so every listing is stable across pages. A repeated `put`
+ * keeps the follower's position, and every read returns a copy the caller may change freely.
+ */
+export class MemoryFollowerStore {
+    #followers = new Map();
+    /** @param followers Followers the store starts with, as if each had been `put` in order. */
+    constructor(followers = []) {
+        for (let follower of followers)
+            this.#followers.set(keyOf(follower.actor, follower.id), { ...follower });
+    }
+    /** Inserts or replaces by `(actor, id)`, refreshing inbox, shared inbox, `followId` and state. */
+    async put(follower) {
+        this.#followers.set(keyOf(follower.actor, follower.id), { ...follower });
+        return success(undefined);
+    }
+    /** The follower in either state, or `null` when `id` does not follow `actor`. */
+    async get(actor, id) {
+        let follower = this.#followers.get(keyOf(actor, id));
+        return success(follower ? { ...follower } : null);
+    }
+    /** Succeeds whether or not the follower existed. */
+    async remove(actor, id) {
+        this.#followers.delete(keyOf(actor, id));
+        return success(undefined);
+    }
+    /** Drops followers of every local actor whose inbox or shared inbox is `inbox`. */
+    async removeInbox(inbox) {
+        for (let [key, follower] of this.#followers) {
+            if (follower.inbox === inbox || follower.sharedInbox === inbox)
+                this.#followers.delete(key);
+        }
+        return success(undefined);
+    }
+    /** Accepted followers of `actor` in insertion order, narrowed to `origin` when given. */
+    async list(actor, options) {
+        let followers = this.#accepted(actor);
+        if (options.origin !== undefined) {
+            let origin = options.origin;
+            followers = followers.filter((follower) => originOf(follower.id) === origin);
+        }
+        return page(followers.map((follower) => ({ ...follower })), options.cursor, options.limit);
+    }
+    /** Accepted followers of `actor`, the number the followers collection publishes. */
+    async count(actor) {
+        return success(this.#accepted(actor).length);
+    }
+    /** Each distinct `sharedInbox ?? inbox` once, in the order its first follower was added. */
+    async inboxes(actor, options) {
+        let targets = new Set(this.#accepted(actor).map((one) => one.sharedInbox ?? one.inbox));
+        return page([...targets], options.cursor, options.limit);
+    }
+    /** The accepted followers of `actor`, in insertion order. */
+    #accepted(actor) {
+        return [...this.#followers.values()].filter((follower) => follower.actor === actor && follower.state === "accepted");
+    }
+}
+/** The map key of a follower; the separator cannot appear inside an IRI. */
+function keyOf(actor, id) {
+    return `${actor} ${id}`;
+}
+/** Claimed activity ids, each held until its TTL passes and then claimable again. */
+export class MemorySeenActivities {
+    #expires = new Map();
+    #now;
+    /** @param options The clock claims are timed against. */
+    constructor(options = {}) {
+        this.#now = options.now ?? Date.now;
+    }
+    /** Fails on a TTL `@sdxc/duration` cannot read, so a mistyped TTL surfaces as an error. */
+    async claim(id, ttl) {
+        let ms = toMs(ttl);
+        if (!Number.isFinite(ms) || ms < 0) {
+            return failure(new RangeError(`"${String(ttl)}" is not a duration a claim can last.`));
+        }
+        let now = this.#now();
+        for (let [seen, expires] of this.#expires)
+            if (expires <= now)
+                this.#expires.delete(seen);
+        if (this.#expires.has(id))
+            return success(false);
+        this.#expires.set(id, now + ms);
+        return success(true);
+    }
+}
+/** A fixed set of objects the app serves, found by their `id`. */
+export class MemoryLocalObjects {
+    #objects;
+    /** @param objects The objects served; a later one with a repeated `id` wins. */
+    constructor(objects = []) {
+        this.#objects = new Map(objects.map((object) => [object.id, object]));
+    }
+    /** The object served under `id`, or `null` for any other IRI. */
+    async find(id) {
+        return success(this.#objects.get(id) ?? null);
+    }
+}
+/** A fixed set of hosted actors' keys, found by actor id. */
+export class MemoryKeyProvider {
+    #keys;
+    /** @param keys The keys of every hosted actor; a later entry for the same actor wins. */
+    constructor(keys = []) {
+        this.#keys = new Map(keys.map((one) => [one.actor, one]));
+    }
+    /** The actor's keys, or `null` for an actor this provider does not host. */
+    async keysOf(actor) {
+        return success(this.#keys.get(actor) ?? null);
+    }
+}

package/dist/remote.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Fetching remote actors, keys and objects safely: every request through
+ * `@sdxc/outbound` within a deadline and a size cap, signed when the app asks for
+ * authorized fetch, each document checked against the URL it came from, and cached.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Cache } from "@sdxc/cache";
+import type { DurationInput } from "@sdxc/duration";
+import type { Result } from "@sdxc/result";
+import type { ActorKeys } from "./keys.js";
+import type { ActivityPub } from "./lib/types.js";
+import type { KeyProvider } from "./store.js";
+import { ActivityPubFetchError } from "./errors.js";
+/**
+ * Who signs the resolver's GETs: a local actor and its keys, or the provider that holds
+ * them, read on each request; a provider holding no keys for the actor leaves GETs unsigned.
+ */
+export interface ResolverSigner {
+    actor: string;
+    keys: ActorKeys | KeyProvider;
+}
+/** How long a fetched document is reused, by what it was fetched as. */
+export interface ResolverTtl {
+    /** @default "1 day" */
+    actor?: DurationInput;
+    /** @default "1 hour" */
+    object?: DurationInput;
+}
+/** What a `RemoteResolver` is built from. */
+export interface ResolverOptions {
+    /** Remote documents, kept as JSON under `activitypub:doc:<iri>`; a failing store is a miss. */
+    cache: Cache;
+    /** Signs every GET (authorized fetch), which secure-mode Mastodon and GoToSocial require. */
+    signer?: ResolverSigner;
+    /** Sent on every request; some instances refuse requests without one. */
+    userAgent: string;
+    ttl?: ResolverTtl;
+    /** One deadline for the redirect chain and the body. @default "10 seconds" */
+    timeout?: DurationInput;
+    /** @default 1048576 */
+    maxBytes?: number;
+}
+/** How one lookup treats the cache. */
+export interface ResolveOptions {
+    /** Skips the cached copy and refetches, storing what arrives. @default false */
+    fresh?: boolean;
+}
+/** A verified key: the actor that owns it and publishes it, and the key itself. */
+export interface ResolvedKey {
+    /** The owning actor's id, which an inbox compares with `activity.actor`. */
+    owner: string;
+    /** A verify-only key for `@sdxc/http-signatures`'s `verify`. */
+    publicKey: CryptoKey;
+    actor: ActivityPub.Actor;
+}
+/**
+ * Reads remote ActivityPub documents. Every method answers an `ActivityPubFetchError`
+ * rather than throwing, and `gone` means the resource was deleted: its cache entry is
+ * already evicted, so the caller forgets it too. `RemoteResolver` is the implementation;
+ * a test may supply its own.
+ */
+export interface Resolver {
+    /** An actor, fetched at its id. */
+    actor(iri: string, options?: ResolveOptions): Promise<Result<ActivityPub.Actor, ActivityPubFetchError>>;
+    /**
+     * The key a signature's `keyId` names, resolved to the actor that publishes it. The
+     * key's `owner` must be that actor and the actor must list the key, so a key document
+     * cannot claim an actor that never vouched for it.
+     */
+    key(keyId: string, options?: ResolveOptions): Promise<Result<ResolvedKey, ActivityPubFetchError>>;
+    /** An object or an activity; one with an `actor` member reads as an activity. */
+    object(iri: string, options?: ResolveOptions): Promise<Result<ActivityPub.Object | ActivityPub.Activity, ActivityPubFetchError>>;
+    /** The decoded document at `iri` after the same checks, for a shape no reader models. */
+    document(iri: string, options?: ResolveOptions): Promise<Result<Record<string, unknown>, ActivityPubFetchError>>;
+    /** Forgets the cached copy of `iri`, as after an actor's `Update` or `Delete`. */
+    evict(iri: string): Promise<void>;
+}
+/**
+ * Reads remote documents through `@sdxc/outbound` and the app's cache. A document is
+ * accepted only when its `id` has the origin the redirect chain ended at, so only that
+ * origin can speak for an id, and a `410` or a `Tombstone` answers `gone`.
+ *
+ * @example let resolver = new RemoteResolver({ cache, signer: { actor: ACTOR_ID, keys }, userAgent: USER_AGENT });
+ */
+export declare class RemoteResolver implements Resolver {
+    #private;
+    /** @param options - The cache, the optional signer, the `User-Agent`, and the bounds. */
+    constructor(options: ResolverOptions);
+    /** An actor, fetched at its id. */
+    actor(iri: string, options?: ResolveOptions): Promise<Result<ActivityPub.Actor, ActivityPubFetchError>>;
+    /**
+     * The key a signature's `keyId` names, resolved to the actor that publishes it. The
+     * key's `owner` must be that actor and the actor must list the key, so a key document
+     * cannot claim an actor that never vouched for it.
+     */
+    key(keyId: string, options?: ResolveOptions): Promise<Result<ResolvedKey, ActivityPubFetchError>>;
+    /** An object or an activity; one with an `actor` member reads as an activity. */
+    object(iri: string, options?: ResolveOptions): Promise<Result<ActivityPub.Object | ActivityPub.Activity, ActivityPubFetchError>>;
+    /** The decoded document at `iri` after the same checks, for a shape no reader models. */
+    document(iri: string, options?: ResolveOptions): Promise<Result<Record<string, unknown>, ActivityPubFetchError>>;
+    /** Drops both spellings of the entry, so a fragment never keeps a deleted copy alive. */
+    evict(iri: string): Promise<void>;
+}

package/dist/remote.js

@@ -0,0 +1,262 @@
+import { sign } from "@sdxc/http-signatures";
+import { release } from "@sdxc/outbound";
+import { failure, isFailure, isSuccess, success } from "@sdxc/result";
+import { ActivityPubFetchError } from "./errors.js";
+import { importPublicKey } from "./keys.js";
+import { ACTIVITY_ACCEPT } from "./lib/constants.js";
+import { DEFAULT_MAX_BYTES, DEFAULT_TIMEOUT, decodeObject, readSuccess, request, } from "./lib/fetch.js";
+import { parseActivity, parseActor, parseObject } from "./lib/parse.js";
+/** Mastodon refetches an actor about once a day, so a profile edit reaches it as fast. */
+const DEFAULT_ACTOR_TTL = "1 day";
+/** Short enough that an edited post is seen again within the hour. */
+const DEFAULT_OBJECT_TTL = "1 hour";
+/** The namespace of every cache entry, so the resolver shares a store with anything else. */
+const CACHE_PREFIX = "activitypub:doc:";
+/**
+ * Reads remote documents through `@sdxc/outbound` and the app's cache. A document is
+ * accepted only when its `id` has the origin the redirect chain ended at, so only that
+ * origin can speak for an id, and a `410` or a `Tombstone` answers `gone`.
+ *
+ * @example let resolver = new RemoteResolver({ cache, signer: { actor: ACTOR_ID, keys }, userAgent: USER_AGENT });
+ */
+export class RemoteResolver {
+    #options;
+    #actorTtl;
+    #objectTtl;
+    #timeout;
+    #maxBytes;
+    /** @param options - The cache, the optional signer, the `User-Agent`, and the bounds. */
+    constructor(options) {
+        this.#options = options;
+        this.#actorTtl = options.ttl?.actor ?? DEFAULT_ACTOR_TTL;
+        this.#objectTtl = options.ttl?.object ?? DEFAULT_OBJECT_TTL;
+        this.#timeout = options.timeout ?? DEFAULT_TIMEOUT;
+        this.#maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+    }
+    /** An actor, fetched at its id. */
+    async actor(iri, options) {
+        let json = await this.#load(iri, this.#actorTtl, options);
+        if (isFailure(json))
+            return json;
+        return readActor(iri, json.data);
+    }
+    /**
+     * The key a signature's `keyId` names, resolved to the actor that publishes it. The
+     * key's `owner` must be that actor and the actor must list the key, so a key document
+     * cannot claim an actor that never vouched for it.
+     */
+    async key(keyId, options) {
+        let json = await this.#load(keyId, this.#actorTtl, options);
+        if (isFailure(json))
+            return json;
+        let actor;
+        let asActor = parseActor(json.data);
+        if (isSuccess(asActor)) {
+            actor = asActor.data;
+        }
+        else {
+            let owner = claimedOwner(json.data, keyId);
+            if (owner === null) {
+                return failure(new ActivityPubFetchError("invalid-document", keyId, `${keyId} is neither an actor nor a key with an owner`));
+            }
+            let fetched = await this.actor(owner, options);
+            if (isFailure(fetched))
+                return fetched;
+            actor = fetched.data;
+        }
+        let publicKey = actor.publicKey;
+        if (publicKey === null || publicKey.id !== keyId) {
+            return failure(new ActivityPubFetchError("not-found", keyId, `${actor.id} does not publish ${keyId}`));
+        }
+        if (publicKey.owner !== actor.id) {
+            return failure(new ActivityPubFetchError("id-mismatch", keyId, `${keyId} is owned by ${publicKey.owner}, not by ${actor.id}`));
+        }
+        let imported = await importPublicKey(publicKey.publicKeyPem);
+        if (isFailure(imported)) {
+            return failure(new ActivityPubFetchError("invalid-document", keyId, imported.error.message, {
+                cause: imported.error,
+            }));
+        }
+        return success({ owner: actor.id, publicKey: imported.data, actor });
+    }
+    /** An object or an activity; one with an `actor` member reads as an activity. */
+    async object(iri, options) {
+        let json = await this.#load(iri, this.#objectTtl, options);
+        if (isFailure(json))
+            return json;
+        let parsed = "actor" in json.data ? parseActivity(json.data) : parseObject(json.data);
+        if (isFailure(parsed))
+            return failure(invalidDocument(iri, parsed.error));
+        return parsed;
+    }
+    /** The decoded document at `iri` after the same checks, for a shape no reader models. */
+    document(iri, options) {
+        return this.#load(iri, this.#objectTtl, options);
+    }
+    /** Drops both spellings of the entry, so a fragment never keeps a deleted copy alive. */
+    async evict(iri) {
+        let cache = this.#options.cache;
+        await Promise.all([
+            cache.delete(cacheKey(iri)).catch(() => undefined),
+            cache.delete(cacheKey(withoutFragment(iri))).catch(() => undefined),
+        ]);
+    }
+    /**
+     * The signer's keys, read from its provider when it names one: `null` when the provider
+     * holds none for the signer, which sends the GET unsigned, and a retryable
+     * `unauthorized` when the provider fails.
+     */
+    async #signingKeys(url, signer) {
+        if (!("keysOf" in signer.keys))
+            return success(signer.keys);
+        let found = await signer.keys.keysOf(signer.actor);
+        if (isFailure(found)) {
+            return failure(new ActivityPubFetchError("unauthorized", url, `Could not read the keys of ${signer.actor}: ${found.error.message}`, { retryable: true, cause: found.error }));
+        }
+        return success(found.data);
+    }
+    /**
+     * The headers of one GET, signed with draft-cavage over `(request-target) host date`
+     * when a signer is set, the scheme every server that requires signed GETs accepts.
+     */
+    async #headersFor(url) {
+        let headers = new Headers({ accept: ACTIVITY_ACCEPT, "user-agent": this.#options.userAgent });
+        let signer = this.#options.signer;
+        if (signer === undefined)
+            return success(headers);
+        let keys = await this.#signingKeys(url, signer);
+        if (isFailure(keys))
+            return keys;
+        if (keys.data === null)
+            return success(headers);
+        let signed = await sign(new Request(url, { headers }), {
+            scheme: "draft-cavage",
+            key: { id: keys.data.rsa.id, privateKey: keys.data.rsa.privateKey },
+        });
+        if (isFailure(signed)) {
+            return failure(new ActivityPubFetchError("unauthorized", url, `Could not sign the request: ${signed.error.message}`, {
+                cause: signed.error,
+            }));
+        }
+        return success(new Headers(signed.data.headers));
+    }
+    /**
+     * Fetches a document. A signed request redirected elsewhere carries a signature over
+     * the first URL, so when the end of the chain refuses it, it is signed for that URL
+     * and asked once more.
+     */
+    async #fetchDocument(url) {
+        let headers = await this.#headersFor(url);
+        if (isFailure(headers))
+            return headers;
+        let maxBytes = this.#maxBytes;
+        let fetchOptions = {
+            headers: headers.data,
+            timeout: this.#timeout,
+            maxBytes,
+        };
+        let answered = await request(url, fetchOptions);
+        if (isFailure(answered))
+            return answered;
+        let refused = answered.data.response.status === 401 || answered.data.response.status === 403;
+        if (refused && this.#options.signer !== undefined && answered.data.url.href !== url) {
+            release(answered.data.response.body);
+            let final = answered.data.url.href;
+            let resigned = await this.#headersFor(final);
+            if (isFailure(resigned))
+                return resigned;
+            answered = await request(final, { ...fetchOptions, headers: resigned.data });
+            if (isFailure(answered))
+                return answered;
+        }
+        let body = await readSuccess(url, answered.data, maxBytes);
+        if (isFailure(body))
+            return body;
+        let json = decodeObject(url, body.data.text);
+        if (isFailure(json))
+            return json;
+        let id = json.data.id;
+        if (typeof id !== "string" || !URL.canParse(id)) {
+            return failure(new ActivityPubFetchError("invalid-document", url, `${url} has no id`));
+        }
+        if (new URL(id).origin !== body.data.url.origin) {
+            return failure(new ActivityPubFetchError("id-mismatch", url, `${body.data.url.href} answered a document whose id ${id} is on another origin`));
+        }
+        return success(json.data);
+    }
+    /**
+     * The document at `iri`, from the cache unless `fresh`, else fetched and stored. A
+     * Tombstone, cached or fetched, answers `gone` and evicts the entry.
+     */
+    async #load(iri, ttl, resolveOptions) {
+        let url = withoutFragment(iri);
+        if (!URL.canParse(url)) {
+            return failure(new ActivityPubFetchError("refused-url", iri, `${iri} is not a URL`));
+        }
+        let cache = this.#options.cache;
+        let key = cacheKey(url);
+        let json = null;
+        if (resolveOptions?.fresh !== true) {
+            let cached = await cache.read(key).catch(() => null);
+            if (cached !== null && isSuccess(cached) && isRecord(cached.data))
+                json = cached.data;
+        }
+        if (json === null) {
+            let fetched = await this.#fetchDocument(url);
+            if (isFailure(fetched)) {
+                if (fetched.error.code === "gone")
+                    await this.evict(url);
+                return fetched;
+            }
+            json = fetched.data;
+            if (json.type !== "Tombstone") {
+                await cache.write(key, json, { ttl }).catch(() => undefined);
+            }
+        }
+        if (json.type === "Tombstone") {
+            await this.evict(url);
+            return failure(new ActivityPubFetchError("gone", url, `${url} was deleted`));
+        }
+        return success(json);
+    }
+}
+/** Reads `json` as an actor, failing `invalid-document` with the parser's explanation. */
+function readActor(url, json) {
+    let actor = parseActor(json);
+    if (isFailure(actor))
+        return failure(invalidDocument(url, actor.error));
+    return actor;
+}
+/** The cache entry of a document. */
+function cacheKey(iri) {
+    return `${CACHE_PREFIX}${iri}`;
+}
+/** The URL a request is made to; a fragment names a part of the document and is never sent. */
+function withoutFragment(iri) {
+    let hash = iri.indexOf("#");
+    return hash === -1 ? iri : iri.slice(0, hash);
+}
+/** Whether a cached value is a document, so an entry some other writer left reads as a miss. */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * The actor a key document says owns `keyId`: a standalone key's `owner`, or the `owner`
+ * of the `publicKey` entry with that id on a document that is not a full actor.
+ */
+function claimedOwner(json, keyId) {
+    if (typeof json.owner === "string")
+        return json.owner;
+    let entries = Array.isArray(json.publicKey) ? json.publicKey : [json.publicKey];
+    for (let entry of entries) {
+        if (!isRecord(entry) || entry.id !== keyId)
+            continue;
+        if (typeof entry.owner === "string")
+            return entry.owner;
+    }
+    return null;
+}
+/** A document that fetched fine but is not the shape asked for. */
+function invalidDocument(url, cause) {
+    return new ActivityPubFetchError("invalid-document", url, cause.message, { cause });
+}

package/dist/store.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The storage the package calls and the app implements: followers, processed activity ids,
+ * the app's own objects and its actors' keys. Federation state lives in the app's database,
+ * in its own shape and migrations, next to the content it federates.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { DurationInput } from "@sdxc/duration";
+import type { Result } from "@sdxc/result";
+import type { ActorKeys } from "./keys.js";
+import type { ActivityPub } from "./lib/types.js";
+/** Someone who follows a local actor, as the package needs to deliver to them and answer Undo. */
+export interface Follower {
+    /** The local actor being followed. */
+    actor: string;
+    /** The remote actor's id. */
+    id: string;
+    inbox: string;
+    /** Preferred for delivery, so one POST reaches every follower on that server. */
+    sharedInbox: string | null;
+    /** The Follow's id: an Accept echoes it and an Undo must name it. */
+    followId: string;
+    /** `pending` while a local actor that approves followers by hand has not decided. */
+    state: "accepted" | "pending";
+}
+/**
+ * A page of a store listing. `next` is the store's own opaque cursor, handed back unchanged to
+ * read the following page, and `null` on the last one.
+ *
+ * @template T The listed item.
+ */
+export interface StorePage<T> {
+    items: T[];
+    next: string | null;
+}
+/** The followers of local actors. Every write is idempotent, so redelivered activities are harmless. */
+export interface FollowerStore {
+    /** Inserts or replaces by `(actor, id)`, so a repeated Follow refreshes inbox and `followId`. */
+    put(follower: Follower): Promise<Result<void, Error>>;
+    /** The follower in any state, so an Undo can name its Follow; `null` when `id` follows nobody. */
+    get(actor: string, id: string): Promise<Result<Follower | null, Error>>;
+    /** Succeeds when the follower is already gone, so a repeated Undo is harmless. */
+    remove(actor: string, id: string): Promise<Result<void, Error>>;
+    /** Drops every follower reached through this inbox or shared inbox, after it answered 410. */
+    removeInbox(inbox: string): Promise<Result<void, Error>>;
+    /** Accepted followers, for the collection; `origin` narrows to one server (FEP-8fcf). */
+    list(actor: string, options: {
+        cursor: string | null;
+        limit: number;
+        origin?: string;
+    }): Promise<Result<StorePage<Follower>, Error>>;
+    /** Accepted followers, which is the `totalItems` the followers collection publishes. */
+    count(actor: string): Promise<Result<number, Error>>;
+    /** Distinct delivery targets of accepted followers, `sharedInbox ?? inbox`, one per URL. */
+    inboxes(actor: string, options: {
+        cursor: string | null;
+        limit: number;
+    }): Promise<Result<StorePage<string>, Error>>;
+}
+/**
+ * Activity ids already processed. Claiming is best effort, because every handler is
+ * idempotent: this saves work on a redelivery and is never what makes processing correct.
+ */
+export interface SeenActivities {
+    /** `true` the first time an id is claimed within `ttl`, and again once `ttl` has passed. */
+    claim(id: string, ttl: DurationInput): Promise<Result<boolean, Error>>;
+}
+/** The app's own objects, so the inbox can tell a reply, Like or Announce of local content from noise. */
+export interface LocalObjects {
+    /** The public object this app serves under `id`, or `null` when it serves none. */
+    find(id: string): Promise<Result<ActivityPub.Object | null, Error>>;
+}
+/** The signing keys of local actors. */
+export interface KeyProvider {
+    /** `null` for an actor this app does not host. */
+    keysOf(actor: string): Promise<Result<ActorKeys | null, Error>>;
+}

package/dist/store.js

@@ -0,0 +1,8 @@
+/**
+ * The storage the package calls and the app implements: followers, processed activity ids,
+ * the app's own objects and its actors' keys. Federation state lives in the app's database,
+ * in its own shape and migrations, next to the content it federates.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */

package/dist/testing.d.ts

@@ -0,0 +1,12 @@
+/**
+ * What an app tests its federation with: in-memory implementations of every store the
+ * package calls, and the conformance suites that hold the app's own stores to the same
+ * contracts, so tests and production run against one set of rules.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+export type { FollowerStoreConformanceOptions, KeyProviderConformanceOptions, LocalObjectsConformanceOptions, SeenActivitiesConformanceOptions, } from "./conformance.js";
+export type { MemorySeenActivitiesOptions } from "./memory.js";
+export { followerStoreConformance, keyProviderConformance, localObjectsConformance, seenActivitiesConformance, } from "./conformance.js";
+export { MemoryFollowerStore, MemoryKeyProvider, MemoryLocalObjects, MemorySeenActivities, } from "./memory.js";

package/dist/testing.js

@@ -0,0 +1,10 @@
+/**
+ * What an app tests its federation with: in-memory implementations of every store the
+ * package calls, and the conformance suites that hold the app's own stores to the same
+ * contracts, so tests and production run against one set of rules.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+export { followerStoreConformance, keyProviderConformance, localObjectsConformance, seenActivitiesConformance, } from "./conformance.js";
+export { MemoryFollowerStore, MemoryKeyProvider, MemoryLocalObjects, MemorySeenActivities, } from "./memory.js";