Add FEP-5711 collection inverse properties

Add FEP-5711 inverse properties to the bot actor's outbox and
followers collections by patching ActivityPub collection responses
in BotImpl.fetch().

Add fetch-level regression coverage for actor, collection root,
and paged collection responses, and document the change in the
bot concept docs and changelog.

Co-Authored-By: OpenAI Codex <codex@openai.com>

Author: dahlia

CHANGES.md

@@ -8,6 +8,9 @@ To be released.
 
 ### @fedify/botkit
 
+ -  Added FEP-5711 inverse properties to the bot actor's `outbox` and
+    `followers` collections.
+
  -  Added a remote follow button to the web interface.
     [[#10], [#14] by Hyeonseo Kim]
 

docs/concepts/bot.md

@@ -13,6 +13,12 @@ The `Bot` object is the main component of the library.  It is used to register
 event handlers, and provides the entry point of the bot—the `~Bot.fetch()`
 method to be connected to the HTTP server.
 
+BotKit also exposes the bot actor's standard ActivityPub collections.  The
+JSON-LD responses of the `outbox` and `followers` collections include the
+[FEP-5711] inverse properties `outboxOf` and `followersOf`.
+
+[FEP-5711]: https://w3id.org/fep/5711
+
 
 Instantiation
 -------------

packages/botkit/src/bot-impl.test.ts

@@ -2309,6 +2309,137 @@ test("BotImpl.fetch()", async () => {
   assert.deepStrictEqual(response2.status, 200);
 });
 
+test("BotImpl.fetch() includes FEP-5711 inverse properties", async () => {
+  const repository = new MemoryRepository();
+  const bot = new BotImpl<void>({
+    kv: new MemoryKvStore(),
+    repository,
+    username: "bot",
+    collectionWindow: 1,
+  });
+  const actorId = new URL("https://example.com/ap/actor/bot");
+
+  await repository.addFollower(
+    new URL("https://example.com/actor/1#follow"),
+    new Person({
+      id: new URL("https://example.com/actor/1"),
+      preferredUsername: "john",
+      inbox: new URL("https://example.com/actor/1/inbox"),
+    }),
+  );
+  await repository.addMessage(
+    "78acb1ea-4ac6-46b7-bcd4-3a8965d8126e",
+    new Create({
+      id: new URL(
+        "https://example.com/ap/actor/bot/create/78acb1ea-4ac6-46b7-bcd4-3a8965d8126e",
+      ),
+      actor: actorId,
+      to: PUBLIC_COLLECTION,
+      cc: new URL("https://example.com/ap/actor/bot/followers"),
+      object: new Note({
+        id: new URL("https://example.com/ap/actor/bot/note/1"),
+        attribution: actorId,
+        to: PUBLIC_COLLECTION,
+        cc: new URL("https://example.com/ap/actor/bot/followers"),
+        content: "Hello, world!",
+        published: Temporal.Instant.from("2025-01-01T00:00:00Z"),
+      }),
+      published: Temporal.Instant.from("2025-01-01T00:00:00Z"),
+    }),
+  );
+
+  const actorResponse = await bot.fetch(
+    new Request("https://example.com/ap/actor/bot", {
+      headers: { accept: "application/activity+json" },
+    }),
+  );
+  assert.deepStrictEqual(actorResponse.status, 200);
+  const actorJson = await actorResponse.json();
+  assert.deepStrictEqual(actorJson.id, actorId.href);
+  assert.deepStrictEqual(
+    actorJson.followers,
+    "https://example.com/ap/actor/bot/followers",
+  );
+  assert.deepStrictEqual(
+    actorJson.outbox,
+    "https://example.com/ap/actor/bot/outbox",
+  );
+
+  const outboxResponse = await bot.fetch(
+    new Request("https://example.com/ap/actor/bot/outbox", {
+      headers: { accept: "application/activity+json" },
+    }),
+  );
+  assert.deepStrictEqual(outboxResponse.status, 200);
+  const outboxJson = await outboxResponse.json();
+  assert.deepStrictEqual(outboxJson.type, "OrderedCollection");
+  assert.deepStrictEqual(
+    outboxJson.id,
+    "https://example.com/ap/actor/bot/outbox",
+  );
+  assert.deepStrictEqual(outboxJson.totalItems, 1);
+  assert.deepStrictEqual(
+    outboxJson.first,
+    "https://example.com/ap/actor/bot/outbox?cursor=",
+  );
+  assert.deepStrictEqual(outboxJson.outboxOf, actorId.href);
+
+  const outboxPageResponse = await bot.fetch(
+    new Request("https://example.com/ap/actor/bot/outbox?cursor=", {
+      headers: { accept: "application/activity+json" },
+    }),
+  );
+  assert.deepStrictEqual(outboxPageResponse.status, 200);
+  const outboxPageJson = await outboxPageResponse.json();
+  assert.deepStrictEqual(outboxPageJson.type, "OrderedCollectionPage");
+  assert.deepStrictEqual(
+    outboxPageJson.id,
+    "https://example.com/ap/actor/bot/outbox?cursor=",
+  );
+  assert.deepStrictEqual(
+    outboxPageJson.partOf,
+    "https://example.com/ap/actor/bot/outbox",
+  );
+  assert.deepStrictEqual(outboxPageJson.outboxOf, actorId.href);
+
+  const followersResponse = await bot.fetch(
+    new Request("https://example.com/ap/actor/bot/followers", {
+      headers: { accept: "application/activity+json" },
+    }),
+  );
+  assert.deepStrictEqual(followersResponse.status, 200);
+  const followersJson = await followersResponse.json();
+  assert.deepStrictEqual(followersJson.type, "OrderedCollection");
+  assert.deepStrictEqual(
+    followersJson.id,
+    "https://example.com/ap/actor/bot/followers",
+  );
+  assert.deepStrictEqual(followersJson.totalItems, 1);
+  assert.deepStrictEqual(
+    followersJson.first,
+    "https://example.com/ap/actor/bot/followers?cursor=0",
+  );
+  assert.deepStrictEqual(followersJson.followersOf, actorId.href);
+
+  const followersPageResponse = await bot.fetch(
+    new Request("https://example.com/ap/actor/bot/followers?cursor=0", {
+      headers: { accept: "application/activity+json" },
+    }),
+  );
+  assert.deepStrictEqual(followersPageResponse.status, 200);
+  const followersPageJson = await followersPageResponse.json();
+  assert.deepStrictEqual(followersPageJson.type, "OrderedCollectionPage");
+  assert.deepStrictEqual(
+    followersPageJson.id,
+    "https://example.com/ap/actor/bot/followers?cursor=0",
+  );
+  assert.deepStrictEqual(
+    followersPageJson.partOf,
+    "https://example.com/ap/actor/bot/followers",
+  );
+  assert.deepStrictEqual(followersPageJson.followersOf, actorId.href);
+});
+
 describe("BotImpl.addCustomEmoji(), BotImpl.addCustomEmojis()", () => {
   const bot = new BotImpl<void>({ kv: new MemoryKvStore(), username: "bot" });
 

packages/botkit/src/bot-impl.ts

@@ -1064,6 +1064,57 @@ export class BotImpl<TContextData> implements Bot<TContextData> {
     return new SessionImpl(this, ctx);
   }
 
+  async addCollectionInverseProperty(
+    request: Request,
+    contextData: TContextData,
+    response: Response,
+  ): Promise<Response> {
+    if (!response.ok) return response;
+    const ctx = this.federation.createContext(request, contextData);
+    const parsed = ctx.parseUri(new URL(request.url));
+    if (
+      parsed == null ||
+      (parsed.type !== "outbox" && parsed.type !== "followers") ||
+      parsed.identifier == null
+    ) {
+      return response;
+    }
+    const contentType = response.headers.get("Content-Type");
+    if (
+      contentType == null ||
+      (
+        !contentType.startsWith("application/activity+json") &&
+        !contentType.startsWith("application/ld+json")
+      )
+    ) {
+      return response;
+    }
+    const body = await response.json();
+    if (typeof body !== "object" || body == null || Array.isArray(body)) {
+      return new Response(JSON.stringify(body), {
+        headers: response.headers,
+        status: response.status,
+        statusText: response.statusText,
+      });
+    }
+    const property = parsed.type === "outbox" ? "outboxOf" : "followersOf";
+    const actorUri = ctx.getActorUri(parsed.identifier).href;
+    if (body[property] === actorUri) {
+      return new Response(JSON.stringify(body), {
+        headers: response.headers,
+        status: response.status,
+        statusText: response.statusText,
+      });
+    }
+    const headers = new Headers(response.headers);
+    headers.delete("Content-Length");
+    return new Response(JSON.stringify({ ...body, [property]: actorUri }), {
+      headers,
+      status: response.status,
+      statusText: response.statusText,
+    });
+  }
+
   async fetch(request: Request, contextData: TContextData): Promise<Response> {
     if (this.behindProxy) {
       request = await getXForwardedRequest(request);
@@ -1074,7 +1125,12 @@ export class BotImpl<TContextData> implements Bot<TContextData> {
       url.pathname.startsWith("/ap/") ||
       url.pathname.startsWith("/nodeinfo/")
     ) {
-      return await this.federation.fetch(request, { contextData });
+      const response = await this.federation.fetch(request, { contextData });
+      return await this.addCollectionInverseProperty(
+        request,
+        contextData,
+        response,
+      );
     }
     const match = /^\/emojis\/([a-z0-9-_]+)(?:$|\.)/.exec(url.pathname);
     if (match != null) {