@oxy.so/federation 2.7.0 → 2.8.0

package/README.md

@@ -29,3 +29,24 @@ each request. Only whole seconds from 0 through 86400 are accepted. This does
 not change the injected JRD cache: applications must also authorize its reads
 and their user resolver against current policy. It cannot retract documents
 already cached by remote consumers before this setting changes.
+
+## Deleted actors
+
+When a local account is deleted, tell the fediverse once and then answer as
+gone, the way Mastodon handles account deletion:
+
+1. Call `deliveryService.federateActorDelete(oxyUserId, username)` BEFORE
+   deleting the account's accepted follower rows, since they are its
+   recipients. It sends the actor's `Delete` of itself (`<actor>#delete`, a
+   deterministic id, so a retried run does not fan out twice) to each follower
+   shared inbox, signed with the actor's own key. The key must therefore still
+   be signable at send time; Oxy keeps it after the account is gone.
+2. Pass `isActorGone(username)` to `createActorRouter` and
+   `createWebfingerRouter`. It is asked only for a username `resolveUser` found
+   nobody for. True answers `410 Gone` instead of 404 on the actor (with a
+   `Tombstone` body), its inbox, its collections and WebFinger. Mastodon deletes
+   an account whose WebFinger answers 410; Lemmy, PieFed and Mbin mark an actor
+   deleted when a refetch answers 410. A 404 tells none of them anything.
+
+The app's own content routes (outbox, posts) can answer the same way with
+`goneTombstone(id)`.

package/dist/cjs/node/actorRouter.js

@@ -28,6 +28,7 @@ const httpCacheControl_1 = require("./httpCacheControl");
 const httpSignature_1 = require("../httpSignature");
 const urls_1 = require("../urls");
 const actorObject_1 = require("../actorObject");
+const goneActor_1 = require("./goneActor");
 /** Page size for the paginated followers/following collections (mirrors the outbox). */
 const FOLLOW_PAGE_SIZE = 20;
 /** Extract the `:username` param safely as a string. */
@@ -64,6 +65,18 @@ function createActorRouter(config) {
     function wantsActivityPub(req) {
         return config.wantsActivityPub(req.headers.accept);
     }
+    /**
+     * The answer for a username nobody resolved to: 410 with the actor's
+     * `Tombstone` when it is a deleted actor, else the usual 404.
+     */
+    async function userMissing(res, username) {
+        if (config.isActorGone && (await config.isActorGone(username))) {
+            res.set('Content-Type', apContentType);
+            res.set('Cache-Control', httpCacheControl);
+            return res.status(410).json((0, goneActor_1.goneTombstone)(urls.actor(username)));
+        }
+        return res.status(404).json({ error: 'User not found' });
+    }
     /** Common inbox handler with HTTP signature verification. */
     async function handleInbox(req, res) {
         try {
@@ -131,7 +144,7 @@ function createActorRouter(config) {
         try {
             const user = await config.resolveUser(username);
             if (!user)
-                return res.status(404).json({ error: 'User not found' });
+                return userMissing(res, username);
             if (!config.consent.isSharingEnabledFromUser(user)) {
                 return res.status(404).json({ error: 'User not found' });
             }
@@ -251,7 +264,7 @@ function createActorRouter(config) {
             }
             const user = await config.resolveUser(username);
             if (!user)
-                return res.status(404).json({ error: 'User not found' });
+                return userMissing(res, username);
             // Sharing OFF must be indistinguishable from a nonexistent user — same 404
             // body, no separate error code. Derived from the already-resolved user.
             if (!config.consent.isSharingEnabledFromUser(user)) {
@@ -299,9 +312,13 @@ function createActorRouter(config) {
         // server drop it permanently rather than retry, so availability wins over
         // gating freshness — the activity is processed and any consent decision is
         // re-checked downstream by the id-based (fail-open) gates.
+        // A DELETED actor's inbox refuses delivery with 410, so the sender stops
+        // rather than treating it as a transient miss.
         const username = getUsername(req);
         const sharingState = await config.consent.getSharingStateByUsername(username);
-        if (sharingState === 'disabled' || sharingState === 'unknown-user') {
+        if (sharingState === 'unknown-user')
+            return userMissing(res, username);
+        if (sharingState === 'disabled') {
             return res.status(404).json({ error: 'User not found' });
         }
         return handleInbox(req, res);
@@ -327,8 +344,9 @@ function createActorRouter(config) {
             const username = getUsername(req);
             try {
                 const user = await config.resolveUser(username);
-                if (!user ||
-                    !config.consent.isSharingEnabledFromUser(user) ||
+                if (!user)
+                    return userMissing(res, username);
+                if (!config.consent.isSharingEnabledFromUser(user) ||
                     (0, actorObject_1.localActorTypeForAccountKind)(user.kind) !== actorObject_1.LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND.community) {
                     return res.status(404).json({ error: 'User not found' });
                 }

package/dist/cjs/node/delivery.js

@@ -30,6 +30,7 @@ exports.createDeliveryService = createDeliveryService;
 const apContext_1 = require("../apContext");
 const boundedBody_1 = require("./boundedBody");
 const httpSignature_1 = require("../httpSignature");
+const goneActor_1 = require("./goneActor");
 /** Total time budget for a single delivery POST (connect + response headers). */
 const DELIVER_ACTIVITY_TIMEOUT_MS = 15000;
 /** How many bytes of a failed-delivery response body are read for the debug log. */
@@ -439,6 +440,11 @@ function createDeliveryService(config) {
             logger.error('Failed to federate actor update:', err);
         }
     }
+    async function federateActorDelete(actorOxyUserId, username) {
+        if (!config.federationEnabled)
+            return;
+        await deliverToFollowers((0, goneActor_1.buildActorDeleteActivity)(urls.actor(username)), actorOxyUserId, username);
+    }
     return {
         deliverActivity,
         queueDelivery,
@@ -449,5 +455,6 @@ function createDeliveryService(config) {
         sendAccept,
         sendReject,
         federateActorUpdate,
+        federateActorDelete,
     };
 }

package/dist/cjs/node/goneActor.js

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * A DELETED local actor, as the fediverse is told about it.
+ *
+ * Two halves, following Mastodon's account deletion:
+ *
+ *  1. Once, the app sends `Delete{actor}`: the actor deletes itself, signed with
+ *     its own key, to every follower's (shared) inbox. That is
+ *     `DeliveryService.federateActorDelete`, built by {@link buildActorDeleteActivity}.
+ *  2. From then on the actor's URLs answer `410 Gone` instead of `404`. That is
+ *     what a server that missed the Delete, or never acts on one, reads as
+ *     permanent: Mastodon deletes its copy of an account whose WebFinger answers
+ *     410, and Lemmy, PieFed and Mbin mark a community or person deleted when a
+ *     refetch answers 410 or a `Tombstone`. A 404 tells all of them nothing, so
+ *     they keep the ghost profile and keep delivering to it.
+ *
+ * The routers ask the app's `isActorGone(username)` only after `resolveUser`
+ * found nobody, so a live account is never answered as gone.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.goneTombstone = goneTombstone;
+exports.buildActorDeleteActivity = buildActorDeleteActivity;
+const apContext_1 = require("../apContext");
+/** The body of a `410 Gone` for a deleted object: a bare `Tombstone` naming it. */
+function goneTombstone(id) {
+    return { '@context': apContext_1.AP_CONTEXT, id, type: 'Tombstone' };
+}
+/**
+ * The actor's `Delete` of itself. The id is DETERMINISTIC (no timestamp), the
+ * shape Mastodon sends (`<actor>#delete`), so a retried run re-sends the same
+ * activity and a delivery queue that dedupes on activity id + inbox sends each
+ * inbox one copy.
+ */
+function buildActorDeleteActivity(actorUri) {
+    return {
+        '@context': apContext_1.AP_CONTEXT,
+        id: `${actorUri}#delete`,
+        type: 'Delete',
+        actor: actorUri,
+        to: ['https://www.w3.org/ns/activitystreams#Public'],
+        object: actorUri,
+    };
+}

package/dist/cjs/node/index.js

@@ -18,7 +18,7 @@
  * actor + inbox + follow-graph Express routers.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createActorRouter = exports.createWebfingerRouter = exports.ActorResolutionPendingError = exports.createInboundDispatcher = exports.DeliveryAuthorizationDeniedError = exports.createDeliveryService = exports.ActorResolver = exports.createActorResolver = exports.createIdentityBridge = exports.createTcoLinkExpander = exports.createSignedFetch = void 0;
+exports.createActorRouter = exports.goneTombstone = exports.buildActorDeleteActivity = exports.createWebfingerRouter = exports.ActorResolutionPendingError = exports.createInboundDispatcher = exports.DeliveryAuthorizationDeniedError = exports.createDeliveryService = exports.ActorResolver = exports.createActorResolver = exports.createIdentityBridge = exports.createTcoLinkExpander = exports.createSignedFetch = void 0;
 var signedFetch_1 = require("./signedFetch");
 Object.defineProperty(exports, "createSignedFetch", { enumerable: true, get: function () { return signedFetch_1.createSignedFetch; } });
 /**
@@ -66,5 +66,12 @@ Object.defineProperty(exports, "createWebfingerRouter", { enumerable: true, get:
  * The ActivityPub actor + inbox + follow-graph router (actor GET incl. the
  * `instance` actor, inbox POST with HTTP-sig verify, followers/following pages).
  */
+/**
+ * A deleted local actor: its `Delete` of itself, and the `Tombstone` its URLs
+ * answer `410 Gone` with afterwards.
+ */
+var goneActor_1 = require("./goneActor");
+Object.defineProperty(exports, "buildActorDeleteActivity", { enumerable: true, get: function () { return goneActor_1.buildActorDeleteActivity; } });
+Object.defineProperty(exports, "goneTombstone", { enumerable: true, get: function () { return goneActor_1.goneTombstone; } });
 var actorRouter_1 = require("./actorRouter");
 Object.defineProperty(exports, "createActorRouter", { enumerable: true, get: function () { return actorRouter_1.createActorRouter; } });

package/dist/cjs/node/webfingerRouter.js

@@ -90,8 +90,13 @@ function createWebfingerRouter(config) {
                 return res.json(cached);
             }
             const user = await config.resolveUser(username);
-            if (!user)
+            if (!user) {
+                if (config.isActorGone && (await config.isActorGone(username))) {
+                    res.set('Cache-Control', httpCacheControl);
+                    return res.status(410).json({ error: 'User deleted' });
+                }
                 return res.status(404).json({ error: 'User not found' });
+            }
             // Sharing OFF must be indistinguishable from a nonexistent user — same 404
             // body, no separate error code. UNLIKE the other user-scoped surfaces,
             // webfinger does a SECOND, uncached consent read here rather than reusing

package/dist/esm/node/actorRouter.js

@@ -25,6 +25,7 @@ import { discoveryCacheControl } from './httpCacheControl.js';
 import { verifyHttpSignature } from '../httpSignature.js';
 import { INSTANCE_ACTOR_USERNAME, normalizeActorUsername } from '../urls.js';
 import { LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND, localActorTypeForAccountKind, } from '../actorObject.js';
+import { goneTombstone } from './goneActor.js';
 /** Page size for the paginated followers/following collections (mirrors the outbox). */
 const FOLLOW_PAGE_SIZE = 20;
 /** Extract the `:username` param safely as a string. */
@@ -61,6 +62,18 @@ export function createActorRouter(config) {
     function wantsActivityPub(req) {
         return config.wantsActivityPub(req.headers.accept);
     }
+    /**
+     * The answer for a username nobody resolved to: 410 with the actor's
+     * `Tombstone` when it is a deleted actor, else the usual 404.
+     */
+    async function userMissing(res, username) {
+        if (config.isActorGone && (await config.isActorGone(username))) {
+            res.set('Content-Type', apContentType);
+            res.set('Cache-Control', httpCacheControl);
+            return res.status(410).json(goneTombstone(urls.actor(username)));
+        }
+        return res.status(404).json({ error: 'User not found' });
+    }
     /** Common inbox handler with HTTP signature verification. */
     async function handleInbox(req, res) {
         try {
@@ -128,7 +141,7 @@ export function createActorRouter(config) {
         try {
             const user = await config.resolveUser(username);
             if (!user)
-                return res.status(404).json({ error: 'User not found' });
+                return userMissing(res, username);
             if (!config.consent.isSharingEnabledFromUser(user)) {
                 return res.status(404).json({ error: 'User not found' });
             }
@@ -248,7 +261,7 @@ export function createActorRouter(config) {
             }
             const user = await config.resolveUser(username);
             if (!user)
-                return res.status(404).json({ error: 'User not found' });
+                return userMissing(res, username);
             // Sharing OFF must be indistinguishable from a nonexistent user — same 404
             // body, no separate error code. Derived from the already-resolved user.
             if (!config.consent.isSharingEnabledFromUser(user)) {
@@ -296,9 +309,13 @@ export function createActorRouter(config) {
         // server drop it permanently rather than retry, so availability wins over
         // gating freshness — the activity is processed and any consent decision is
         // re-checked downstream by the id-based (fail-open) gates.
+        // A DELETED actor's inbox refuses delivery with 410, so the sender stops
+        // rather than treating it as a transient miss.
         const username = getUsername(req);
         const sharingState = await config.consent.getSharingStateByUsername(username);
-        if (sharingState === 'disabled' || sharingState === 'unknown-user') {
+        if (sharingState === 'unknown-user')
+            return userMissing(res, username);
+        if (sharingState === 'disabled') {
             return res.status(404).json({ error: 'User not found' });
         }
         return handleInbox(req, res);
@@ -324,8 +341,9 @@ export function createActorRouter(config) {
             const username = getUsername(req);
             try {
                 const user = await config.resolveUser(username);
-                if (!user ||
-                    !config.consent.isSharingEnabledFromUser(user) ||
+                if (!user)
+                    return userMissing(res, username);
+                if (!config.consent.isSharingEnabledFromUser(user) ||
                     localActorTypeForAccountKind(user.kind) !== LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND.community) {
                     return res.status(404).json({ error: 'User not found' });
                 }

package/dist/esm/node/delivery.js

@@ -26,6 +26,7 @@
 import { AP_CONTEXT } from '../apContext.js';
 import { readBodyChunks } from './boundedBody.js';
 import { signRequest } from '../httpSignature.js';
+import { buildActorDeleteActivity } from './goneActor.js';
 /** Total time budget for a single delivery POST (connect + response headers). */
 const DELIVER_ACTIVITY_TIMEOUT_MS = 15000;
 /** How many bytes of a failed-delivery response body are read for the debug log. */
@@ -434,6 +435,11 @@ export function createDeliveryService(config) {
             logger.error('Failed to federate actor update:', err);
         }
     }
+    async function federateActorDelete(actorOxyUserId, username) {
+        if (!config.federationEnabled)
+            return;
+        await deliverToFollowers(buildActorDeleteActivity(urls.actor(username)), actorOxyUserId, username);
+    }
     return {
         deliverActivity,
         queueDelivery,
@@ -444,5 +450,6 @@ export function createDeliveryService(config) {
         sendAccept,
         sendReject,
         federateActorUpdate,
+        federateActorDelete,
     };
 }

package/dist/esm/node/goneActor.js

@@ -0,0 +1,39 @@
+/**
+ * A DELETED local actor, as the fediverse is told about it.
+ *
+ * Two halves, following Mastodon's account deletion:
+ *
+ *  1. Once, the app sends `Delete{actor}`: the actor deletes itself, signed with
+ *     its own key, to every follower's (shared) inbox. That is
+ *     `DeliveryService.federateActorDelete`, built by {@link buildActorDeleteActivity}.
+ *  2. From then on the actor's URLs answer `410 Gone` instead of `404`. That is
+ *     what a server that missed the Delete, or never acts on one, reads as
+ *     permanent: Mastodon deletes its copy of an account whose WebFinger answers
+ *     410, and Lemmy, PieFed and Mbin mark a community or person deleted when a
+ *     refetch answers 410 or a `Tombstone`. A 404 tells all of them nothing, so
+ *     they keep the ghost profile and keep delivering to it.
+ *
+ * The routers ask the app's `isActorGone(username)` only after `resolveUser`
+ * found nobody, so a live account is never answered as gone.
+ */
+import { AP_CONTEXT } from '../apContext.js';
+/** The body of a `410 Gone` for a deleted object: a bare `Tombstone` naming it. */
+export function goneTombstone(id) {
+    return { '@context': AP_CONTEXT, id, type: 'Tombstone' };
+}
+/**
+ * The actor's `Delete` of itself. The id is DETERMINISTIC (no timestamp), the
+ * shape Mastodon sends (`<actor>#delete`), so a retried run re-sends the same
+ * activity and a delivery queue that dedupes on activity id + inbox sends each
+ * inbox one copy.
+ */
+export function buildActorDeleteActivity(actorUri) {
+    return {
+        '@context': AP_CONTEXT,
+        id: `${actorUri}#delete`,
+        type: 'Delete',
+        actor: actorUri,
+        to: ['https://www.w3.org/ns/activitystreams#Public'],
+        object: actorUri,
+    };
+}

package/dist/esm/node/index.js

@@ -53,4 +53,9 @@ export { createWebfingerRouter, } from './webfingerRouter.js';
  * The ActivityPub actor + inbox + follow-graph router (actor GET incl. the
  * `instance` actor, inbox POST with HTTP-sig verify, followers/following pages).
  */
+/**
+ * A deleted local actor: its `Delete` of itself, and the `Tombstone` its URLs
+ * answer `410 Gone` with afterwards.
+ */
+export { buildActorDeleteActivity, goneTombstone } from './goneActor.js';
 export { createActorRouter, } from './actorRouter.js';

package/dist/esm/node/webfingerRouter.js

@@ -87,8 +87,13 @@ export function createWebfingerRouter(config) {
                 return res.json(cached);
             }
             const user = await config.resolveUser(username);
-            if (!user)
+            if (!user) {
+                if (config.isActorGone && (await config.isActorGone(username))) {
+                    res.set('Cache-Control', httpCacheControl);
+                    return res.status(410).json({ error: 'User deleted' });
+                }
                 return res.status(404).json({ error: 'User not found' });
+            }
             // Sharing OFF must be indistinguishable from a nonexistent user — same 404
             // body, no separate error code. UNLIKE the other user-scoped surfaces,
             // webfinger does a SECOND, uncached consent read here rather than reusing

package/dist/types/node/actorRouter.d.ts

@@ -24,6 +24,7 @@ import type { AccountKind } from '@oxy.so/contracts';
 import type { User } from '@oxy.so/core';
 import type { UrlBuilders } from '../urls';
 import { type LocalActorBuilder } from '../actorObject';
+import { type IsActorGone } from './goneActor';
 /** The resolved-user fields the actor + collection routes read. */
 export interface ActorRouteUser {
     _id?: string | null;
@@ -114,6 +115,13 @@ export interface ActorRouterConfig {
      * the route is not mounted; any account that is not a community 404s.
      */
     fetchModerators?(userId: string): Promise<User[]>;
+    /**
+     * Whether a username that resolved to nobody names a DELETED local actor
+     * (`goneActor.ts`). True ⇒ the actor, its inbox and its collections answer
+     * `410 Gone` (the actor with a `Tombstone`) instead of 404. Omitted ⇒ every
+     * miss is a 404.
+     */
+    isActorGone?: IsActorGone;
     /** Actor HTTP response TTL in whole seconds, 0..86400. Defaults to 1800; 0 sends no-store. */
     httpCacheTtlSeconds?: number;
     /** Diagnostics sink. */

package/dist/types/node/delivery.d.ts

@@ -270,6 +270,15 @@ export interface DeliveryService {
     sendReject(localOxyUserId: string, localUsername: string, followActivityId: string, remoteActorUri: string): Promise<void>;
     /** Rebroadcast the FULL actor document as an Update(Person) to remote followers. */
     federateActorUpdate(actorOxyUserId: string, username: string): Promise<void>;
+    /**
+     * Tell every remote follower the actor is gone: its `Delete` of itself
+     * (`goneActor.ts`), one per (shared) inbox, signed with its own key. Needs the
+     * accepted follower rows, so call it BEFORE deleting them. Asks no consent and
+     * resolves no profile, since the account is already gone at its identity
+     * provider; it needs only the handle and the key the handle addresses. Throws
+     * when it cannot queue, so the caller's job retries.
+     */
+    federateActorDelete(actorOxyUserId: string, username: string): Promise<void>;
 }
 /** Build the outbound delivery + follow-lifecycle service from an app's adapters. */
 export declare function createDeliveryService<TActor extends DeliveryActorFields>(config: DeliveryServiceConfig<TActor>): DeliveryService;

package/dist/types/node/goneActor.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A DELETED local actor, as the fediverse is told about it.
+ *
+ * Two halves, following Mastodon's account deletion:
+ *
+ *  1. Once, the app sends `Delete{actor}`: the actor deletes itself, signed with
+ *     its own key, to every follower's (shared) inbox. That is
+ *     `DeliveryService.federateActorDelete`, built by {@link buildActorDeleteActivity}.
+ *  2. From then on the actor's URLs answer `410 Gone` instead of `404`. That is
+ *     what a server that missed the Delete, or never acts on one, reads as
+ *     permanent: Mastodon deletes its copy of an account whose WebFinger answers
+ *     410, and Lemmy, PieFed and Mbin mark a community or person deleted when a
+ *     refetch answers 410 or a `Tombstone`. A 404 tells all of them nothing, so
+ *     they keep the ghost profile and keep delivering to it.
+ *
+ * The routers ask the app's `isActorGone(username)` only after `resolveUser`
+ * found nobody, so a live account is never answered as gone.
+ */
+/** Does `username` name a local actor that was deleted? Asked only for a username that resolved to nobody. */
+export type IsActorGone = (username: string) => Promise<boolean>;
+/** The body of a `410 Gone` for a deleted object: a bare `Tombstone` naming it. */
+export declare function goneTombstone(id: string): Record<string, unknown>;
+/**
+ * The actor's `Delete` of itself. The id is DETERMINISTIC (no timestamp), the
+ * shape Mastodon sends (`<actor>#delete`), so a retried run re-sends the same
+ * activity and a delivery queue that dedupes on activity id + inbox sends each
+ * inbox one copy.
+ */
+export declare function buildActorDeleteActivity(actorUri: string): Record<string, unknown>;

package/dist/types/node/index.d.ts

@@ -53,4 +53,9 @@ export { createWebfingerRouter, type WebfingerRouterConfig, type WebfingerSharin
  * The ActivityPub actor + inbox + follow-graph router (actor GET incl. the
  * `instance` actor, inbox POST with HTTP-sig verify, followers/following pages).
  */
+/**
+ * A deleted local actor: its `Delete` of itself, and the `Tombstone` its URLs
+ * answer `410 Gone` with afterwards.
+ */
+export { buildActorDeleteActivity, goneTombstone, type IsActorGone } from './goneActor';
 export { createActorRouter, type ActorRouterConfig, type ActorRouteUser, type ActorSharingState, type ActorRouterLogger, type FollowPage, } from './actorRouter';

package/dist/types/node/webfingerRouter.d.ts

@@ -13,6 +13,7 @@
  */
 import { Router } from 'express';
 import type { UrlBuilders } from '../urls';
+import type { IsActorGone } from './goneActor';
 /** The tri-state consent read for a username with no already-resolved user object. */
 export type WebfingerSharingState = 'enabled' | 'disabled' | 'unknown-user' | 'unavailable';
 /** The resolved-user fields the webfinger consent fallback reads. */
@@ -55,6 +56,12 @@ export interface WebfingerRouterConfig {
         get(username: string): Promise<WebfingerJrd | null>;
         set(username: string, jrd: WebfingerJrd): void;
     };
+    /**
+     * Whether a username that resolved to nobody names a DELETED local actor
+     * (`goneActor.ts`). True ⇒ `410 Gone` instead of 404, which is what makes
+     * Mastodon delete its copy of the account. Omitted ⇒ every miss is a 404.
+     */
+    isActorGone?: IsActorGone;
     /** HTTP response TTL in whole seconds, 0..86400. Defaults to 3600; 0 sends no-store. */
     httpCacheTtlSeconds?: number;
     /** Diagnostics sink. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/federation",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "description": "Oxy Federation — the app-agnostic ActivityPub identity + follow engine substrate: the network-connector contract, normalized cross-network DTOs, HTTP signatures, actor resolution, the outbound delivery transport + follow lifecycle, the inbound dispatcher, and the webfinger/actor/inbox Express routers. Domain-parameterized so every Oxy app backend federates under its own domain.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/__tests__/delivery.test.ts

@@ -471,6 +471,29 @@ describe('federateActorUpdate', () => {
   });
 });
 
+describe('federateActorDelete', () => {
+  it("sends the actor's own Delete, once per shared inbox, with no consent or profile read", async () => {
+    const shared = 'https://shared.example/inbox';
+    const rig = makeRig({
+      sharingEnabled: false,
+      followerActorUris: ['a', 'b'],
+      followerInboxes: { a: { sharedInboxUrl: shared }, b: { sharedInboxUrl: shared } },
+    });
+
+    await rig.service.federateActorDelete('u-alice', 'alice');
+
+    expect(rig.enqueued).toHaveLength(1);
+    expect(rig.enqueued[0].activityJson).toEqual({
+      '@context': AP_CONTEXT,
+      id: `${urls.actor('alice')}#delete`,
+      type: 'Delete',
+      actor: urls.actor('alice'),
+      to: ['https://www.w3.org/ns/activitystreams#Public'],
+      object: urls.actor('alice'),
+    });
+  });
+});
+
 describe('live delivery authorization', () => {
   const activity = {
     type: 'Create',

package/src/__tests__/routers.test.ts

@@ -210,6 +210,16 @@ describe('webfinger router', () => {
     expect(res.body.links[0].href).toBe(urls.actor('alice'));
   });
 
+  it('answers 410 for a deleted actor, and still 404 for an unknown one', async () => {
+    const app = makeWebfingerApp({ isActorGone: async (username) => username === 'gone' });
+    const gone = await request(app).get('/.well-known/webfinger?resource=acct:gone@mention.earth');
+    expect(gone.status).toBe(410);
+    const unknown = await request(app).get(
+      '/.well-known/webfinger?resource=acct:ghost@mention.earth',
+    );
+    expect(unknown.status).toBe(404);
+  });
+
   it('404s a sharing-disabled user indistinguishably', async () => {
     const app = makeWebfingerApp({
       consent: {
@@ -589,6 +599,35 @@ describe('actor router — inbox POST', () => {
   });
 });
 
+describe('actor router — a deleted actor', () => {
+  it('answers 410 with a Tombstone on the actor, its inbox and collections; an unknown user stays 404', async () => {
+    const app = makeActorApp({
+      actorConfig: { isActorGone: async (username) => username === 'gone' },
+    });
+    const actor = await request(app)
+      .get('/ap/users/gone')
+      .set('Accept', 'application/activity+json');
+    expect(actor.status).toBe(410);
+    expect(actor.body).toMatchObject({ id: urls.actor('gone'), type: 'Tombstone' });
+
+    const inbox = await request(app)
+      .post('/ap/users/gone/inbox')
+      .set('Content-Type', 'application/activity+json')
+      .send({ type: 'Follow' });
+    expect(inbox.status).toBe(410);
+
+    const followers = await request(app)
+      .get('/ap/users/gone/followers')
+      .set('Accept', 'application/activity+json');
+    expect(followers.status).toBe(410);
+
+    const unknown = await request(app)
+      .get('/ap/users/ghost')
+      .set('Accept', 'application/activity+json');
+    expect(unknown.status).toBe(404);
+  });
+});
+
 describe('community moderators collection', () => {
   const moderatorsApp = () =>
     makeActorApp({

package/src/node/actorRouter.ts

@@ -33,6 +33,7 @@ import {
   localActorTypeForAccountKind,
   type LocalActorBuilder,
 } from '../actorObject';
+import { goneTombstone, type IsActorGone } from './goneActor';
 
 /** Page size for the paginated followers/following collections (mirrors the outbox). */
 const FOLLOW_PAGE_SIZE = 20;
@@ -133,6 +134,13 @@ export interface ActorRouterConfig {
    * the route is not mounted; any account that is not a community 404s.
    */
   fetchModerators?(userId: string): Promise<User[]>;
+  /**
+   * Whether a username that resolved to nobody names a DELETED local actor
+   * (`goneActor.ts`). True ⇒ the actor, its inbox and its collections answer
+   * `410 Gone` (the actor with a `Tombstone`) instead of 404. Omitted ⇒ every
+   * miss is a 404.
+   */
+  isActorGone?: IsActorGone;
   /** Actor HTTP response TTL in whole seconds, 0..86400. Defaults to 1800; 0 sends no-store. */
   httpCacheTtlSeconds?: number;
   /** Diagnostics sink. */
@@ -178,6 +186,19 @@ export function createActorRouter(config: ActorRouterConfig): Router {
     return config.wantsActivityPub(req.headers.accept);
   }
 
+  /**
+   * The answer for a username nobody resolved to: 410 with the actor's
+   * `Tombstone` when it is a deleted actor, else the usual 404.
+   */
+  async function userMissing(res: Response, username: string): Promise<Response> {
+    if (config.isActorGone && (await config.isActorGone(username))) {
+      res.set('Content-Type', apContentType);
+      res.set('Cache-Control', httpCacheControl);
+      return res.status(410).json(goneTombstone(urls.actor(username)));
+    }
+    return res.status(404).json({ error: 'User not found' });
+  }
+
   /** Common inbox handler with HTTP signature verification. */
   async function handleInbox(req: InboxRequest, res: Response): Promise<Response> {
     try {
@@ -264,7 +285,7 @@ export function createActorRouter(config: ActorRouterConfig): Router {
 
     try {
       const user = await config.resolveUser(username);
-      if (!user) return res.status(404).json({ error: 'User not found' });
+      if (!user) return userMissing(res, username);
 
       if (!config.consent.isSharingEnabledFromUser(user)) {
         return res.status(404).json({ error: 'User not found' });
@@ -403,7 +424,7 @@ export function createActorRouter(config: ActorRouterConfig): Router {
       }
 
       const user = await config.resolveUser(username);
-      if (!user) return res.status(404).json({ error: 'User not found' });
+      if (!user) return userMissing(res, username);
 
       // Sharing OFF must be indistinguishable from a nonexistent user — same 404
       // body, no separate error code. Derived from the already-resolved user.
@@ -457,9 +478,12 @@ export function createActorRouter(config: ActorRouterConfig): Router {
     // server drop it permanently rather than retry, so availability wins over
     // gating freshness — the activity is processed and any consent decision is
     // re-checked downstream by the id-based (fail-open) gates.
+    // A DELETED actor's inbox refuses delivery with 410, so the sender stops
+    // rather than treating it as a transient miss.
     const username = getUsername(req);
     const sharingState = await config.consent.getSharingStateByUsername(username);
-    if (sharingState === 'disabled' || sharingState === 'unknown-user') {
+    if (sharingState === 'unknown-user') return userMissing(res, username);
+    if (sharingState === 'disabled') {
       return res.status(404).json({ error: 'User not found' });
     }
 
@@ -492,8 +516,8 @@ export function createActorRouter(config: ActorRouterConfig): Router {
       const username = getUsername(req);
       try {
         const user = await config.resolveUser(username);
+        if (!user) return userMissing(res, username);
         if (
-          !user ||
           !config.consent.isSharingEnabledFromUser(user) ||
           localActorTypeForAccountKind(user.kind) !== LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND.community
         ) {

package/src/node/delivery.ts

@@ -30,6 +30,7 @@ import { readBodyChunks } from './boundedBody';
 import { signRequest, type HttpSignatureSigner } from '../httpSignature';
 import type { UrlBuilders } from '../urls';
 import type { LocalActorBuilder } from '../actorObject';
+import { buildActorDeleteActivity } from './goneActor';
 
 /** Total time budget for a single delivery POST (connect + response headers). */
 const DELIVER_ACTIVITY_TIMEOUT_MS = 15000;
@@ -360,6 +361,15 @@ export interface DeliveryService {
   ): Promise<void>;
   /** Rebroadcast the FULL actor document as an Update(Person) to remote followers. */
   federateActorUpdate(actorOxyUserId: string, username: string): Promise<void>;
+  /**
+   * Tell every remote follower the actor is gone: its `Delete` of itself
+   * (`goneActor.ts`), one per (shared) inbox, signed with its own key. Needs the
+   * accepted follower rows, so call it BEFORE deleting them. Asks no consent and
+   * resolves no profile, since the account is already gone at its identity
+   * provider; it needs only the handle and the key the handle addresses. Throws
+   * when it cannot queue, so the caller's job retries.
+   */
+  federateActorDelete(actorOxyUserId: string, username: string): Promise<void>;
 }
 
 /** Build the outbound delivery + follow-lifecycle service from an app's adapters. */
@@ -850,6 +860,15 @@ export function createDeliveryService<TActor extends DeliveryActorFields>(
     }
   }
 
+  async function federateActorDelete(actorOxyUserId: string, username: string): Promise<void> {
+    if (!config.federationEnabled) return;
+    await deliverToFollowers(
+      buildActorDeleteActivity(urls.actor(username)),
+      actorOxyUserId,
+      username,
+    );
+  }
+
   return {
     deliverActivity,
     queueDelivery,
@@ -860,5 +879,6 @@ export function createDeliveryService<TActor extends DeliveryActorFields>(
     sendAccept,
     sendReject,
     federateActorUpdate,
+    federateActorDelete,
   };
 }

package/src/node/goneActor.ts

@@ -0,0 +1,45 @@
+/**
+ * A DELETED local actor, as the fediverse is told about it.
+ *
+ * Two halves, following Mastodon's account deletion:
+ *
+ *  1. Once, the app sends `Delete{actor}`: the actor deletes itself, signed with
+ *     its own key, to every follower's (shared) inbox. That is
+ *     `DeliveryService.federateActorDelete`, built by {@link buildActorDeleteActivity}.
+ *  2. From then on the actor's URLs answer `410 Gone` instead of `404`. That is
+ *     what a server that missed the Delete, or never acts on one, reads as
+ *     permanent: Mastodon deletes its copy of an account whose WebFinger answers
+ *     410, and Lemmy, PieFed and Mbin mark a community or person deleted when a
+ *     refetch answers 410 or a `Tombstone`. A 404 tells all of them nothing, so
+ *     they keep the ghost profile and keep delivering to it.
+ *
+ * The routers ask the app's `isActorGone(username)` only after `resolveUser`
+ * found nobody, so a live account is never answered as gone.
+ */
+
+import { AP_CONTEXT } from '../apContext';
+
+/** Does `username` name a local actor that was deleted? Asked only for a username that resolved to nobody. */
+export type IsActorGone = (username: string) => Promise<boolean>;
+
+/** The body of a `410 Gone` for a deleted object: a bare `Tombstone` naming it. */
+export function goneTombstone(id: string): Record<string, unknown> {
+  return { '@context': AP_CONTEXT, id, type: 'Tombstone' };
+}
+
+/**
+ * The actor's `Delete` of itself. The id is DETERMINISTIC (no timestamp), the
+ * shape Mastodon sends (`<actor>#delete`), so a retried run re-sends the same
+ * activity and a delivery queue that dedupes on activity id + inbox sends each
+ * inbox one copy.
+ */
+export function buildActorDeleteActivity(actorUri: string): Record<string, unknown> {
+  return {
+    '@context': AP_CONTEXT,
+    id: `${actorUri}#delete`,
+    type: 'Delete',
+    actor: actorUri,
+    to: ['https://www.w3.org/ns/activitystreams#Public'],
+    object: actorUri,
+  };
+}

package/src/node/index.ts

@@ -141,6 +141,12 @@ export {
  * The ActivityPub actor + inbox + follow-graph router (actor GET incl. the
  * `instance` actor, inbox POST with HTTP-sig verify, followers/following pages).
  */
+/**
+ * A deleted local actor: its `Delete` of itself, and the `Tombstone` its URLs
+ * answer `410 Gone` with afterwards.
+ */
+export { buildActorDeleteActivity, goneTombstone, type IsActorGone } from './goneActor';
+
 export {
   createActorRouter,
   type ActorRouterConfig,

package/src/node/webfingerRouter.ts

@@ -17,6 +17,7 @@ import { discoveryCacheControl } from './httpCacheControl';
 import { isSameFederationHost } from '../apUri';
 import type { UrlBuilders } from '../urls';
 import { INSTANCE_ACTOR_USERNAME, normalizeActorUsername } from '../urls';
+import type { IsActorGone } from './goneActor';
 
 /** Default HTTP response max-age. The injected JRD cache has its own policy. */
 const WEBFINGER_CACHE_TTL = 3600;
@@ -65,6 +66,12 @@ export interface WebfingerRouterConfig {
     get(username: string): Promise<WebfingerJrd | null>;
     set(username: string, jrd: WebfingerJrd): void;
   };
+  /**
+   * Whether a username that resolved to nobody names a DELETED local actor
+   * (`goneActor.ts`). True ⇒ `410 Gone` instead of 404, which is what makes
+   * Mastodon delete its copy of the account. Omitted ⇒ every miss is a 404.
+   */
+  isActorGone?: IsActorGone;
   /** HTTP response TTL in whole seconds, 0..86400. Defaults to 3600; 0 sends no-store. */
   httpCacheTtlSeconds?: number;
   /** Diagnostics sink. */
@@ -147,7 +154,13 @@ export function createWebfingerRouter(config: WebfingerRouterConfig): Router {
       }
 
       const user = await config.resolveUser(username);
-      if (!user) return res.status(404).json({ error: 'User not found' });
+      if (!user) {
+        if (config.isActorGone && (await config.isActorGone(username))) {
+          res.set('Cache-Control', httpCacheControl);
+          return res.status(410).json({ error: 'User deleted' });
+        }
+        return res.status(404).json({ error: 'User not found' });
+      }
 
       // Sharing OFF must be indistinguishable from a nonexistent user — same 404
       // body, no separate error code. UNLIKE the other user-scoped surfaces,