洪 民憙 (Hong Minhee)

If you are a member of Codeberg e.V. please take the time to participate in the poll that was just sent out about banning vibe-coded projects on Codeberg.

Please agree to the proposal. Slop can live on GitHub.

We're pleased to announce BotKit 0.5.0. This release changes how both the docs site and every bot's own pages look, and it stops limiting a server to one bot: a single process can now host a whole fleet of them. Quoting, and being quoted, goes through a consent step under FEP-044f, and a Redis-backed repository joins the SQLite and PostgreSQL ones for shared production storage. A few of these changes are breaking; see below for what to check before you upgrade.

A new look for botkit.fedify.dev

Until this release, botkit.fedify.dev read like a stock VitePress site: a workable but generic shell wrapped around the docs, with none of BotKit's own personality showing through.

The theme and the landing page are both new. The palette now matches the real logo greens instead of a generic default, and headlines are set in Space Grotesk, paired with Inter for everything else; the display font is self-hosted, so no visitor's IP is handed to a font CDN. The new landing page frames BotKit's dinosaur mascot inside its signature unassembled-model-kit sprue frame, then leads with a tabbed installer for Deno, npm, pnpm, and Yarn and a one-file bot example before getting into what BotKit actually does: messages, events, multi-bot instances, and the pages it builds for a bot without any extra work from you.

The deployment guides grew alongside the new landing page: they were split apart and fleshed out, and a new Cloudflare Workers guide joins the existing Deno Deploy, Docker, and self-hosting guides.

A new look for your bot's pages

The pages BotKit serves for your bot (its profile, its posts, its follower list) got the same attention, in the opposite direction. Until now they were built on Pico CSS pulled from an external CDN: a fine default, but a generic one that made every BotKit-hosted bot look like a demo of the same template, and that quietly sent every visitor's browser off to fetch a stylesheet from someone else's server.

That's gone. Bot pages now use a self-contained design system, bundled with the package and served from BotKit's own content-addressed, cache-forever path: no external CDN, no build step, on either Deno or Node.js. The whole look is driven by a single accent color you choose (twenty names, the same legend Pico CSS uses, so your existing choice of color still works), tinting links, the follow button, and small highlights, while everything else stays quiet so your bot's name, avatar, and posts are what a visitor actually notices. A new PagesOptions.theme option ("auto", "light", or "dark") controls the color scheme independently of the accent. A repost is now marked and attributed to its original author instead of blending into the bot's own timeline.

If you want to go further than the accent color allows, PagesOptions.css still lets you inject custom CSS on top of BotKit's own stylesheet.

Multi-bot instances

Until this release, a BotKit process could only ever be one bot. Running a second bot meant standing up a whole second server, even when the two bots could easily have shared the same infrastructure. That limitation, raised in #16, is gone: the new createInstance() function creates an Instance that owns the shared plumbing (the key–value store, the message queue, the repository, and HTTP handling), and any number of bots can live on it side by side, each with its own actor identity and event handlers.

For a fixed, known set of bots, Instance.createBot() takes an identifier and a profile:

import { createInstance, text } from "@fedify/botkit";
import { MemoryKvStore } from "@fedify/fedify";

const instance = createInstance<void>({ kv: new MemoryKvStore() });

const greetBot = instance.createBot("greet", {
  username: "greetbot",
  name: "Greeting Bot",
});

greetBot.onFollow = async (session, followRequest) => {
  await followRequest.accept();
  await session.publish(text`Welcome, ${followRequest.follower}!`);
};

For a family of bots resolved on demand (one per region, one per customer, thousands of them backed by a database), pass a dispatcher function instead of a fixed identifier, and BotKit resolves and federates each one lazily:

const weatherBots = instance.createBot(async (ctx, identifier) => {
  if (!identifier.startsWith("weather_")) return null;
  const region = await db.getRegion(identifier.slice("weather_".length));
  if (region == null) return null;
  return { username: identifier, name: `${region.name} Weather Bot` };
});

weatherBots.onMention = async (session, message) => {
  const code = session.bot.identifier.slice("weather_".length);
  await message.reply(text`Current weather: ${await db.getWeather(code)}`);
};

Incoming activities are routed only to the bots they actually concern: the followed bot, the owner of a liked or replied-to message, mentioned bots, and bots followed by the sender. Multi-bot instances also serve a list of hosted bots at the web root, with each bot's own pages moving to /@{username}; a reserved instance actor signs shared-inbox requests when there's no single bot whose key obviously should.

None of this touches single-bot deployments: createBot() keeps working exactly as it always has, with the bot's pages staying at the web root and its data migrated to the new storage layout automatically on startup. If you maintain a custom Repository implementation, though, this is a breaking change worth planning for: every method now takes the owning bot's identifier as its first parameter, Session.bot is a read-only ReadonlyBot instead of a mutable Bot, and local object URIs carry the owning bot's identifier (old-format URIs are still recognized and permanently redirected, so links other servers stored keep working). The full picture, including how to move an existing single-bot deployment onto a multi-bot instance later, is in the new Instance concept document.

Thanks to @moreal, whose early work-in-progress explorations of this problem surfaced its two hardest design questions (mapping usernames to identifiers for dynamic bots, and routing object URIs that used to carry no owner information) well before this implementation settled on its final shape.

Consent-respecting quotes with FEP-044f

BotKit has supported quoting since 0.2.0, but only in the Misskey family's style: a quoteUrl property and a Link tag, sent without ever asking the quoted author. Mastodon 4.4 and 4.5 do things differently: they verify quotes through FEP-044f's consent handshake before showing them as quotes at all. Without that handshake, a BotKit bot's quotes never rendered as quotes on Mastodon, and quotes of a BotKit bot showed up as unverifiable.

BotKit now handles the FEP-044f handshake in both directions. When you quote a message, it sets the FEP-044f quote property and sends a QuoteRequest to the quoted author, alongside the Create it already sent. Publishing stays non-blocking: the post goes out immediately, and the quote is upgraded once (or if) approval arrives:

const message = await session.publish(text`This message quotes another one.`, {
  quoteTarget: quoted,
});
console.log(message.quoteApprovalState); // "pending"

On the receiving side, a new quotePolicy option (on createBot(), and per message on Session.publish()) controls how your bot answers incoming quote requests: automatically for everyone ("public", the default), automatically for followers only, never ("nobody"), or held for manual review through the new Bot.onQuoteRequest event:

bot.onQuoteRequest = async (session, request) => {
  if (request.state === "pending") await request.accept();
};

Bot.onQuoteAccepted, Bot.onQuoteRejected, and Bot.onQuoteRevoked cover what happens next for quotes your own bot sent, Message.quoteApproved reports whether an incoming quote carries a valid authorization stamp, and AuthorizedMessage.unauthorizeQuote() lets you revoke one you previously granted. The legacy quoteUrl and Misskey-style tags are still sent alongside the new property, so nothing about quoting on Misskey and its relatives changes. The full design is spread across #27 through #33.

A Redis repository (@fedify/botkit-redis)

BotKit has had a SQLite repository since 0.3.0 and a PostgreSQL one since 0.4.0, but neither is the natural fit for a bot that runs as several worker processes sharing one store, which is exactly the shape a Redis-backed deployment usually takes. The new @fedify/botkit-redis package fills that gap with RedisRepository, built directly on Redis strings, sets, and sorted sets rather than going through a generic key–value abstraction:

import { createBot, MemoryKvStore } from "@fedify/botkit";
import { RedisRepository } from "@fedify/botkit-redis";

const bot = createBot({
  username: "mybot",
  kv: new MemoryKvStore(),
  repository: new RedisRepository({ url: "redis://localhost:6379/0" }),
});

Because several workers can share one Redis instance, the read-modify-write paths that matter most under concurrency (message updates, follower bookkeeping, quote authorization indexes) are protected by short-lived locks that get renewed while a slow update is still running, rather than by assuming only one process ever touches the data at a time. The package supports both a connection URL it manages itself and an existing node-redis client you inject and keep control of, and it's available for both Deno and Node.js. #12 and #35 cover the rest of it.

Smaller improvements

The npm package's TypeScript declaration files no longer accidentally include the runtime Temporal polyfill code, which had been leaking into consumers' .d.ts output. Fedify was upgraded to 2.3.1, Hono to 4.12.27, and LogTape to 2.2.3.

As always, the full list of changes is in CHANGES.md, and every API mentioned above is documented at botkit.fedify.dev. Thank you to everyone who filed issues, opened discussions, and tried BotKit out.

If you build something with BotKit, run into a rough edge, or just want to talk through an idea before opening an issue, GitHub Discussions is the place for exactly that. For something closer to real time, BotKit's chat now lives on Matrix at #fedify:matrix.org. Drop in and say hello.

We're pleased to announce BotKit 0.5.0. This release changes how both the docs site and every bot's own pages look, and it stops limiting a server to one bot: a single process can now host a whole fleet of them. Quoting, and being quoted, goes through a consent step under FEP-044f, and a Redis-backed repository joins the SQLite and PostgreSQL ones for shared production storage. A few of these changes are breaking; see below for what to check before you upgrade.

A new look for botkit.fedify.dev

Until this release, botkit.fedify.dev read like a stock VitePress site: a workable but generic shell wrapped around the docs, with none of BotKit's own personality showing through.

The theme and the landing page are both new. The palette now matches the real logo greens instead of a generic default, and headlines are set in Space Grotesk, paired with Inter for everything else; the display font is self-hosted, so no visitor's IP is handed to a font CDN. The new landing page frames BotKit's dinosaur mascot inside its signature unassembled-model-kit sprue frame, then leads with a tabbed installer for Deno, npm, pnpm, and Yarn and a one-file bot example before getting into what BotKit actually does: messages, events, multi-bot instances, and the pages it builds for a bot without any extra work from you.

The deployment guides grew alongside the new landing page: they were split apart and fleshed out, and a new Cloudflare Workers guide joins the existing Deno Deploy, Docker, and self-hosting guides.

A new look for your bot's pages

The pages BotKit serves for your bot (its profile, its posts, its follower list) got the same attention, in the opposite direction. Until now they were built on Pico CSS pulled from an external CDN: a fine default, but a generic one that made every BotKit-hosted bot look like a demo of the same template, and that quietly sent every visitor's browser off to fetch a stylesheet from someone else's server.

That's gone. Bot pages now use a self-contained design system, bundled with the package and served from BotKit's own content-addressed, cache-forever path: no external CDN, no build step, on either Deno or Node.js. The whole look is driven by a single accent color you choose (twenty names, the same legend Pico CSS uses, so your existing choice of color still works), tinting links, the follow button, and small highlights, while everything else stays quiet so your bot's name, avatar, and posts are what a visitor actually notices. A new PagesOptions.theme option ("auto", "light", or "dark") controls the color scheme independently of the accent. A repost is now marked and attributed to its original author instead of blending into the bot's own timeline.

If you want to go further than the accent color allows, PagesOptions.css still lets you inject custom CSS on top of BotKit's own stylesheet.

Multi-bot instances

Until this release, a BotKit process could only ever be one bot. Running a second bot meant standing up a whole second server, even when the two bots could easily have shared the same infrastructure. That limitation, raised in #16, is gone: the new createInstance() function creates an Instance that owns the shared plumbing (the key–value store, the message queue, the repository, and HTTP handling), and any number of bots can live on it side by side, each with its own actor identity and event handlers.

For a fixed, known set of bots, Instance.createBot() takes an identifier and a profile:

import { createInstance, text } from "@fedify/botkit";
import { MemoryKvStore } from "@fedify/fedify";

const instance = createInstance<void>({ kv: new MemoryKvStore() });

const greetBot = instance.createBot("greet", {
  username: "greetbot",
  name: "Greeting Bot",
});

greetBot.onFollow = async (session, followRequest) => {
  await followRequest.accept();
  await session.publish(text`Welcome, ${followRequest.follower}!`);
};

For a family of bots resolved on demand (one per region, one per customer, thousands of them backed by a database), pass a dispatcher function instead of a fixed identifier, and BotKit resolves and federates each one lazily:

const weatherBots = instance.createBot(async (ctx, identifier) => {
  if (!identifier.startsWith("weather_")) return null;
  const region = await db.getRegion(identifier.slice("weather_".length));
  if (region == null) return null;
  return { username: identifier, name: `${region.name} Weather Bot` };
});

weatherBots.onMention = async (session, message) => {
  const code = session.bot.identifier.slice("weather_".length);
  await message.reply(text`Current weather: ${await db.getWeather(code)}`);
};

Incoming activities are routed only to the bots they actually concern: the followed bot, the owner of a liked or replied-to message, mentioned bots, and bots followed by the sender. Multi-bot instances also serve a list of hosted bots at the web root, with each bot's own pages moving to /@{username}; a reserved instance actor signs shared-inbox requests when there's no single bot whose key obviously should.

None of this touches single-bot deployments: createBot() keeps working exactly as it always has, with the bot's pages staying at the web root and its data migrated to the new storage layout automatically on startup. If you maintain a custom Repository implementation, though, this is a breaking change worth planning for: every method now takes the owning bot's identifier as its first parameter, Session.bot is a read-only ReadonlyBot instead of a mutable Bot, and local object URIs carry the owning bot's identifier (old-format URIs are still recognized and permanently redirected, so links other servers stored keep working). The full picture, including how to move an existing single-bot deployment onto a multi-bot instance later, is in the new Instance concept document.

Thanks to @moreal, whose early work-in-progress explorations of this problem surfaced its two hardest design questions (mapping usernames to identifiers for dynamic bots, and routing object URIs that used to carry no owner information) well before this implementation settled on its final shape.

Consent-respecting quotes with FEP-044f

BotKit has supported quoting since 0.2.0, but only in the Misskey family's style: a quoteUrl property and a Link tag, sent without ever asking the quoted author. Mastodon 4.4 and 4.5 do things differently: they verify quotes through FEP-044f's consent handshake before showing them as quotes at all. Without that handshake, a BotKit bot's quotes never rendered as quotes on Mastodon, and quotes of a BotKit bot showed up as unverifiable.

BotKit now handles the FEP-044f handshake in both directions. When you quote a message, it sets the FEP-044f quote property and sends a QuoteRequest to the quoted author, alongside the Create it already sent. Publishing stays non-blocking: the post goes out immediately, and the quote is upgraded once (or if) approval arrives:

const message = await session.publish(text`This message quotes another one.`, {
  quoteTarget: quoted,
});
console.log(message.quoteApprovalState); // "pending"

On the receiving side, a new quotePolicy option (on createBot(), and per message on Session.publish()) controls how your bot answers incoming quote requests: automatically for everyone ("public", the default), automatically for followers only, never ("nobody"), or held for manual review through the new Bot.onQuoteRequest event:

bot.onQuoteRequest = async (session, request) => {
  if (request.state === "pending") await request.accept();
};

Bot.onQuoteAccepted, Bot.onQuoteRejected, and Bot.onQuoteRevoked cover what happens next for quotes your own bot sent, Message.quoteApproved reports whether an incoming quote carries a valid authorization stamp, and AuthorizedMessage.unauthorizeQuote() lets you revoke one you previously granted. The legacy quoteUrl and Misskey-style tags are still sent alongside the new property, so nothing about quoting on Misskey and its relatives changes. The full design is spread across #27 through #33.

A Redis repository (@fedify/botkit-redis)

BotKit has had a SQLite repository since 0.3.0 and a PostgreSQL one since 0.4.0, but neither is the natural fit for a bot that runs as several worker processes sharing one store, which is exactly the shape a Redis-backed deployment usually takes. The new @fedify/botkit-redis package fills that gap with RedisRepository, built directly on Redis strings, sets, and sorted sets rather than going through a generic key–value abstraction:

import { createBot, MemoryKvStore } from "@fedify/botkit";
import { RedisRepository } from "@fedify/botkit-redis";

const bot = createBot({
  username: "mybot",
  kv: new MemoryKvStore(),
  repository: new RedisRepository({ url: "redis://localhost:6379/0" }),
});

Because several workers can share one Redis instance, the read-modify-write paths that matter most under concurrency (message updates, follower bookkeeping, quote authorization indexes) are protected by short-lived locks that get renewed while a slow update is still running, rather than by assuming only one process ever touches the data at a time. The package supports both a connection URL it manages itself and an existing node-redis client you inject and keep control of, and it's available for both Deno and Node.js. #12 and #35 cover the rest of it.

Smaller improvements

The npm package's TypeScript declaration files no longer accidentally include the runtime Temporal polyfill code, which had been leaking into consumers' .d.ts output. Fedify was upgraded to 2.3.1, Hono to 4.12.27, and LogTape to 2.2.3.

As always, the full list of changes is in CHANGES.md, and every API mentioned above is documented at botkit.fedify.dev. Thank you to everyone who filed issues, opened discussions, and tried BotKit out.

If you build something with BotKit, run into a rough edge, or just want to talk through an idea before opening an issue, GitHub Discussions is the place for exactly that. For something closer to real time, BotKit's chat now lives on Matrix at #fedify:matrix.org. Drop in and say hello.

If you are a member of Codeberg e.V. please take the time to participate in the poll that was just sent out about banning vibe-coded projects on Codeberg.

Please agree to the proposal. Slop can live on GitHub.

A quiet failure

Picture the moment your server sends its first Follow activity to Mastodon. You read the spec, built the JSON, signed the HTTP request, and POSTed it with care. What comes back is a single line: 401 Unauthorized. No body. No explanation.

What went wrong? Maybe the clock behind your Date header drifted a few minutes. Maybe the hash in your Digest header is off. Maybe you uppercased the (request-target) pseudo-header while building the signing string, or published your public key as PEM where the other side wanted multibase. The remote server won't tell you. So you start reading someone else's server code to debug your own.

I know, because I've been there. Fedify began as a casualty of another project. I set out to build a single-user microblogging server, the one that would later become Hollo, and started implementing ActivityPub from scratch. Somewhere between the signature specs and the JSON-LD, the protocol work swallowed the product, and I put the whole thing down. What I picked back up wasn't the app. It was the framework the app should have had. Fedify shipped first; only then could Hollo exist, built on top of it. (I've told this story at more length in A year with the fediverse.)

ActivityPub development gets hard in a few very specific places. In this post I want to walk through five of them, then show what each one looks like with Fedify. If you've spent time in the fediverse, you'll probably nod along. If you haven't, you may wonder why anyone would do all of this by hand. Either way, the conclusion is the same: nobody has to anymore.

Five scenes

Scene 1: there is more than one standard

ActivityPub servers authenticate each other with HTTP signatures. Except there isn't one signature spec. Most of the fediverse runs on draft-cavage-http-signatures-12, an expired draft that never became a standard. The actual standard exists too: RFC 9421, HTTP Message Signatures. The problem is that you can't know which one a given server accepts until you try.

A real-world implementation therefore has to sign with one spec, see whether it gets rejected, re-sign with the other, and remember per server which one worked so it can skip the dance next time. The fediverse calls this double-knocking. Yes, you get to implement it yourself.

That's still not the end. HTTP signatures only prove who sent a request. For situations like inbox forwarding, where you relay an activity you received to a third party, you need signatures that live on the document itself: Linked Data Signatures and Object Integrity Proofs. Four signature mechanisms in total, and two kinds of keys to manage: RSA and Ed25519.

Scene 2: one document, many shapes

ActivityPub's wire format is JSON-LD, and in JSON-LD the same document can take many shapes. This is easier to show than to explain. Here is a Create activity one server might send:

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "type": "Create",
  "actor": "https://example.com/users/alice",
  "to": "https://www.w3.org/ns/activitystreams#Public",
  "object": {
    "type": "Note",
    "id": "https://example.com/notes/123",
    "content": "Hello, fediverse!"
  }
}

And here is a semantically identical activity from another server:

{
  "@context": ["https://www.w3.org/ns/activitystreams"],
  "type": "Create",
  "actor": {
    "type": "Person",
    "id": "https://example.com/users/alice",
    "preferredUsername": "alice"
  },
  "to": ["as:Public"],
  "object": "https://example.com/notes/123"
}

actor turned from a URI string into an inline object. to turned from a string into an array. object went the other way, from an inline object to a URI. Even the address that means “public” has three valid spellings: https://www.w3.org/ns/activitystreams#Public, as:Public, and plain Public. Your parser has to accept every combination, and which one arrives depends on the sender's implementation.

The spec-compliant answer is to normalize every document with a JSON-LD processor, expansion followed by compaction. In practice many implementations treat it all as “just JSON” and quietly break on whatever shape some server happens to emit. Either way, you end up with defensive code smeared across the whole codebase: is this a string? An array? An object? A URI I have to fetch?

Scene 3: the zombie post

A user publishes a post, spots a typo, and deletes it right away. Your server sends a Create, then a Delete. Thanks to network weather, some receiving server gets the Delete first and the Create second. It ignores the deletion of a post that doesn't exist yet, then dutifully processes the creation of a post that was already deleted. That post now lives on that server forever, while its author believes it's gone.

Then there's scale. With five thousand followers, one post means thousands of HTTP deliveries. Do that inline in the request handler and your publish button takes half a minute to respond, or the server falls over. Fine, use a queue. Deliveries fail, so retry them. On what schedule? Exponential backoff. How many times? And is a 500 Internal Server Error the same kind of failure as a 410 Gone? When do you clean up three thousand followers on a server that no longer exists? Should you keep hammering a host that has been down for days?

At some point it dawns on you that this is no longer protocol implementation. It's distributed systems engineering.

Scene 4: it's not a spec, it's an ecosystem

Even perfect spec compliance doesn't buy you interoperability. A few examples from the field:

• Mastodon's secure mode requires HTTP signatures on GET requests too (so-called authorized fetch). Now suppose both servers run in that mode. To fetch the other side's public key you must sign your request; to verify your signature, the other side must first fetch your key. Deadlock. The community's workaround is to sign with an “instance actor” that represents the server itself. You won't find that in the spec.
• Threads can't parse activities whose actor is embedded as an inline object. When sending to Threads, the actor has to be a URI.
• Lemmy silently rejects Group actors that lack fields Mastodon never asks for, such as a moderators collection linked via attributedTo and a featured collection.
• Misskey carries vocabulary extensions of its own; quote posts alone go by three different property names across implementations.

The list keeps growing. Interoperability here is not something you finish once and stop thinking about. It's maintenance, forever.

Scene 5: insecure by default

Build it from scratch, and you start out wide open. Skip signature verification on incoming activities and anyone can inject a forged Follow or Delete. Leave the document loader unrestricted and a malicious activity can point it at http://169.254.169.254/ or your internal network, turning your server into an SSRF proxy. Skip origin checks on embedded objects and any server can hand out a document claiming “here's what the Mastodon lead developer said.”

What these traps share is that nothing happens when you fall into them. Everything appears to work. Until someone exploits it.

Ghost ran into this too

If you're thinking “surely our team would manage,” consider Ghost: a leading open-source publishing platform used by thousands of journalists and creators, and a team that set out to build its own ActivityPub support.

We can definitely attest to the problems that Fedify is working hard to solve, because even in just a few weeks of early prototyping we were running into the issues described above right away.

From Alright, let's Fedify

Ghost ended up building its ActivityPub layer on Fedify.

So I put all of it in a framework

Fedify is a TypeScript library for building federated server apps on ActivityPub and the standards around it. It runs on Deno, Node.js, and Bun, and supports edge runtimes like Cloudflare Workers. The design goal hasn't changed since the beginning: keep everything in those five scenes out of application code.

Here are the same five scenes again, this time with Fedify.

Scene 1, revisited: the signature war is the framework's job

Here is everything it takes to put one actor on the fediverse:

import { createFederation, generateCryptoKeyPair, MemoryKvStore } from "@fedify/fedify";
import { Endpoints, Person } from "@fedify/vocab";

const federation = createFederation<void>({
  kv: new MemoryKvStore(),  // Swap for Redis, PostgreSQL, etc. in production
});

federation
  .setActorDispatcher("/users/{identifier}", async (ctx, identifier) => {
    if (identifier !== "alice") return null;
    const keyPairs = await ctx.getActorKeyPairs(identifier);
    return new Person({
      id: ctx.getActorUri(identifier),
      preferredUsername: identifier,
      name: "Alice",
      inbox: ctx.getInboxUri(identifier),
      endpoints: new Endpoints({ sharedInbox: ctx.getInboxUri() }),
      publicKey: keyPairs[0].cryptographicKey,
      assertionMethods: keyPairs.map((keyPair) => keyPair.multikey),
    });
  })
  .setKeyPairsDispatcher(async (ctx, identifier) => {
    // In real code you'd persist these in a database; this shows the gist
    return [await generateCryptoKeyPair()];
  });

The moment this code runs:

• Every outgoing request gets signed. With an RSA key, Fedify emits HTTP Signatures and Linked Data Signatures; add an Ed25519 key and it attaches Object Integrity Proofs as well. All four mechanisms coexist on a single activity, and each receiver verifies with the strongest one it understands.
• Fedify does the double-knocking for you: first contact goes out as RFC 9421, a rejection triggers a draft-cavage retry, and the winning spec is cached per server. If the rejection carries an Accept-Signature challenge (RFC 9421 §5), Fedify reads it and re-signs with exactly the components the server asked for.
• Incoming signatures are verified before your code sees anything. An activity that fails verification never reaches your listeners.
• One bonus. Because you registered an actor dispatcher, you now have a WebFinger (RFC 7033) server, for free. Type @alice@example.com into Mastodon's search box and your actor comes up. You never wrote a line of WebFinger code.

Scene 2, revisited: types instead of JSON-LD

Fedify ships about eighty classes covering the whole Activity Vocabulary plus the major vendor extensions. The classes are typed and immutable, and their accessors absorb the shape differences that JSON-LD allows.

const actor = await ctx.lookupObject("@hongminhee@hollo.social");
if (actor instanceof Person) {
  console.log(actor.name);           // Safe whether it's a string or langString
  const followers = await actor.getFollowers();  // Fetches a URI, unwraps an object
}

lookupObject() takes a handle and runs the whole chain for you, WebFinger discovery included. Accessors like getFollowers() behave the same way whether the value is a URI reference or an inline object, and fetched values are cached.

Vendor fragmentation gets stitched up here too. The three competing quote properties (quoteUri, _misskey_quote, quoteUrl) are unified behind one API, next to the emerging FEP-044f quote. Misskey's isCat property exists as a type, so your server can determine cat-ness with full type safety. It sounds like a joke, but a few dozen details of exactly this kind are what interoperability is actually made of.

Scene 3, revisited: the zombie post dies in one line

Delivery infrastructure first. Plug a message queue into createFederation() and delivery moves to the background, with automatic retries under exponential backoff (up to ten attempts by default). When a post goes to thousands of followers, two-stage fan-out kicks in: a single consolidated message enters the queue, and a background worker splits it into per-server delivery tasks. The publish button responds immediately.

Retries create a problem of their own: the same activity can arrive twice. Fedify keeps a 24-hour idempotence cache of processed activities, so duplicates get detected and skipped before they reach your handlers.

As for the zombie post, the fix is one option:

await ctx.sendActivity(
  { identifier: "alice" },
  "followers",           // Collects recipients from your followers collection
  deleteActivity,
  { orderingKey: post.id },  // Same key = in-order delivery per server
);

Activities that share an orderingKey are delivered to each receiving server in the order they were sent. A Delete can no longer overtake its Create. Activities with different keys still go out in parallel, so throughput survives.

Fedify also handles dead servers. On a 404 Not Found or 410 Gone, it stops retrying and calls a handler you register. If the delivery went to a shared inbox, you also get the list of followers behind it, so you can prune vanished accounts on the spot. Hosts that fail repeatedly trip a per-host circuit breaker that holds deliveries and probes periodically until the host recovers. It's on by default; there's nothing to configure.

Scene 4, revisited: we track the quirks so you don't

Here is how Fedify disarms the traps from scene 4:

• Authorized fetch: chain .authorize() onto a dispatcher and the verified identity of the requester lands in your callback. Blocklists, private collections, whatever your app needs is plain application logic. The instance-actor deadlock has a supported pattern as well.
• Threads and inline actors: an activity transformer, enabled by default, rewrites inline actors into URIs on the way out. You don't need to know Threads has this problem.
• Lemmy's requirements: the custom collection API exposes a moderators collection in a few lines, and Lemmy's JSON-LD context ships preloaded.

When a new quirk surfaces in the wild, the fix lands in Fedify, not in every application separately. Each interoperability lesson gets learned once.

Scene 5, revisited: becoming unsafe takes effort

Fedify's defaults point the other way.

• Signature verification is something you turn off (for tests), not something you remember to turn on.
• The document loader refuses private address ranges and loopback out of the box, with DNS rebinding accounted for. To open yourself up to SSRF you have to flip an option whose very name announces it's for testing.
• When an embedded object's origin differs from its parent document's, the accessor refuses to trust it and re-fetches from the source (based on FEP-fe34). Content spoofing is stopped at the property access level.

In a from-scratch implementation, you have to keep remembering to do things safely. In Fedify, the unsafe path is the one that takes deliberate effort. For a federated server, with its tangle of trust boundaries, that's the right way around.

Your stack stays your stack

“Fine, but what if it doesn't fit our stack?” Fedify was built to fit the stack you already have. There are thirteen web framework integrations: servers like Express, Hono, Fastify, Koa, NestJS, and Elysia, and meta-frameworks like Next.js, Nuxt, SvelteKit, Astro, SolidStart, and Fresh. Middleware handles content negotiation, so the same URL in your existing app serves HTML to browsers and JSON-LD to the fediverse.

Fedify doesn't dictate your database either. For its own storage it asks for one key–value interface, with seven adapters available (Redis, PostgreSQL, MySQL/MariaDB, SQLite, Deno KV, Cloudflare Workers KV, in-memory). Message queues come in eight flavors (PostgreSQL, Redis, AMQP/RabbitMQ, and so on), and you can implement the interface yourself if none fits. Your domain data stays in whatever database and ORM you already use.

Already running federation on another library? There are migration guides with data migration scripts for moving from activitypub-express and friends without losing your existing followers.

The core isn't the ceiling, either. Higher-level packages build on it: @fedify/relay gives you a complete ActivityPub relay server in a single function call, and @fedify/backfill reconstructs incomplete conversation threads by walking the rest of the fediverse for you.

Tools for the whole development loop

A quieter misery of federated development has always been the missing tooling. Fedify comes with tools for every stage of the loop.

fedify init scaffolds a project in one line, and fedify tunnel exposes your local server over HTTPS so you can test against real Mastodon. Activities your server sends can be received by fedify inbox, a disposable inbox server spun up on the spot; whatever other servers publish, you can inspect with fedify lookup. My personal favorite is fedify lookup --authorized-fetch, which generates a one-off key pair and stands up a temporary ActivityPub server just to make a signed request for an object behind secure mode. The CLI is also useful to ActivityPub developers who don't use Fedify at all.

While you write code, an ActivityPub-specific linter (@fedify/lint) catches twenty kinds of interoperability bugs, like an actor missing its inbox. Tests run without the network using mocks from @fedify/testing. Once the server is up, attach the debug dashboard (@fedify/debugger) with one line and watch activities and signature verification results in your browser, live. In production there's built-in OpenTelemetry instrumentation (28 span types, 37 metrics) plus a monitoring guide, and when performance matters, fedify bench, a load-testing tool built for ActivityPub, catches regressions in CI.

As far as I know, no other ActivityPub framework ships even one of the tools in this section.

The documentation is part of the tooling. The official docs run to a thirty-chapter manual and five tutorials, and they go well past API listings. There's an operations chapter with ready-made PromQL queries and alerting rules for watching your queue backlog, and a field-guide chapter that documents de facto conventions, like which property makes your avatar show up in Mastodon, with screenshots. At two in the morning, when federation is broken and you don't know why, this is the difference between a bad night and a short one.

It's already running

Fedify is not a thought experiment. Ghost's ActivityPub service, mentioned above, is built on it. So are Encyclia, which bridges ORCID researcher records into the fediverse; SiliconBeest, running serverless on Cloudflare Workers; Typo Blue, a Korean blogging platform; Hollo, my own single-user microblogging platform; and Hackers' Pub, run by its community. Hollo, by the way, is the app from the beginning of this post: the project I once had to shelve, finished at last on the framework it forced into existence.

The tutorials give a concrete sense of scale. They walk you from a single-file server, a few dozen lines, that Mastodon can follow, through an image sharing service in roughly 750 lines that fully interoperates with Pixelfed (follows, likes, comments), up to a community platform federating both ways with the real lemmy.ml.

The fediverse needs more apps

I didn't build Fedify to mint more ActivityPub experts. Rather the opposite. I believe the fediverse will only grow beyond microblogging when developers can build federated apps without knowing ActivityPub's fine print. Signature spec transitions and JSON-LD compaction are problems that belong inside a framework, not barriers in front of someone with a new idea.

Starting takes one line:

npm init @fedify

Follow the first tutorial and by the end, Mastodon can find your server. If you get stuck, come find us in the Matrix room or GitHub Discussions. See you in the fediverse.

A quiet failure

Picture the moment your server sends its first Follow activity to Mastodon. You read the spec, built the JSON, signed the HTTP request, and POSTed it with care. What comes back is a single line: 401 Unauthorized. No body. No explanation.

What went wrong? Maybe the clock behind your Date header drifted a few minutes. Maybe the hash in your Digest header is off. Maybe you uppercased the (request-target) pseudo-header while building the signing string, or published your public key as PEM where the other side wanted multibase. The remote server won't tell you. So you start reading someone else's server code to debug your own.

I know, because I've been there. Fedify began as a casualty of another project. I set out to build a single-user microblogging server, the one that would later become Hollo, and started implementing ActivityPub from scratch. Somewhere between the signature specs and the JSON-LD, the protocol work swallowed the product, and I put the whole thing down. What I picked back up wasn't the app. It was the framework the app should have had. Fedify shipped first; only then could Hollo exist, built on top of it. (I've told this story at more length in A year with the fediverse.)

ActivityPub development gets hard in a few very specific places. In this post I want to walk through five of them, then show what each one looks like with Fedify. If you've spent time in the fediverse, you'll probably nod along. If you haven't, you may wonder why anyone would do all of this by hand. Either way, the conclusion is the same: nobody has to anymore.

Five scenes

Scene 1: there is more than one standard

ActivityPub servers authenticate each other with HTTP signatures. Except there isn't one signature spec. Most of the fediverse runs on draft-cavage-http-signatures-12, an expired draft that never became a standard. The actual standard exists too: RFC 9421, HTTP Message Signatures. The problem is that you can't know which one a given server accepts until you try.

A real-world implementation therefore has to sign with one spec, see whether it gets rejected, re-sign with the other, and remember per server which one worked so it can skip the dance next time. The fediverse calls this double-knocking. Yes, you get to implement it yourself.

That's still not the end. HTTP signatures only prove who sent a request. For situations like inbox forwarding, where you relay an activity you received to a third party, you need signatures that live on the document itself: Linked Data Signatures and Object Integrity Proofs. Four signature mechanisms in total, and two kinds of keys to manage: RSA and Ed25519.

Scene 2: one document, many shapes

ActivityPub's wire format is JSON-LD, and in JSON-LD the same document can take many shapes. This is easier to show than to explain. Here is a Create activity one server might send:

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "type": "Create",
  "actor": "https://example.com/users/alice",
  "to": "https://www.w3.org/ns/activitystreams#Public",
  "object": {
    "type": "Note",
    "id": "https://example.com/notes/123",
    "content": "Hello, fediverse!"
  }
}

And here is a semantically identical activity from another server:

{
  "@context": ["https://www.w3.org/ns/activitystreams"],
  "type": "Create",
  "actor": {
    "type": "Person",
    "id": "https://example.com/users/alice",
    "preferredUsername": "alice"
  },
  "to": ["as:Public"],
  "object": "https://example.com/notes/123"
}

actor turned from a URI string into an inline object. to turned from a string into an array. object went the other way, from an inline object to a URI. Even the address that means “public” has three valid spellings: https://www.w3.org/ns/activitystreams#Public, as:Public, and plain Public. Your parser has to accept every combination, and which one arrives depends on the sender's implementation.

The spec-compliant answer is to normalize every document with a JSON-LD processor, expansion followed by compaction. In practice many implementations treat it all as “just JSON” and quietly break on whatever shape some server happens to emit. Either way, you end up with defensive code smeared across the whole codebase: is this a string? An array? An object? A URI I have to fetch?

Scene 3: the zombie post

A user publishes a post, spots a typo, and deletes it right away. Your server sends a Create, then a Delete. Thanks to network weather, some receiving server gets the Delete first and the Create second. It ignores the deletion of a post that doesn't exist yet, then dutifully processes the creation of a post that was already deleted. That post now lives on that server forever, while its author believes it's gone.

Then there's scale. With five thousand followers, one post means thousands of HTTP deliveries. Do that inline in the request handler and your publish button takes half a minute to respond, or the server falls over. Fine, use a queue. Deliveries fail, so retry them. On what schedule? Exponential backoff. How many times? And is a 500 Internal Server Error the same kind of failure as a 410 Gone? When do you clean up three thousand followers on a server that no longer exists? Should you keep hammering a host that has been down for days?

At some point it dawns on you that this is no longer protocol implementation. It's distributed systems engineering.

Scene 4: it's not a spec, it's an ecosystem

Even perfect spec compliance doesn't buy you interoperability. A few examples from the field:

• Mastodon's secure mode requires HTTP signatures on GET requests too (so-called authorized fetch). Now suppose both servers run in that mode. To fetch the other side's public key you must sign your request; to verify your signature, the other side must first fetch your key. Deadlock. The community's workaround is to sign with an “instance actor” that represents the server itself. You won't find that in the spec.
• Threads can't parse activities whose actor is embedded as an inline object. When sending to Threads, the actor has to be a URI.
• Lemmy silently rejects Group actors that lack fields Mastodon never asks for, such as a moderators collection linked via attributedTo and a featured collection.
• Misskey carries vocabulary extensions of its own; quote posts alone go by three different property names across implementations.

The list keeps growing. Interoperability here is not something you finish once and stop thinking about. It's maintenance, forever.

Scene 5: insecure by default

Build it from scratch, and you start out wide open. Skip signature verification on incoming activities and anyone can inject a forged Follow or Delete. Leave the document loader unrestricted and a malicious activity can point it at http://169.254.169.254/ or your internal network, turning your server into an SSRF proxy. Skip origin checks on embedded objects and any server can hand out a document claiming “here's what the Mastodon lead developer said.”

What these traps share is that nothing happens when you fall into them. Everything appears to work. Until someone exploits it.

Ghost ran into this too

If you're thinking “surely our team would manage,” consider Ghost: a leading open-source publishing platform used by thousands of journalists and creators, and a team that set out to build its own ActivityPub support.

We can definitely attest to the problems that Fedify is working hard to solve, because even in just a few weeks of early prototyping we were running into the issues described above right away.

From Alright, let's Fedify

Ghost ended up building its ActivityPub layer on Fedify.

So I put all of it in a framework

Fedify is a TypeScript library for building federated server apps on ActivityPub and the standards around it. It runs on Deno, Node.js, and Bun, and supports edge runtimes like Cloudflare Workers. The design goal hasn't changed since the beginning: keep everything in those five scenes out of application code.

Here are the same five scenes again, this time with Fedify.

Scene 1, revisited: the signature war is the framework's job

Here is everything it takes to put one actor on the fediverse:

import { createFederation, generateCryptoKeyPair, MemoryKvStore } from "@fedify/fedify";
import { Endpoints, Person } from "@fedify/vocab";

const federation = createFederation<void>({
  kv: new MemoryKvStore(),  // Swap for Redis, PostgreSQL, etc. in production
});

federation
  .setActorDispatcher("/users/{identifier}", async (ctx, identifier) => {
    if (identifier !== "alice") return null;
    const keyPairs = await ctx.getActorKeyPairs(identifier);
    return new Person({
      id: ctx.getActorUri(identifier),
      preferredUsername: identifier,
      name: "Alice",
      inbox: ctx.getInboxUri(identifier),
      endpoints: new Endpoints({ sharedInbox: ctx.getInboxUri() }),
      publicKey: keyPairs[0].cryptographicKey,
      assertionMethods: keyPairs.map((keyPair) => keyPair.multikey),
    });
  })
  .setKeyPairsDispatcher(async (ctx, identifier) => {
    // In real code you'd persist these in a database; this shows the gist
    return [await generateCryptoKeyPair()];
  });

The moment this code runs:

• Every outgoing request gets signed. With an RSA key, Fedify emits HTTP Signatures and Linked Data Signatures; add an Ed25519 key and it attaches Object Integrity Proofs as well. All four mechanisms coexist on a single activity, and each receiver verifies with the strongest one it understands.
• Fedify does the double-knocking for you: first contact goes out as RFC 9421, a rejection triggers a draft-cavage retry, and the winning spec is cached per server. If the rejection carries an Accept-Signature challenge (RFC 9421 §5), Fedify reads it and re-signs with exactly the components the server asked for.
• Incoming signatures are verified before your code sees anything. An activity that fails verification never reaches your listeners.
• One bonus. Because you registered an actor dispatcher, you now have a WebFinger (RFC 7033) server, for free. Type @alice@example.com into Mastodon's search box and your actor comes up. You never wrote a line of WebFinger code.

Scene 2, revisited: types instead of JSON-LD

Fedify ships about eighty classes covering the whole Activity Vocabulary plus the major vendor extensions. The classes are typed and immutable, and their accessors absorb the shape differences that JSON-LD allows.

const actor = await ctx.lookupObject("@hongminhee@hollo.social");
if (actor instanceof Person) {
  console.log(actor.name);           // Safe whether it's a string or langString
  const followers = await actor.getFollowers();  // Fetches a URI, unwraps an object
}

lookupObject() takes a handle and runs the whole chain for you, WebFinger discovery included. Accessors like getFollowers() behave the same way whether the value is a URI reference or an inline object, and fetched values are cached.

Vendor fragmentation gets stitched up here too. The three competing quote properties (quoteUri, _misskey_quote, quoteUrl) are unified behind one API, next to the emerging FEP-044f quote. Misskey's isCat property exists as a type, so your server can determine cat-ness with full type safety. It sounds like a joke, but a few dozen details of exactly this kind are what interoperability is actually made of.

Scene 3, revisited: the zombie post dies in one line

Delivery infrastructure first. Plug a message queue into createFederation() and delivery moves to the background, with automatic retries under exponential backoff (up to ten attempts by default). When a post goes to thousands of followers, two-stage fan-out kicks in: a single consolidated message enters the queue, and a background worker splits it into per-server delivery tasks. The publish button responds immediately.

Retries create a problem of their own: the same activity can arrive twice. Fedify keeps a 24-hour idempotence cache of processed activities, so duplicates get detected and skipped before they reach your handlers.

As for the zombie post, the fix is one option:

await ctx.sendActivity(
  { identifier: "alice" },
  "followers",           // Collects recipients from your followers collection
  deleteActivity,
  { orderingKey: post.id },  // Same key = in-order delivery per server
);

Activities that share an orderingKey are delivered to each receiving server in the order they were sent. A Delete can no longer overtake its Create. Activities with different keys still go out in parallel, so throughput survives.

Fedify also handles dead servers. On a 404 Not Found or 410 Gone, it stops retrying and calls a handler you register. If the delivery went to a shared inbox, you also get the list of followers behind it, so you can prune vanished accounts on the spot. Hosts that fail repeatedly trip a per-host circuit breaker that holds deliveries and probes periodically until the host recovers. It's on by default; there's nothing to configure.

Scene 4, revisited: we track the quirks so you don't

Here is how Fedify disarms the traps from scene 4:

• Authorized fetch: chain .authorize() onto a dispatcher and the verified identity of the requester lands in your callback. Blocklists, private collections, whatever your app needs is plain application logic. The instance-actor deadlock has a supported pattern as well.
• Threads and inline actors: an activity transformer, enabled by default, rewrites inline actors into URIs on the way out. You don't need to know Threads has this problem.
• Lemmy's requirements: the custom collection API exposes a moderators collection in a few lines, and Lemmy's JSON-LD context ships preloaded.

When a new quirk surfaces in the wild, the fix lands in Fedify, not in every application separately. Each interoperability lesson gets learned once.

Scene 5, revisited: becoming unsafe takes effort

Fedify's defaults point the other way.

• Signature verification is something you turn off (for tests), not something you remember to turn on.
• The document loader refuses private address ranges and loopback out of the box, with DNS rebinding accounted for. To open yourself up to SSRF you have to flip an option whose very name announces it's for testing.
• When an embedded object's origin differs from its parent document's, the accessor refuses to trust it and re-fetches from the source (based on FEP-fe34). Content spoofing is stopped at the property access level.

In a from-scratch implementation, you have to keep remembering to do things safely. In Fedify, the unsafe path is the one that takes deliberate effort. For a federated server, with its tangle of trust boundaries, that's the right way around.

Your stack stays your stack

“Fine, but what if it doesn't fit our stack?” Fedify was built to fit the stack you already have. There are thirteen web framework integrations: servers like Express, Hono, Fastify, Koa, NestJS, and Elysia, and meta-frameworks like Next.js, Nuxt, SvelteKit, Astro, SolidStart, and Fresh. Middleware handles content negotiation, so the same URL in your existing app serves HTML to browsers and JSON-LD to the fediverse.

Fedify doesn't dictate your database either. For its own storage it asks for one key–value interface, with seven adapters available (Redis, PostgreSQL, MySQL/MariaDB, SQLite, Deno KV, Cloudflare Workers KV, in-memory). Message queues come in eight flavors (PostgreSQL, Redis, AMQP/RabbitMQ, and so on), and you can implement the interface yourself if none fits. Your domain data stays in whatever database and ORM you already use.

Already running federation on another library? There are migration guides with data migration scripts for moving from activitypub-express and friends without losing your existing followers.

The core isn't the ceiling, either. Higher-level packages build on it: @fedify/relay gives you a complete ActivityPub relay server in a single function call, and @fedify/backfill reconstructs incomplete conversation threads by walking the rest of the fediverse for you.

Tools for the whole development loop

A quieter misery of federated development has always been the missing tooling. Fedify comes with tools for every stage of the loop.

fedify init scaffolds a project in one line, and fedify tunnel exposes your local server over HTTPS so you can test against real Mastodon. Activities your server sends can be received by fedify inbox, a disposable inbox server spun up on the spot; whatever other servers publish, you can inspect with fedify lookup. My personal favorite is fedify lookup --authorized-fetch, which generates a one-off key pair and stands up a temporary ActivityPub server just to make a signed request for an object behind secure mode. The CLI is also useful to ActivityPub developers who don't use Fedify at all.

While you write code, an ActivityPub-specific linter (@fedify/lint) catches twenty kinds of interoperability bugs, like an actor missing its inbox. Tests run without the network using mocks from @fedify/testing. Once the server is up, attach the debug dashboard (@fedify/debugger) with one line and watch activities and signature verification results in your browser, live. In production there's built-in OpenTelemetry instrumentation (28 span types, 37 metrics) plus a monitoring guide, and when performance matters, fedify bench, a load-testing tool built for ActivityPub, catches regressions in CI.

As far as I know, no other ActivityPub framework ships even one of the tools in this section.

The documentation is part of the tooling. The official docs run to a thirty-chapter manual and five tutorials, and they go well past API listings. There's an operations chapter with ready-made PromQL queries and alerting rules for watching your queue backlog, and a field-guide chapter that documents de facto conventions, like which property makes your avatar show up in Mastodon, with screenshots. At two in the morning, when federation is broken and you don't know why, this is the difference between a bad night and a short one.

It's already running

Fedify is not a thought experiment. Ghost's ActivityPub service, mentioned above, is built on it. So are Encyclia, which bridges ORCID researcher records into the fediverse; SiliconBeest, running serverless on Cloudflare Workers; Typo Blue, a Korean blogging platform; Hollo, my own single-user microblogging platform; and Hackers' Pub, run by its community. Hollo, by the way, is the app from the beginning of this post: the project I once had to shelve, finished at last on the framework it forced into existence.

The tutorials give a concrete sense of scale. They walk you from a single-file server, a few dozen lines, that Mastodon can follow, through an image sharing service in roughly 750 lines that fully interoperates with Pixelfed (follows, likes, comments), up to a community platform federating both ways with the real lemmy.ml.

The fediverse needs more apps

I didn't build Fedify to mint more ActivityPub experts. Rather the opposite. I believe the fediverse will only grow beyond microblogging when developers can build federated apps without knowing ActivityPub's fine print. Signature spec transitions and JSON-LD compaction are problems that belong inside a framework, not barriers in front of someone with a new idea.

Starting takes one line:

npm init @fedify

Follow the first tutorial and by the end, Mastodon can find your server. If you get stuck, come find us in the Matrix room or GitHub Discussions. See you in the fediverse.

A quiet failure

Picture the moment your server sends its first Follow activity to Mastodon. You read the spec, built the JSON, signed the HTTP request, and POSTed it with care. What comes back is a single line: 401 Unauthorized. No body. No explanation.

What went wrong? Maybe the clock behind your Date header drifted a few minutes. Maybe the hash in your Digest header is off. Maybe you uppercased the (request-target) pseudo-header while building the signing string, or published your public key as PEM where the other side wanted multibase. The remote server won't tell you. So you start reading someone else's server code to debug your own.

I know, because I've been there. Fedify began as a casualty of another project. I set out to build a single-user microblogging server, the one that would later become Hollo, and started implementing ActivityPub from scratch. Somewhere between the signature specs and the JSON-LD, the protocol work swallowed the product, and I put the whole thing down. What I picked back up wasn't the app. It was the framework the app should have had. Fedify shipped first; only then could Hollo exist, built on top of it. (I've told this story at more length in A year with the fediverse.)

ActivityPub development gets hard in a few very specific places. In this post I want to walk through five of them, then show what each one looks like with Fedify. If you've spent time in the fediverse, you'll probably nod along. If you haven't, you may wonder why anyone would do all of this by hand. Either way, the conclusion is the same: nobody has to anymore.

Five scenes

Scene 1: there is more than one standard

ActivityPub servers authenticate each other with HTTP signatures. Except there isn't one signature spec. Most of the fediverse runs on draft-cavage-http-signatures-12, an expired draft that never became a standard. The actual standard exists too: RFC 9421, HTTP Message Signatures. The problem is that you can't know which one a given server accepts until you try.

A real-world implementation therefore has to sign with one spec, see whether it gets rejected, re-sign with the other, and remember per server which one worked so it can skip the dance next time. The fediverse calls this double-knocking. Yes, you get to implement it yourself.

That's still not the end. HTTP signatures only prove who sent a request. For situations like inbox forwarding, where you relay an activity you received to a third party, you need signatures that live on the document itself: Linked Data Signatures and Object Integrity Proofs. Four signature mechanisms in total, and two kinds of keys to manage: RSA and Ed25519.

Scene 2: one document, many shapes

ActivityPub's wire format is JSON-LD, and in JSON-LD the same document can take many shapes. This is easier to show than to explain. Here is a Create activity one server might send:

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "type": "Create",
  "actor": "https://example.com/users/alice",
  "to": "https://www.w3.org/ns/activitystreams#Public",
  "object": {
    "type": "Note",
    "id": "https://example.com/notes/123",
    "content": "Hello, fediverse!"
  }
}

And here is a semantically identical activity from another server:

{
  "@context": ["https://www.w3.org/ns/activitystreams"],
  "type": "Create",
  "actor": {
    "type": "Person",
    "id": "https://example.com/users/alice",
    "preferredUsername": "alice"
  },
  "to": ["as:Public"],
  "object": "https://example.com/notes/123"
}

actor turned from a URI string into an inline object. to turned from a string into an array. object went the other way, from an inline object to a URI. Even the address that means “public” has three valid spellings: https://www.w3.org/ns/activitystreams#Public, as:Public, and plain Public. Your parser has to accept every combination, and which one arrives depends on the sender's implementation.

The spec-compliant answer is to normalize every document with a JSON-LD processor, expansion followed by compaction. In practice many implementations treat it all as “just JSON” and quietly break on whatever shape some server happens to emit. Either way, you end up with defensive code smeared across the whole codebase: is this a string? An array? An object? A URI I have to fetch?

Scene 3: the zombie post

A user publishes a post, spots a typo, and deletes it right away. Your server sends a Create, then a Delete. Thanks to network weather, some receiving server gets the Delete first and the Create second. It ignores the deletion of a post that doesn't exist yet, then dutifully processes the creation of a post that was already deleted. That post now lives on that server forever, while its author believes it's gone.

Then there's scale. With five thousand followers, one post means thousands of HTTP deliveries. Do that inline in the request handler and your publish button takes half a minute to respond, or the server falls over. Fine, use a queue. Deliveries fail, so retry them. On what schedule? Exponential backoff. How many times? And is a 500 Internal Server Error the same kind of failure as a 410 Gone? When do you clean up three thousand followers on a server that no longer exists? Should you keep hammering a host that has been down for days?

At some point it dawns on you that this is no longer protocol implementation. It's distributed systems engineering.

Scene 4: it's not a spec, it's an ecosystem

Even perfect spec compliance doesn't buy you interoperability. A few examples from the field:

• Mastodon's secure mode requires HTTP signatures on GET requests too (so-called authorized fetch). Now suppose both servers run in that mode. To fetch the other side's public key you must sign your request; to verify your signature, the other side must first fetch your key. Deadlock. The community's workaround is to sign with an “instance actor” that represents the server itself. You won't find that in the spec.
• Threads can't parse activities whose actor is embedded as an inline object. When sending to Threads, the actor has to be a URI.
• Lemmy silently rejects Group actors that lack fields Mastodon never asks for, such as a moderators collection linked via attributedTo and a featured collection.
• Misskey carries vocabulary extensions of its own; quote posts alone go by three different property names across implementations.

The list keeps growing. Interoperability here is not something you finish once and stop thinking about. It's maintenance, forever.

Scene 5: insecure by default

Build it from scratch, and you start out wide open. Skip signature verification on incoming activities and anyone can inject a forged Follow or Delete. Leave the document loader unrestricted and a malicious activity can point it at http://169.254.169.254/ or your internal network, turning your server into an SSRF proxy. Skip origin checks on embedded objects and any server can hand out a document claiming “here's what the Mastodon lead developer said.”

What these traps share is that nothing happens when you fall into them. Everything appears to work. Until someone exploits it.

Ghost ran into this too

If you're thinking “surely our team would manage,” consider Ghost: a leading open-source publishing platform used by thousands of journalists and creators, and a team that set out to build its own ActivityPub support.

We can definitely attest to the problems that Fedify is working hard to solve, because even in just a few weeks of early prototyping we were running into the issues described above right away.

From Alright, let's Fedify

Ghost ended up building its ActivityPub layer on Fedify.

So I put all of it in a framework

Fedify is a TypeScript library for building federated server apps on ActivityPub and the standards around it. It runs on Deno, Node.js, and Bun, and supports edge runtimes like Cloudflare Workers. The design goal hasn't changed since the beginning: keep everything in those five scenes out of application code.

Here are the same five scenes again, this time with Fedify.

Scene 1, revisited: the signature war is the framework's job

Here is everything it takes to put one actor on the fediverse:

import { createFederation, generateCryptoKeyPair, MemoryKvStore } from "@fedify/fedify";
import { Endpoints, Person } from "@fedify/vocab";

const federation = createFederation<void>({
  kv: new MemoryKvStore(),  // Swap for Redis, PostgreSQL, etc. in production
});

federation
  .setActorDispatcher("/users/{identifier}", async (ctx, identifier) => {
    if (identifier !== "alice") return null;
    const keyPairs = await ctx.getActorKeyPairs(identifier);
    return new Person({
      id: ctx.getActorUri(identifier),
      preferredUsername: identifier,
      name: "Alice",
      inbox: ctx.getInboxUri(identifier),
      endpoints: new Endpoints({ sharedInbox: ctx.getInboxUri() }),
      publicKey: keyPairs[0].cryptographicKey,
      assertionMethods: keyPairs.map((keyPair) => keyPair.multikey),
    });
  })
  .setKeyPairsDispatcher(async (ctx, identifier) => {
    // In real code you'd persist these in a database; this shows the gist
    return [await generateCryptoKeyPair()];
  });

The moment this code runs:

• Every outgoing request gets signed. With an RSA key, Fedify emits HTTP Signatures and Linked Data Signatures; add an Ed25519 key and it attaches Object Integrity Proofs as well. All four mechanisms coexist on a single activity, and each receiver verifies with the strongest one it understands.
• Fedify does the double-knocking for you: first contact goes out as RFC 9421, a rejection triggers a draft-cavage retry, and the winning spec is cached per server. If the rejection carries an Accept-Signature challenge (RFC 9421 §5), Fedify reads it and re-signs with exactly the components the server asked for.
• Incoming signatures are verified before your code sees anything. An activity that fails verification never reaches your listeners.
• One bonus. Because you registered an actor dispatcher, you now have a WebFinger (RFC 7033) server, for free. Type @alice@example.com into Mastodon's search box and your actor comes up. You never wrote a line of WebFinger code.

Scene 2, revisited: types instead of JSON-LD

Fedify ships about eighty classes covering the whole Activity Vocabulary plus the major vendor extensions. The classes are typed and immutable, and their accessors absorb the shape differences that JSON-LD allows.

const actor = await ctx.lookupObject("@hongminhee@hollo.social");
if (actor instanceof Person) {
  console.log(actor.name);           // Safe whether it's a string or langString
  const followers = await actor.getFollowers();  // Fetches a URI, unwraps an object
}

lookupObject() takes a handle and runs the whole chain for you, WebFinger discovery included. Accessors like getFollowers() behave the same way whether the value is a URI reference or an inline object, and fetched values are cached.

Vendor fragmentation gets stitched up here too. The three competing quote properties (quoteUri, _misskey_quote, quoteUrl) are unified behind one API, next to the emerging FEP-044f quote. Misskey's isCat property exists as a type, so your server can determine cat-ness with full type safety. It sounds like a joke, but a few dozen details of exactly this kind are what interoperability is actually made of.

Scene 3, revisited: the zombie post dies in one line

Delivery infrastructure first. Plug a message queue into createFederation() and delivery moves to the background, with automatic retries under exponential backoff (up to ten attempts by default). When a post goes to thousands of followers, two-stage fan-out kicks in: a single consolidated message enters the queue, and a background worker splits it into per-server delivery tasks. The publish button responds immediately.

Retries create a problem of their own: the same activity can arrive twice. Fedify keeps a 24-hour idempotence cache of processed activities, so duplicates get detected and skipped before they reach your handlers.

As for the zombie post, the fix is one option:

await ctx.sendActivity(
  { identifier: "alice" },
  "followers",           // Collects recipients from your followers collection
  deleteActivity,
  { orderingKey: post.id },  // Same key = in-order delivery per server
);

Activities that share an orderingKey are delivered to each receiving server in the order they were sent. A Delete can no longer overtake its Create. Activities with different keys still go out in parallel, so throughput survives.

Fedify also handles dead servers. On a 404 Not Found or 410 Gone, it stops retrying and calls a handler you register. If the delivery went to a shared inbox, you also get the list of followers behind it, so you can prune vanished accounts on the spot. Hosts that fail repeatedly trip a per-host circuit breaker that holds deliveries and probes periodically until the host recovers. It's on by default; there's nothing to configure.

Scene 4, revisited: we track the quirks so you don't

Here is how Fedify disarms the traps from scene 4:

• Authorized fetch: chain .authorize() onto a dispatcher and the verified identity of the requester lands in your callback. Blocklists, private collections, whatever your app needs is plain application logic. The instance-actor deadlock has a supported pattern as well.
• Threads and inline actors: an activity transformer, enabled by default, rewrites inline actors into URIs on the way out. You don't need to know Threads has this problem.
• Lemmy's requirements: the custom collection API exposes a moderators collection in a few lines, and Lemmy's JSON-LD context ships preloaded.

When a new quirk surfaces in the wild, the fix lands in Fedify, not in every application separately. Each interoperability lesson gets learned once.

Scene 5, revisited: becoming unsafe takes effort

Fedify's defaults point the other way.

• Signature verification is something you turn off (for tests), not something you remember to turn on.
• The document loader refuses private address ranges and loopback out of the box, with DNS rebinding accounted for. To open yourself up to SSRF you have to flip an option whose very name announces it's for testing.
• When an embedded object's origin differs from its parent document's, the accessor refuses to trust it and re-fetches from the source (based on FEP-fe34). Content spoofing is stopped at the property access level.

In a from-scratch implementation, you have to keep remembering to do things safely. In Fedify, the unsafe path is the one that takes deliberate effort. For a federated server, with its tangle of trust boundaries, that's the right way around.

Your stack stays your stack

“Fine, but what if it doesn't fit our stack?” Fedify was built to fit the stack you already have. There are thirteen web framework integrations: servers like Express, Hono, Fastify, Koa, NestJS, and Elysia, and meta-frameworks like Next.js, Nuxt, SvelteKit, Astro, SolidStart, and Fresh. Middleware handles content negotiation, so the same URL in your existing app serves HTML to browsers and JSON-LD to the fediverse.

Fedify doesn't dictate your database either. For its own storage it asks for one key–value interface, with seven adapters available (Redis, PostgreSQL, MySQL/MariaDB, SQLite, Deno KV, Cloudflare Workers KV, in-memory). Message queues come in eight flavors (PostgreSQL, Redis, AMQP/RabbitMQ, and so on), and you can implement the interface yourself if none fits. Your domain data stays in whatever database and ORM you already use.

Already running federation on another library? There are migration guides with data migration scripts for moving from activitypub-express and friends without losing your existing followers.

The core isn't the ceiling, either. Higher-level packages build on it: @fedify/relay gives you a complete ActivityPub relay server in a single function call, and @fedify/backfill reconstructs incomplete conversation threads by walking the rest of the fediverse for you.

Tools for the whole development loop

A quieter misery of federated development has always been the missing tooling. Fedify comes with tools for every stage of the loop.

fedify init scaffolds a project in one line, and fedify tunnel exposes your local server over HTTPS so you can test against real Mastodon. Activities your server sends can be received by fedify inbox, a disposable inbox server spun up on the spot; whatever other servers publish, you can inspect with fedify lookup. My personal favorite is fedify lookup --authorized-fetch, which generates a one-off key pair and stands up a temporary ActivityPub server just to make a signed request for an object behind secure mode. The CLI is also useful to ActivityPub developers who don't use Fedify at all.

While you write code, an ActivityPub-specific linter (@fedify/lint) catches twenty kinds of interoperability bugs, like an actor missing its inbox. Tests run without the network using mocks from @fedify/testing. Once the server is up, attach the debug dashboard (@fedify/debugger) with one line and watch activities and signature verification results in your browser, live. In production there's built-in OpenTelemetry instrumentation (28 span types, 37 metrics) plus a monitoring guide, and when performance matters, fedify bench, a load-testing tool built for ActivityPub, catches regressions in CI.

As far as I know, no other ActivityPub framework ships even one of the tools in this section.

The documentation is part of the tooling. The official docs run to a thirty-chapter manual and five tutorials, and they go well past API listings. There's an operations chapter with ready-made PromQL queries and alerting rules for watching your queue backlog, and a field-guide chapter that documents de facto conventions, like which property makes your avatar show up in Mastodon, with screenshots. At two in the morning, when federation is broken and you don't know why, this is the difference between a bad night and a short one.

It's already running

Fedify is not a thought experiment. Ghost's ActivityPub service, mentioned above, is built on it. So are Encyclia, which bridges ORCID researcher records into the fediverse; SiliconBeest, running serverless on Cloudflare Workers; Typo Blue, a Korean blogging platform; Hollo, my own single-user microblogging platform; and Hackers' Pub, run by its community. Hollo, by the way, is the app from the beginning of this post: the project I once had to shelve, finished at last on the framework it forced into existence.

The tutorials give a concrete sense of scale. They walk you from a single-file server, a few dozen lines, that Mastodon can follow, through an image sharing service in roughly 750 lines that fully interoperates with Pixelfed (follows, likes, comments), up to a community platform federating both ways with the real lemmy.ml.

The fediverse needs more apps

I didn't build Fedify to mint more ActivityPub experts. Rather the opposite. I believe the fediverse will only grow beyond microblogging when developers can build federated apps without knowing ActivityPub's fine print. Signature spec transitions and JSON-LD compaction are problems that belong inside a framework, not barriers in front of someone with a new idea.

Starting takes one line:

npm init @fedify

Follow the first tutorial and by the end, Mastodon can find your server. If you get stuck, come find us in the Matrix room or GitHub Discussions. See you in the fediverse.