@fedify/relay 2.4.0-dev.1832 → 2.4.0-dev.1848

package/README.md

@@ -40,33 +40,38 @@ subscribed instances, creating a shared pool of federated content.
 Relay protocols
 ---------------
 
-This package supports two popular relay protocols used in the fediverse:
+This package implements the relay-server side of the two relay protocols
+described by [FEP-ae0c].  It does not subscribe an existing ActivityPub
+application to remote relays.
+
+[FEP-ae0c]: https://w3id.org/fep/ae0c
 
 ### Mastodon-style relay
 
-The Mastodon-style relay protocol uses LD signatures for activity
-verification and follows the Public collection. This protocol is widely
-supported by Mastodon and many other ActivityPub implementations.
+Mastodon-style clients subscribe by sending a `Follow` whose object is the
+ActivityStreams Public collection to the relay's shared inbox.  The relay
+accepts or rejects the subscription and forwards signed activities directly to
+accepted subscribers.
 
-Key features:
+#### Key features
 
- -  Direct activity relaying with proper content types (`Create`, `Update`,
-    `Delete`, `Move`)
- -  LD signature verification and generation
- -  Follows the ActivityPub Public collection
- -  Simple subscription mechanism via `Follow` activities
+ -  Direct forwarding of `Create`, `Update`, `Delete`, `Move`, and `Announce`
+    activities
+ -  Immediate subscription state after approval
+ -  Subscription through the shared inbox URI
 
 ### LitePub-style relay
 
-The LitePub-style relay protocol uses bidirectional following relationships
-and wraps activities in `Announce` activities for distribution.
+LitePub-style clients subscribe by following the relay actor.  After approving
+the request, the relay follows the client actor back and waits for an `Accept`.
+It wraps forwarded objects in `Announce` activities.
 
-Key features:
+#### Key features
 
  -  Reciprocal following between relay and subscribers
- -  Activities wrapped in `Announce` for distribution
+ -  Activities distributed through `Announce`
  -  Two-phase subscription (pending → accepted)
- -  Enhanced federation capabilities
+ -  Subscription through the relay actor URI
 
 
 Installation
@@ -102,7 +107,7 @@ Usage
 
 ### Creating a relay
 
-Here's a simple example of creating a relay server using the factory function:
+Here's a simple example of creating a relay server using the factory function.
 
 ~~~~ typescript
 import { createRelay } from "@fedify/relay";
@@ -128,7 +133,7 @@ const relay = createRelay("mastodon", {
 Deno.serve((request) => relay.fetch(request));
 ~~~~
 
-You can also create a LitePub-style relay by changing the type:
+You can also create a LitePub-style relay by changing the type.
 
 ~~~~ typescript
 const relay = createRelay("litepub", {
@@ -138,10 +143,25 @@ const relay = createRelay("litepub", {
 });
 ~~~~
 
+The relay actor and shared inbox use fixed internal routes.  Retrieve their
+public URIs from the relay instead of constructing paths yourself.
+
+~~~~ typescript
+const actorUri = await relay.getActorUri();
+// https://relay.example.com/users/relay
+
+const inboxUri = await relay.getSharedInboxUri();
+// https://relay.example.com/inbox
+~~~~
+
+Give Mastodon-style clients the shared inbox URI and LitePub-style clients the
+actor URI.
+
 ### Subscription handling
 
 The `subscriptionHandler` is required and determines whether to approve or
-reject subscription requests.  For an open relay that accepts all subscriptions:
+reject subscription requests.  The following example creates an open relay that
+accepts all subscriptions.
 
 ~~~~ typescript
 const relay = createRelay("mastodon", {
@@ -151,7 +171,7 @@ const relay = createRelay("mastodon", {
 });
 ~~~~
 
-You can also implement custom approval logic:
+You can also implement custom approval logic.
 
 ~~~~ typescript
 const relay = createRelay("mastodon", {
@@ -199,7 +219,7 @@ if (follower) {
 
 The relay's `fetch()` method returns a standard `Response` object, making it
 compatible with any web framework that supports the Fetch API.  Here's an
-example with Hono:
+example with Hono.
 
 ~~~~ typescript
 import { Hono } from "hono";
@@ -224,31 +244,44 @@ export default app;
 How it works
 ------------
 
-The relay operates by:
+1.  Actor registration—the relay presents itself as an `Application` actor at
+    `/users/relay`.
+2.  Subscription—Mastodon-style clients follow the Public collection;
+    LitePub-style clients follow the relay actor.
+3.  Approval—the relay's subscription handler determines whether to approve
+    the subscription and responds with `Accept` or `Reject`.
+4.  Forwarding—the relay handles `Create`, `Update`, `Delete`, `Move`, and
+    `Announce` activities delivered to its inbox.  Mastodon-style relays forward
+    them directly; LitePub-style relays wrap their objects in `Announce`.
+5.  Unsubscription—instances can unsubscribe by sending an `Undo` activity
+    wrapping their original `Follow` activity.
+
+
+Application responsibilities
+----------------------------
+
+`createRelay()` provides the relay-specific ActivityPub routes and behavior.
+The surrounding application remains responsible for HTTPS, persistent storage,
+a durable production queue, subscription policy, rate limiting, monitoring,
+and moderation.  WebFinger and NodeInfo discovery endpoints are not configured
+by this package.
 
-1.  **Actor registration**: The relay presents itself as a Service actor at
-    `/users/relay`
-2.  **Subscription**: Instances subscribe to the relay by sending a `Follow`
-    activity
-3.  **Approval**: The relay's subscription handler determines whether to
-    approve the subscription (responds with `Accept` or `Reject`)
-4.  **Forwarding**: When a subscribed instance sends activities (`Create`,
-    `Update`, `Delete`, `Move`) to the relay's inbox, the relay forwards them
-    to all other subscribed instances
-5.  **Unsubscription**: Instances can unsubscribe by sending an `Undo` activity
-    wrapping their original `Follow` activity
+The `subscriptionHandler` controls which actors become delivery recipients; it
+does not authorize publishing to the relay.  The relay does not require an
+activity sender to be a stored follower or inspect its audience for the Public
+collection, so deployments need to account for that behavior in their access
+and moderation policies.
 
 
 Storage requirements
 --------------------
 
-The relay requires a key–value store to persist:
+The relay requires a key–value store to persist the following data.
 
- -  Subscriber list and their Follow activity IDs
- -  Subscriber actor information
- -  Relay's cryptographic key pairs (RSA and Ed25519)
+ -  Subscriber actor information and subscription state
+ -  The relay's cryptographic key pairs (RSA and Ed25519)
 
-Any `KvStore` implementation from Fedify can be used, including:
+Any `KvStore` implementation from Fedify can be used, including the following.
 
  -  `MemoryKvStore` (for development/testing)
  -  `DenoKvStore` (Deno KV)
@@ -301,7 +334,7 @@ Public interface for ActivityPub relay implementations.
 
 #### Relay types
 
-The relay type is specified when calling `createRelay()`:
+The relay type is specified when calling `createRelay()`.
 
  -  `"mastodon"`: Mastodon-compatible relay using direct activity forwarding,
     immediate subscription approval, and LD signatures
@@ -310,7 +343,7 @@ The relay type is specified when calling `createRelay()`:
 
 ### `RelayOptions`
 
-Configuration options for the relay:
+Configuration options for the relay.
 
  -  `kv: KvStore` (required): Key–value store for persisting relay data
  -  `origin: string` (required): Relay's origin URL (e.g.,
@@ -326,7 +359,7 @@ Configuration options for the relay:
 
 ### `SubscriptionRequestHandler`
 
-A function that determines whether to approve a subscription request:
+A function that determines whether to approve a subscription request.
 
 ~~~~ typescript
 type SubscriptionRequestHandler = (
@@ -347,7 +380,7 @@ type SubscriptionRequestHandler = (
 
 ### `RelayFollower`
 
-A follower of the relay with validated Actor instance:
+A follower of the relay with validated Actor instance.
 
 ~~~~ typescript
 interface RelayFollower {

package/dist/factory.test.d.ts

@@ -0,0 +1,2 @@
+import { Temporal } from "temporal-polyfill";
+import { URLPattern } from "urlpattern-polyfill";

package/dist/factory.test.js

@@ -0,0 +1,21 @@
+import "temporal-polyfill";
+import "urlpattern-polyfill";
+globalThis.addEventListener = () => {};
+import { MemoryKvStore } from "@fedify/fedify";
+import { createRelay } from "@fedify/relay";
+import { strictEqual } from "node:assert";
+import test, { describe } from "node:test";
+//#region src/factory.test.ts
+describe("createRelay", () => {
+	for (const type of ["mastodon", "litepub"]) test(`${type} exposes the canonical relay URIs`, async () => {
+		const relay = createRelay(type, {
+			kv: new MemoryKvStore(),
+			origin: "https://relay.example.com",
+			subscriptionHandler: () => Promise.resolve(true)
+		});
+		strictEqual((await relay.getActorUri()).href, "https://relay.example.com/users/relay");
+		strictEqual((await relay.getSharedInboxUri()).href, "https://relay.example.com/inbox");
+	});
+});
+//#endregion
+export {};

package/dist/litepub.test.js

@@ -4,10 +4,10 @@ globalThis.addEventListener = () => {};
 import { t as isRelayFollowerData } from "./types-BDWJ2_j0.js";
 import { MemoryKvStore, signRequest } from "@fedify/fedify";
 import { createRelay } from "@fedify/relay";
-import { Accept, Announce, Create, Delete, Follow, Move, Note, Person, Undo, Update } from "@fedify/vocab";
-import { exportSpki, getDocumentLoader } from "@fedify/vocab-runtime";
 import { deepStrictEqual, ok, strictEqual } from "node:assert";
 import test, { describe } from "node:test";
+import { Accept, Announce, Create, Delete, Follow, Move, Note, Person, Undo, Update } from "@fedify/vocab";
+import { exportSpki, getDocumentLoader } from "@fedify/vocab-runtime";
 //#region src/litepub.test.ts
 const mockDocumentLoader = async (url) => {
 	if (url === "https://remote.example.com/users/alice" || url === "https://remote.example.com/users/alice#main-key") return {
@@ -199,12 +199,31 @@ describe("LitePubRelay", () => {
 			body: JSON.stringify(await followActivity.toJsonLd({ contextLoader: mockDocumentLoader }))
 		});
 		request = await signRequest(request, rsaKeyPair.privateKey, rsaPublicKey.id);
-		await relay.fetch(request);
+		const originalFetch = globalThis.fetch;
+		const deliveredActivities = [];
+		globalThis.fetch = (async (input, init) => {
+			const outboundRequest = input instanceof Request ? input : new Request(input, init);
+			if (outboundRequest.url === "https://remote.example.com/users/alice/inbox") {
+				deliveredActivities.push(await outboundRequest.json());
+				return new Response(null, { status: 202 });
+			}
+			return originalFetch(input, init);
+		});
+		try {
+			await relay.fetch(request);
+		} finally {
+			globalThis.fetch = originalFetch;
+		}
 		strictEqual(handlerCalled, true);
 		ok(handlerActor);
 		const followerData = await kv.get(["follower", "https://remote.example.com/users/alice"]);
 		ok(isRelayFollowerData(followerData));
 		strictEqual(followerData.state, "pending");
+		const reciprocalFollow = deliveredActivities.find((activity) => activity.type === "Follow");
+		ok(reciprocalFollow, "Expected a reciprocal Follow activity");
+		strictEqual(reciprocalFollow.actor, "https://relay.example.com/users/relay");
+		strictEqual(reciprocalFollow.object, "https://remote.example.com/users/alice");
+		strictEqual(reciprocalFollow.to, "https://remote.example.com/users/alice");
 	});
 	test("handles Follow activity with subscription rejection", async () => {
 		const kv = new MemoryKvStore();
@@ -539,6 +558,65 @@ describe("LitePubRelay", () => {
 		const response = await relay.fetch(request);
 		ok(response.status === 200 || response.status === 202);
 	});
+	test("forwards activities only to accepted followers", async () => {
+		const kv = new MemoryKvStore();
+		const pendingFollower = new Person({
+			id: new URL("https://pending.example.com/users/bob"),
+			preferredUsername: "bob",
+			inbox: new URL("https://pending.example.com/users/bob/inbox")
+		});
+		const acceptedFollower = new Person({
+			id: new URL("https://accepted.example.com/users/carol"),
+			preferredUsername: "carol",
+			inbox: new URL("https://accepted.example.com/users/carol/inbox")
+		});
+		await kv.set(["follower", pendingFollower.id.href], {
+			actor: await pendingFollower.toJsonLd(),
+			state: "pending"
+		});
+		await kv.set(["follower", acceptedFollower.id.href], {
+			actor: await acceptedFollower.toJsonLd(),
+			state: "accepted"
+		});
+		const relay = createRelay("litepub", {
+			kv,
+			origin: "https://relay.example.com",
+			documentLoaderFactory: () => mockDocumentLoader,
+			authenticatedDocumentLoaderFactory: () => mockDocumentLoader,
+			subscriptionHandler: () => Promise.resolve(true)
+		});
+		const createActivity = new Create({
+			id: new URL("https://remote.example.com/activities/create/1"),
+			actor: new URL("https://remote.example.com/users/alice"),
+			object: new Note({
+				id: new URL("https://remote.example.com/notes/1"),
+				content: "Hello world"
+			})
+		});
+		let request = new Request("https://relay.example.com/inbox", {
+			method: "POST",
+			headers: { "Content-Type": "application/activity+json" },
+			body: JSON.stringify(await createActivity.toJsonLd({ contextLoader: mockDocumentLoader }))
+		});
+		request = await signRequest(request, rsaKeyPair.privateKey, rsaPublicKey.id);
+		const originalFetch = globalThis.fetch;
+		const deliveredInboxUrls = [];
+		globalThis.fetch = (async (input, init) => {
+			const outboundRequest = input instanceof Request ? input : new Request(input, init);
+			if (outboundRequest.url.endsWith("/inbox")) {
+				deliveredInboxUrls.push(outboundRequest.url);
+				return new Response(null, { status: 202 });
+			}
+			return await originalFetch(input, init);
+		});
+		try {
+			const response = await relay.fetch(request);
+			ok(response.status === 200 || response.status === 202);
+		} finally {
+			globalThis.fetch = originalFetch;
+		}
+		deepStrictEqual(deliveredInboxUrls, ["https://accepted.example.com/users/carol/inbox"]);
+	});
 	test("handles Update activity with Announce forwarding", async () => {
 		const relay = createRelay("litepub", {
 			kv: new MemoryKvStore(),

package/dist/mastodon.test.js

@@ -4,10 +4,10 @@ globalThis.addEventListener = () => {};
 import { t as isRelayFollowerData } from "./types-BDWJ2_j0.js";
 import { MemoryKvStore, signJsonLd, signRequest } from "@fedify/fedify";
 import { createRelay } from "@fedify/relay";
-import { Announce, Create, Delete, Follow, Move, Note, Person, Undo, Update } from "@fedify/vocab";
-import { exportSpki, getDocumentLoader } from "@fedify/vocab-runtime";
 import { deepStrictEqual, ok, strictEqual } from "node:assert";
 import test, { describe } from "node:test";
+import { Announce, Create, Delete, Follow, Move, Note, Person, Undo, Update } from "@fedify/vocab";
+import { exportSpki, getDocumentLoader } from "@fedify/vocab-runtime";
 //#region src/mastodon.test.ts
 const mockDocumentLoader = async (url) => {
 	if (url === "https://remote.example.com/users/alice" || url === "https://remote.example.com/users/alice#main-key") return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/relay",
-  "version": "2.4.0-dev.1832+1af9355c",
+  "version": "2.4.0-dev.1848+1443269f",
   "description": "ActivityPub relay support for Fedify",
   "keywords": [
     "Fedify",
@@ -47,14 +47,14 @@
   "dependencies": {
     "@logtape/logtape": "^2.2.0",
     "temporal-polyfill": "^1.0.1",
-    "@fedify/fedify": "^2.4.0-dev.1832+1af9355c",
-    "@fedify/vocab": "2.4.0-dev.1832+1af9355c"
+    "@fedify/fedify": "^2.4.0-dev.1848+1443269f",
+    "@fedify/vocab": "2.4.0-dev.1848+1443269f"
   },
   "devDependencies": {
     "tsdown": "^0.22.0",
     "typescript": "^6.0.0",
     "urlpattern-polyfill": "^10.1.0",
-    "@fedify/vocab-runtime": "^2.4.0-dev.1832+1af9355c"
+    "@fedify/vocab-runtime": "^2.4.0-dev.1848+1443269f"
   },
   "scripts": {
     "build:self": "tsdown",