@fedify/relay 2.0.0-dev.100

package/dist/mod.js

@@ -0,0 +1,414 @@
+
+        import { Temporal } from "@js-temporal/polyfill";
+      
+import { Accept, Announce, Create, Delete, Follow, Move, PUBLIC_COLLECTION, Reject, Undo, Update, createFederationBuilder, exportJwk, generateCryptoKeyPair, importJwk, isActor } from "@fedify/fedify";
+import { Application, Object as Object$1, isActor as isActor$1 } from "@fedify/fedify/vocab";
+import { getLogger } from "@logtape/logtape";
+
+//#region src/types.ts
+const RELAY_SERVER_ACTOR = "relay";
+/**
+* Type predicate to check if a value is valid RelayFollowerData from KV store.
+* Validates the storage format (JSON-LD), not the deserialized Actor instance.
+*
+* @param value The value to check
+* @returns true if the value is a RelayFollowerData
+* @internal
+*/
+function isRelayFollowerData(value) {
+	if (!value || typeof value !== "object") return false;
+	const obj = value;
+	return "actor" in obj && "state" in obj && typeof obj.state === "string" && (obj.state === "pending" || obj.state === "accepted");
+}
+
+//#endregion
+//#region src/builder.ts
+const relayBuilder = createFederationBuilder();
+relayBuilder.setActorDispatcher("/users/{identifier}", async (ctx, identifier) => {
+	if (identifier !== RELAY_SERVER_ACTOR) return null;
+	const keys = await ctx.getActorKeyPairs(identifier);
+	return new Application({
+		id: ctx.getActorUri(identifier),
+		preferredUsername: identifier,
+		name: ctx.data.name ?? "ActivityPub Relay",
+		inbox: ctx.getInboxUri(),
+		followers: ctx.getFollowersUri(identifier),
+		following: ctx.getFollowingUri(identifier),
+		url: ctx.getActorUri(identifier),
+		publicKey: keys[0].cryptographicKey,
+		assertionMethods: keys.map((k) => k.multikey)
+	});
+}).setKeyPairsDispatcher(async (ctx, identifier) => {
+	if (identifier !== RELAY_SERVER_ACTOR) return [];
+	const rsaPairJson = await ctx.data.kv.get([
+		"keypair",
+		"rsa",
+		identifier
+	]);
+	const ed25519PairJson = await ctx.data.kv.get([
+		"keypair",
+		"ed25519",
+		identifier
+	]);
+	if (rsaPairJson == null || ed25519PairJson == null) {
+		const rsaPair$1 = await generateCryptoKeyPair("RSASSA-PKCS1-v1_5");
+		const ed25519Pair$1 = await generateCryptoKeyPair("Ed25519");
+		await ctx.data.kv.set([
+			"keypair",
+			"rsa",
+			identifier
+		], {
+			privateKey: await exportJwk(rsaPair$1.privateKey),
+			publicKey: await exportJwk(rsaPair$1.publicKey)
+		});
+		await ctx.data.kv.set([
+			"keypair",
+			"ed25519",
+			identifier
+		], {
+			privateKey: await exportJwk(ed25519Pair$1.privateKey),
+			publicKey: await exportJwk(ed25519Pair$1.publicKey)
+		});
+		return [rsaPair$1, ed25519Pair$1];
+	}
+	const rsaPair = {
+		privateKey: await importJwk(rsaPairJson.privateKey, "private"),
+		publicKey: await importJwk(rsaPairJson.publicKey, "public")
+	};
+	const ed25519Pair = {
+		privateKey: await importJwk(ed25519PairJson.privateKey, "private"),
+		publicKey: await importJwk(ed25519PairJson.publicKey, "public")
+	};
+	return [rsaPair, ed25519Pair];
+});
+async function getFollowerActors(ctx) {
+	const actors = [];
+	for await (const { value } of ctx.data.kv.list(["follower"])) {
+		if (!isRelayFollowerData(value)) continue;
+		if (value.state !== "accepted") continue;
+		const actor = await Object$1.fromJsonLd(value.actor);
+		if (!isActor$1(actor)) continue;
+		actors.push(actor);
+	}
+	return actors;
+}
+async function dispatchRelayActors(ctx, identifier) {
+	if (identifier !== RELAY_SERVER_ACTOR) return null;
+	const actors = await getFollowerActors(ctx);
+	return { items: actors };
+}
+relayBuilder.setFollowersDispatcher("/users/{identifier}/followers", dispatchRelayActors);
+relayBuilder.setFollowingDispatcher("/users/{identifier}/following", dispatchRelayActors);
+
+//#endregion
+//#region src/base.ts
+/**
+* Abstract base class for relay implementations.
+* Provides common infrastructure for both Mastodon and LitePub relays.
+*
+* @internal
+*/
+var BaseRelay = class {
+	federationBuilder;
+	options;
+	federation;
+	constructor(options, relayBuilder$1) {
+		this.options = options;
+		this.federationBuilder = relayBuilder$1;
+	}
+	async fetch(request) {
+		if (this.federation == null) {
+			this.federation = await this.federationBuilder.build(this.options);
+			this.setupInboxListeners();
+		}
+		return await this.federation.fetch(request, { contextData: this.options });
+	}
+	/**
+	* Helper method to parse and validate follower data from storage.
+	* Deserializes JSON-LD actor data and validates it.
+	*
+	* @param actorId The actor ID of the follower
+	* @param data Raw data from KV store
+	* @returns RelayFollower object if valid, null otherwise
+	* @internal
+	*/
+	async parseFollowerData(actorId, data) {
+		if (!isRelayFollowerData(data)) return null;
+		const actor = await Object$1.fromJsonLd(data.actor);
+		if (!isActor$1(actor)) return null;
+		return {
+			actorId,
+			actor,
+			state: data.state
+		};
+	}
+	/**
+	* Lists all followers of the relay.
+	*
+	* @returns An async iterator of follower entries
+	*
+	* @example
+	* ```ts
+	* import { createRelay } from "@fedify/relay";
+	* import { MemoryKvStore } from "@fedify/fedify";
+	*
+	* const relay = createRelay("mastodon", {
+	*   kv: new MemoryKvStore(),
+	*   domain: "relay.example.com",
+	*   subscriptionHandler: async (ctx, actor) => true,
+	* });
+	*
+	* for await (const follower of relay.listFollowers()) {
+	*   console.log(`Follower: ${follower.actorId}`);
+	*   console.log(`State: ${follower.state}`);
+	*   console.log(`Actor: ${follower.actor.name}`);
+	* }
+	* ```
+	*
+	* @since 2.0.0
+	*/
+	async *listFollowers() {
+		for await (const entry of this.options.kv.list(["follower"])) {
+			const actorId = entry.key[1];
+			if (typeof actorId !== "string") continue;
+			const follower = await this.parseFollowerData(actorId, entry.value);
+			if (follower) yield follower;
+		}
+	}
+	/**
+	* Gets a specific follower by actor ID.
+	*
+	* @param actorId The actor ID (URL) of the follower to retrieve
+	* @returns The follower entry if found, null otherwise
+	*
+	* @example
+	* ```ts
+	* import { createRelay } from "@fedify/relay";
+	* import { MemoryKvStore } from "@fedify/fedify";
+	*
+	* const relay = createRelay("mastodon", {
+	*   kv: new MemoryKvStore(),
+	*   domain: "relay.example.com",
+	*   subscriptionHandler: async (ctx, actor) => true,
+	* });
+	*
+	* const follower = await relay.getFollower(
+	*   "https://mastodon.example.com/users/alice"
+	* );
+	* if (follower) {
+	*   console.log(`State: ${follower.state}`);
+	*   console.log(`Actor: ${follower.actor.preferredUsername}`);
+	* }
+	* ```
+	*
+	* @since 2.0.0
+	*/
+	async getFollower(actorId) {
+		const followerData = await this.options.kv.get(["follower", actorId]);
+		return await this.parseFollowerData(actorId, followerData);
+	}
+};
+
+//#endregion
+//#region src/follow.ts
+/**
+* Validate Follow activity and return follower actor if valid.
+* This validation is common to both Mastodon and LitePub relay protocols.
+*
+* @param ctx The federation context
+* @param follow The Follow activity to validate
+* @returns The follower Actor if valid, null otherwise
+*/
+async function validateFollowActivity(ctx, follow) {
+	if (follow.id == null || follow.objectId == null) return null;
+	const parsed = ctx.parseUri(follow.objectId);
+	const isPublicFollow = follow.objectId.href === "https://www.w3.org/ns/activitystreams#Public";
+	if (!isPublicFollow && parsed?.type !== "actor") return null;
+	const follower = await follow.getActor(ctx);
+	if (follower == null || follower.id == null || follower.preferredUsername == null || follower.inboxId == null) return null;
+	return follower;
+}
+/**
+* Send Accept or Reject response for a Follow activity.
+* This is common to both Mastodon and LitePub relay protocols.
+*
+* @param ctx The federation context
+* @param follow The Follow activity being responded to
+* @param follower The actor who sent the Follow
+* @param approved Whether the follow was approved
+*/
+async function sendFollowResponse(ctx, follow, follower, approved) {
+	const relayActorUri = ctx.getActorUri(RELAY_SERVER_ACTOR);
+	const Activity = approved ? Accept : Reject;
+	const action = approved ? "accepts" : "rejects";
+	await ctx.sendActivity({ identifier: RELAY_SERVER_ACTOR }, follower, new Activity({
+		id: new URL(`#${action}`, relayActorUri),
+		actor: relayActorUri,
+		object: follow
+	}));
+}
+/**
+* Handle Undo activity for Follow.
+* This logic is identical for both Mastodon and LitePub relay protocols.
+*
+* @param ctx The federation context
+* @param undo The Undo activity to handle
+* @param logger The logger instance to use for warnings
+*/
+async function handleUndoFollow(ctx, undo, logger$2) {
+	const activity = await undo.getObject({
+		crossOrigin: "trust",
+		...ctx
+	});
+	if (activity instanceof Follow) {
+		if (activity.id == null || activity.actorId == null) return;
+		await ctx.data.kv.delete(["follower", activity.actorId.href]);
+	} else logger$2.warn("Unsupported object type ({type}) for Undo activity: {object}", {
+		type: activity?.constructor.name,
+		object: activity
+	});
+}
+
+//#endregion
+//#region src/litepub.ts
+const logger$1 = getLogger([
+	"fedify",
+	"relay",
+	"litepub"
+]);
+/**
+* A LitePub-compatible ActivityPub relay implementation.
+* This relay follows LitePub's relay protocol and extensions for
+* enhanced federation capabilities.
+*
+* @since 2.0.0
+*/
+var LitePubRelay = class extends BaseRelay {
+	async #announceToFollowers(ctx, activity) {
+		const sender = await activity.getActor(ctx);
+		const excludeBaseUris = sender?.id ? [new URL(sender.id)] : [];
+		const announce = new Announce({
+			id: new URL(`/announce#${crypto.randomUUID()}`, ctx.origin),
+			actor: ctx.getActorUri(RELAY_SERVER_ACTOR),
+			object: activity.objectId,
+			to: PUBLIC_COLLECTION,
+			published: Temporal.Now.instant()
+		});
+		await ctx.sendActivity({ identifier: RELAY_SERVER_ACTOR }, "followers", announce, {
+			excludeBaseUris,
+			preferSharedInbox: true
+		});
+	}
+	setupInboxListeners() {
+		if (this.federation != null) this.federation.setInboxListeners("/users/{identifier}/inbox", "/inbox").on(Follow, async (ctx, follow) => {
+			const follower = await validateFollowActivity(ctx, follow);
+			if (!follower || !follower.id) return;
+			const existingFollow = await ctx.data.kv.get(["follower", follower.id.href]);
+			if (existingFollow?.state === "pending") return;
+			const approved = await this.options.subscriptionHandler(ctx, follower);
+			if (approved) {
+				await ctx.data.kv.set(["follower", follower.id.href], {
+					actor: await follower.toJsonLd(),
+					state: "pending"
+				});
+				await sendFollowResponse(ctx, follow, follower, approved);
+				const relayActorUri = ctx.getActorUri(RELAY_SERVER_ACTOR);
+				await ctx.sendActivity({ identifier: RELAY_SERVER_ACTOR }, follower, new Follow({
+					actor: relayActorUri,
+					object: follower.id,
+					to: follower.id
+				}));
+			} else await sendFollowResponse(ctx, follow, follower, approved);
+		}).on(Accept, async (ctx, accept) => {
+			const follow = await accept.getObject({
+				crossOrigin: "trust",
+				...ctx
+			});
+			if (!(follow instanceof Follow)) return;
+			const relayActorId = follow.actorId;
+			if (relayActorId == null) return;
+			const followerActor = await accept.getActor();
+			if (!isActor(followerActor) || !followerActor.id) return;
+			const parsed = ctx.parseUri(relayActorId);
+			if (parsed == null || parsed.type !== "actor") return;
+			const followerData = await ctx.data.kv.get(["follower", followerActor.id.href]);
+			if (followerData == null) return;
+			const updatedFollowerData = {
+				...followerData,
+				state: "accepted"
+			};
+			await ctx.data.kv.set(["follower", followerActor.id.href], updatedFollowerData);
+		}).on(Undo, async (ctx, undo) => await handleUndoFollow(ctx, undo, logger$1)).on(Create, async (ctx, create) => await this.#announceToFollowers(ctx, create)).on(Update, async (ctx, update) => await this.#announceToFollowers(ctx, update)).on(Move, async (ctx, move) => await this.#announceToFollowers(ctx, move)).on(Delete, async (ctx, deleteActivity) => await this.#announceToFollowers(ctx, deleteActivity)).on(Announce, async (ctx, announce) => await this.#announceToFollowers(ctx, announce));
+	}
+};
+
+//#endregion
+//#region src/mastodon.ts
+const logger = getLogger([
+	"fedify",
+	"relay",
+	"mastodon"
+]);
+/**
+* A Mastodon-compatible ActivityPub relay implementation.
+* This relay follows Mastodon's relay protocol for compatibility
+* with Mastodon instances.
+*
+* @since 2.0.0
+*/
+var MastodonRelay = class extends BaseRelay {
+	async #forwardToFollowers(ctx, activity) {
+		const sender = await activity.getActor(ctx);
+		const excludeBaseUris = sender?.id ? [new URL(sender.id)] : [];
+		await ctx.forwardActivity({ identifier: RELAY_SERVER_ACTOR }, "followers", {
+			skipIfUnsigned: true,
+			excludeBaseUris,
+			preferSharedInbox: true
+		});
+	}
+	setupInboxListeners() {
+		if (this.federation != null) this.federation.setInboxListeners("/users/{identifier}/inbox", "/inbox").on(Follow, async (ctx, follow) => {
+			const follower = await validateFollowActivity(ctx, follow);
+			if (!follower || !follower.id) return;
+			const approved = await this.options.subscriptionHandler(ctx, follower);
+			if (approved) await ctx.data.kv.set(["follower", follower.id.href], {
+				actor: await follower.toJsonLd(),
+				state: "accepted"
+			});
+			await sendFollowResponse(ctx, follow, follower, approved);
+		}).on(Undo, async (ctx, undo) => await handleUndoFollow(ctx, undo, logger)).on(Create, async (ctx, create) => await this.#forwardToFollowers(ctx, create)).on(Delete, async (ctx, deleteActivity) => await this.#forwardToFollowers(ctx, deleteActivity)).on(Move, async (ctx, move) => await this.#forwardToFollowers(ctx, move)).on(Update, async (ctx, update) => await this.#forwardToFollowers(ctx, update)).on(Announce, async (ctx, announce) => await this.#forwardToFollowers(ctx, announce));
+	}
+};
+
+//#endregion
+//#region src/factory.ts
+/**
+* Factory function to create a relay instance.
+*
+* @param type The type of relay to create ("mastodon" or "litepub")
+* @param options Configuration options for the relay
+* @returns A relay instance
+*
+* @example
+* ```ts
+* import { createRelay } from "@fedify/relay";
+* import { MemoryKvStore } from "@fedify/fedify";
+*
+* const relay = createRelay("mastodon", {
+*   kv: new MemoryKvStore(),
+*   domain: "relay.example.com",
+*   subscriptionHandler: async (ctx, actor) => true,
+* });
+* ```
+*
+* @since 2.0.0
+*/
+function createRelay(type, options) {
+	switch (type) {
+		case "mastodon": return new MastodonRelay(options, relayBuilder);
+		case "litepub": return new LitePubRelay(options, relayBuilder);
+	}
+}
+
+//#endregion
+export { RELAY_SERVER_ACTOR, createRelay };

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@fedify/relay",
+  "version": "2.0.0-dev.100+a9d733cc",
+  "description": "ActivityPub relay support for Fedify",
+  "keywords": [
+    "Fedify",
+    "ActivityPub",
+    "Fediverse",
+    "Relay"
+  ],
+  "author": {
+    "name": "Jiwon Kwon",
+    "email": "work@kwonjiwon.org"
+  },
+  "homepage": "https://fedify.dev/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fedify-dev/fedify.git",
+    "directory": "packages/relay"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/fedify-dev/fedify/issues"
+  },
+  "funding": [
+    "https://opencollective.com/fedify",
+    "https://github.com/sponsors/dahlia"
+  ],
+  "type": "module",
+  "main": "./dist/mod.cjs",
+  "module": "./dist/mod.js",
+  "types": "./dist/mod.d.ts",
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/mod.d.ts",
+        "require": "./dist/mod.d.cts",
+        "default": "./dist/mod.d.ts"
+      },
+      "import": "./dist/mod.js",
+      "require": "./dist/mod.cjs",
+      "default": "./dist/mod.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/",
+    "package.json"
+  ],
+  "dependencies": {
+    "@js-temporal/polyfill": "^0.5.1",
+    "@logtape/logtape": "^1.3.5"
+  },
+  "peerDependencies": {
+    "@fedify/fedify": "^2.0.0-dev.100+a9d733cc"
+  },
+  "devDependencies": {
+    "tsdown": "^0.12.9",
+    "typescript": "^5.9.3",
+    "@fedify/testing": "^2.0.0-dev.100+a9d733cc",
+    "@fedify/vocab-runtime": "^2.0.0-dev.100+a9d733cc"
+  },
+  "scripts": {
+    "build": "deno task codegen && tsdown",
+    "prepublish": "deno task codegen && tsdown",
+    "test": "deno task codegen && tsdown && node --test",
+    "test:bun": "deno task codegen && tsdown && bun test --timeout 60000"
+  }
+}