@sdxc/activitypub 0.0.0-pre.1 → 2026.10.9

package/README.md

@@ -315,6 +315,25 @@ already serialized. An activity over 120 KB (`MAX_ACTIVITY_BYTES`) fails `too-la
 delivery message could carry it, and a failing queue fails a retryable `enqueue`. A retried
 fan-out may queue some deliveries twice, which receivers absorb by activity id.
 
+#### `federation.approve(follower: string): Promise<Result<void, ActivityPubError>>`
+
+Accepts a follower a `"pending"` decision held back: it is stored as `accepted`, so it joins the
+followers collection and every later fan-out, and an `Accept` of its stored Follow is queued to
+its inbox. Approving an accepted follower sends the same Accept again, so a retry is safe.
+
+#### `federation.reject(follower: string): Promise<Result<void, ActivityPubError>>`
+
+Refuses a follower, pending or accepted: a `Reject` of its stored Follow is queued to its inbox,
+then the follower is removed. It stays stored until the Reject is queued, so retrying a failed
+call still sends it.
+
+Both answer `not-found` for an actor that does not follow the local actor, and a retryable
+`store` or `enqueue` failure when the store or the queue fails.
+
+```typescript
+let approved = await federation.approve("https://mastodon.social/users/alice");
+```
+
 #### `federation.lookup(handle: string): Promise<Result<ActivityPub.Actor, ActivityPubFetchError>>`
 
 Resolves `@user@host`, `user@host` or `acct:user@host` the way Mastodon does: WebFinger on the
@@ -551,7 +570,7 @@ Every error extends `ActivityPubError`, which carries a `code` and a `retryable`
 ### Storage
 
 The package keeps no state of its own. It calls four interfaces, exported as types, and the
-app implements them over its own database:
+app implements them over its own database, or uses `CacheSeenActivities` for `SeenActivities`:
 
 - `FollowerStore`: followers keyed by `(actor, id)`. `put` inserts or replaces, so a repeated
   Follow refreshes the inbox and `followId`. `list`, `count` and `inboxes` see accepted
@@ -563,6 +582,33 @@ app implements them over its own database:
 - `LocalObjects`: `find(id)` answers the object the app serves under `id`, or `null`.
 - `KeyProvider`: `keysOf(actor)` answers a hosted actor's `ActorKeys`, or `null`.
 
+### `CacheSeenActivities`
+
+A shipped `SeenActivities` over any `@sdxc/cache` `Cache`, so an app that already caches remote
+documents in Workers KV can hold its claims there too.
+
+```typescript
+import { CacheSeenActivities, Federation } from "@sdxc/activitypub";
+import { WorkerKVCache } from "@sdxc/cache/worker-kv";
+
+let cache = new WorkerKVCache(env.CACHE);
+
+let federation = new Federation({
+	// ...
+	stores: { followers, seen: new CacheSeenActivities(cache), objects },
+	cache,
+});
+```
+
+- Claims live under `activitypub:seen:<id>`, apart from anything else the cache holds.
+- A claim's TTL is rounded up to whole seconds and held for at least 60, the shortest
+  expiration Workers KV accepts, so a TTL under a minute is stretched rather than refused.
+- `claim` fails with a `RangeError` for a TTL that is not a positive duration, and with the
+  cache's error when the key cannot be read. A refused write still answers `true`: the
+  activity is processed, and a redelivery is processed again.
+- A claim reads the key and writes it when missing, so two deliveries racing through different
+  isolates can both win. Every handler is idempotent, which makes that harmless.
+
 ### `@sdxc/activitypub/testing`
 
 In-memory implementations of every storage interface, and Vitest suites an app registers
@@ -637,8 +683,8 @@ export default createJobHandler(definitions.federation, async (ctx) => {
 	let processed = await federationFor(storesOf(ctx)).process(ctx.input, { attempts: ctx.attempts });
 	if (isFailure(processed)) {
 		if (processed.error.retryable)
-			ctx.retry({ delay: processed.error.delay, cause: processed.error });
-		ctx.ack(processed.error.message);
+			return ctx.retry({ delay: processed.error.delay, cause: processed.error });
+		return ctx.ack(processed.error.message);
 	}
 });
 ```

package/dist/federation.d.ts

@@ -130,6 +130,28 @@ export declare class Federation {
      * @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>>;
+    /**
+     * Accepts a follower held `pending` by a manual-approval decision: it joins the
+     * followers collection and fan-outs, and an `Accept` of its stored Follow is queued to
+     * its inbox. Approving an accepted follower re-sends the same Accept, so a retry is safe.
+     *
+     * @param follower - The remote actor's id.
+     * @returns `not-found` when the actor does not follow the local actor, or a retryable
+     *   `store` or `enqueue` failure.
+     * @example let approved = await federation.approve("https://mastodon.social/users/alice");
+     */
+    approve(follower: string): Promise<Result<void, ActivityPubError>>;
+    /**
+     * Refuses a follower, pending or accepted: a `Reject` of its stored Follow is queued to
+     * its inbox, then the follower is forgotten. The follower stays stored until the Reject
+     * is queued, so retrying a failed call still sends it.
+     *
+     * @param follower - The remote actor's id.
+     * @returns `not-found` when the actor does not follow the local actor, or a retryable
+     *   `store` or `enqueue` failure.
+     * @example let rejected = await federation.reject("https://mastodon.social/users/alice");
+     */
+    reject(follower: 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

package/dist/federation.js

@@ -5,7 +5,7 @@ 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 { answerTo, handle, store } 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";
@@ -213,6 +213,45 @@ export class Federation {
         }
         return this.#enqueue([{ kind: "fanOut", actor: this.#options.actor.id, activity: text }]);
     }
+    /**
+     * Accepts a follower held `pending` by a manual-approval decision: it joins the
+     * followers collection and fan-outs, and an `Accept` of its stored Follow is queued to
+     * its inbox. Approving an accepted follower re-sends the same Accept, so a retry is safe.
+     *
+     * @param follower - The remote actor's id.
+     * @returns `not-found` when the actor does not follow the local actor, or a retryable
+     *   `store` or `enqueue` failure.
+     * @example let approved = await federation.approve("https://mastodon.social/users/alice");
+     */
+    async approve(follower) {
+        let found = await this.#follower(follower);
+        if (isFailure(found))
+            return found;
+        let put = store(await this.#options.stores.followers.put({ ...found.data, state: "accepted" }));
+        if (isFailure(put))
+            return put;
+        return this.#answer("Accept", found.data);
+    }
+    /**
+     * Refuses a follower, pending or accepted: a `Reject` of its stored Follow is queued to
+     * its inbox, then the follower is forgotten. The follower stays stored until the Reject
+     * is queued, so retrying a failed call still sends it.
+     *
+     * @param follower - The remote actor's id.
+     * @returns `not-found` when the actor does not follow the local actor, or a retryable
+     *   `store` or `enqueue` failure.
+     * @example let rejected = await federation.reject("https://mastodon.social/users/alice");
+     */
+    async reject(follower) {
+        let found = await this.#follower(follower);
+        if (isFailure(found))
+            return found;
+        let answered = await this.#answer("Reject", found.data);
+        if (isFailure(answered))
+            return answered;
+        let actor = this.#options.actor.id;
+        return store(await this.#options.stores.followers.remove(actor, follower));
+    }
     /**
      * 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
@@ -403,6 +442,23 @@ export class Federation {
         let delay = Math.max(retryAfter ?? 0, this.#backoff.delay(attempts));
         return failure(new FederationError(kind, error, delay));
     }
+    /** The local actor's stored follower `id`, or `not-found`. */
+    async #follower(id) {
+        let found = store(await this.#options.stores.followers.get(this.#options.actor.id, id));
+        if (isFailure(found))
+            return found;
+        if (found.data === null) {
+            return failure(new ActivityPubError("not-found", `${id} does not follow the local actor`));
+        }
+        return success(found.data);
+    }
+    /** Queues an answer to the follower's stored Follow, delivered to its own inbox. */
+    async #answer(type, follower) {
+        let actor = this.#options.actor.id;
+        let follow = { id: follower.followId, type: "Follow", actor: follower.id, object: actor };
+        let activity = stringify(answerTo(type, actor, follow));
+        return this.#enqueue([{ kind: "deliver", actor, activity, inbox: follower.inbox }]);
+    }
     /**
      * Writes messages to the app's queue, through `enqueueMany` when it has one. A failure,
      * or an exception, answers a retryable `enqueue` error.

package/dist/index.d.ts

@@ -31,3 +31,4 @@ export { wantsActivity } from "./lib/response.js";
 export { EXTENSION_CONTEXT, stringify } from "./lib/stringify.js";
 export { tombstone } from "./lib/tombstone.js";
 export { RemoteResolver } from "./remote.js";
+export { CacheSeenActivities } from "./seen-activities.js";

package/dist/index.js

@@ -20,3 +20,4 @@ export { wantsActivity } from "./lib/response.js";
 export { EXTENSION_CONTEXT, stringify } from "./lib/stringify.js";
 export { tombstone } from "./lib/tombstone.js";
 export { RemoteResolver } from "./remote.js";
+export { CacheSeenActivities } from "./seen-activities.js";

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

@@ -117,3 +117,21 @@ export interface HandleOutcome {
  * if (isFailure(outcome) && outcome.error.retryable) return ctx.retry({ cause: outcome.error });
  */
 export declare function handle(input: Received, options: HandleOptions): Promise<Result<HandleOutcome, ActivityPubError>>;
+/**
+ * An `Accept` or `Reject` of a Follow, embedding it, since some servers match the answer
+ * on the embedded Follow rather than its id. The id derives from the Follow's, so a
+ * re-sent answer to the same Follow is the same activity.
+ *
+ * @param type - Which answer.
+ * @param local - The local actor answering.
+ * @param follow - The Follow answered.
+ */
+export declare function answerTo(type: "Accept" | "Reject", local: string, follow: ActivityPub.Draft<ActivityPub.Activity>): ActivityPub.Draft<ActivityPub.Activity>;
+/**
+ * A store's answer, its failure made retryable, since a store that failed once can answer
+ * the next attempt.
+ *
+ * @param result - What the store answered.
+ * @template T - What the store answers.
+ */
+export declare function store<T>(result: Result<T, Error>): Result<T, ActivityPubError>;

package/dist/lib/inbox-handle.js

@@ -528,7 +528,7 @@ class Run {
  * @param local - The local actor answering.
  * @param follow - The Follow answered.
  */
-function answerTo(type, local, follow) {
+export function answerTo(type, local, follow) {
     let path = type === "Accept" ? "accepts" : "rejects";
     return {
         id: `${local}#${path}/${encodeURIComponent(follow.id)}`,
@@ -562,7 +562,7 @@ async function settle(called) {
  * @param result - What the store answered.
  * @template T - What the store answers.
  */
-function store(result) {
+export function store(result) {
     if (!isFailure(result))
         return result;
     return failure(new ActivityPubError("store", result.error.message, { retryable: true, cause: result.error }));

package/dist/seen-activities.d.ts

@@ -0,0 +1,30 @@
+/**
+ * A `SeenActivities` store over any `@sdxc/cache` `Cache`, so an app whose remote-document
+ * cache already sits on Workers KV can remember processed activity ids in the same place.
+ * Best effort by contract: every handler is idempotent, so a lost claim only costs work.
+ *
+ * @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 { SeenActivities } from "./store.js";
+/**
+ * Claims activity ids in a `Cache` under `activitypub:seen:<id>`. A claim reads the key and
+ * writes it when missing, so two deliveries racing through different isolates can both win;
+ * the handlers' idempotency covers that.
+ *
+ * @example new CacheSeenActivities(new WorkerKVCache(env.CACHE))
+ */
+export declare class CacheSeenActivities implements SeenActivities {
+    #private;
+    /** @param cache Where claims are held until their TTL passes. */
+    constructor(cache: Cache);
+    /**
+     * `true` when `id` was not claimed within its TTL, held from now for `ttl` rounded up to
+     * whole seconds and at least a minute. A cache that cannot be read is a failure; one that
+     * refuses the write still answers `true`, since processing again is harmless.
+     */
+    claim(id: string, ttl: DurationInput): Promise<Result<boolean, Error>>;
+}

package/dist/seen-activities.js

@@ -0,0 +1,48 @@
+/**
+ * A `SeenActivities` store over any `@sdxc/cache` `Cache`, so an app whose remote-document
+ * cache already sits on Workers KV can remember processed activity ids in the same place.
+ * Best effort by contract: every handler is idempotent, so a lost claim only costs work.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { toMs } from "@sdxc/duration";
+import { failure, isFailure, success } from "@sdxc/result";
+/** Keeps the claims apart from anything else the cache holds. */
+const KEY_PREFIX = "activitypub:seen:";
+/** Workers KV refuses an expiration under a minute, so a shorter claim is held for one. */
+const MIN_TTL_SECONDS = 60;
+/**
+ * Claims activity ids in a `Cache` under `activitypub:seen:<id>`. A claim reads the key and
+ * writes it when missing, so two deliveries racing through different isolates can both win;
+ * the handlers' idempotency covers that.
+ *
+ * @example new CacheSeenActivities(new WorkerKVCache(env.CACHE))
+ */
+export class CacheSeenActivities {
+    #cache;
+    /** @param cache Where claims are held until their TTL passes. */
+    constructor(cache) {
+        this.#cache = cache;
+    }
+    /**
+     * `true` when `id` was not claimed within its TTL, held from now for `ttl` rounded up to
+     * whole seconds and at least a minute. A cache that cannot be read is a failure; one that
+     * refuses the write still answers `true`, since processing again is harmless.
+     */
+    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 key = `${KEY_PREFIX}${id}`;
+        let held = await this.#cache.read(key);
+        if (isFailure(held))
+            return held;
+        if (held.data !== null)
+            return success(false);
+        let seconds = Math.max(MIN_TTL_SECONDS, Math.ceil(ms / 1000));
+        await this.#cache.write(key, Date.now(), { ttl: seconds });
+        return success(true);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sdxc/activitypub",
-	"version": "0.0.0-pre.1",
+	"version": "2026.10.9",
 	"description": "ActivityPub protocol logic: vocabulary, actors, discovery, a verified inbox and signed delivery",
 	"license": "MIT",
 	"type": "module",
@@ -10,18 +10,18 @@
 	},
 	"dependencies": {
 		"@sdxc/backoff": "2026.10.6",
-		"@sdxc/cache": "2026.10.6",
-		"@sdxc/crypto": "2026.10.6",
-		"@sdxc/digest-fields": "0.0.0-pre.1",
+		"@sdxc/cache": "2026.10.9",
+		"@sdxc/crypto": "2026.10.9",
+		"@sdxc/digest-fields": "2026.10.9",
 		"@sdxc/duration": "2026.10.6",
 		"@sdxc/html": "2026.10.6",
-		"@sdxc/http": "2026.10.8",
-		"@sdxc/http-signatures": "0.0.0-pre.1",
-		"@sdxc/logger": "2026.10.6",
-		"@sdxc/outbound": "2026.10.6",
+		"@sdxc/http": "2026.10.9",
+		"@sdxc/http-signatures": "2026.10.9",
+		"@sdxc/logger": "2026.10.9",
+		"@sdxc/outbound": "2026.10.9",
 		"@sdxc/result": "2026.10.6",
 		"@sdxc/validate": "2026.10.6",
-		"@sdxc/well-known": "2026.10.8",
+		"@sdxc/well-known": "2026.10.9",
 		"@standard-schema/spec": "^1.1.0",
 		"remix": "3.0.0"
 	},
@@ -33,7 +33,7 @@
 			"optional": true
 		}
 	},
-	"gitHead": "5b83053d6073199445712cf5d225e8a8b1667992",
+	"gitHead": "64fa732ed0a8ca8693a35aeef6345ae5be2534ef",
 	"publishConfig": {
 		"access": "public"
 	},