Fedify 2.4.0: FEP-ef61 portable objects, background tasks, media uploads, and inbox request reports
한국어 (Korean): Fedify 2.4.0: FEP-ef61 이식 가능한 객체, 백그라운드 작업, 미디어 업로드 및 인박스 요청 리포트 · 자동 번역
日本語 (Japanese): Fedify 2.4.0: FEP-ef61ポータブルオブジェクト、バックグラウンドタスク、メディアアップロード、およびインボックスリクエストレポート · 自動翻訳
Fedify is a TypeScript framework for building ActivityPub servers. It implements federation details such as HTTP Signatures, JSON-LD processing, WebFinger, inbox and outbox routing, and activity delivery.
Fedify 2.4.0 is a minor release with an unusually long changelog. The main addition is support for FEP-ef61 portable objects: a Fedify server can now host actors whose identity is a DID rather than a domain, serve and verify their signed objects, and consume the portable objects of other servers. The release also adds an API for application-defined background tasks, the ActivityPub Media Upload extension, a hook that reports how every inbox request was authenticated and handled, and 410 Gone tombstones for deleted objects. Several defaults change to limit what a hostile peer can make Fedify do. Four new packages ship with this version:
@fedify/adonisjs,
@fedify/interaction-controls,
@fedify/netlify, and
@fedify/pglite.
Most applications can upgrade without code changes, but a few of the new defaults are behavior changes. They are listed in the Upgrading section at the end.
FEP-ef61 portable objects
An ActivityPub object's ID is an HTTP(S) URL on its server's domain. If that server shuts down, its IDs stop resolving, and an actor that moves elsewhere gets a new ID that everyone has to follow again. FEP-ef61, written by
@silverpill@mitra.social of Mitra, proposes IDs that do not name a server at all. A portable ID is an ap: URI whose authority is a DID:
ap://did:key:z6MkrJVnaZkeFzdQyMZu1cgjg7k1pZZ6pvBQ7XJPt4swbTQ2/actor
The same object can be stored on several servers, called gateways, each of which serves it under /.well-known/apgateway/. Because no server owns the ID, a portable actor, activity, or object is authenticated only by its FEP-8b32 Object Integrity Proof, made with a key of the DID in its ID. A portable actor lists its gateways in a gateways property, and other servers deliver to its inbox through them.
Fedify 2.4.0 implements a profile of FEP-ef61 for gateways and consumers of portable objects. It makes two deliberate choices where the FEP or the specifications it rests on leave questions open, and it leaves out a few parts of the proposal; both are described below. The new Portable objects chapter of the manual walks through running portable actors from start to finish and then describes the profile as a whole, so that other implementers can tell what to expect from a Fedify server. The request came from
@anotherdoesnm in
#288, which tracked the work from a roadmap to the final pieces.
Portable objects are a foundation for nomadic identity, not nomadic identity itself. Fedify serves and verifies portable objects and forwards activities between gateways, but it does not copy actors or posts between servers, rotate keys, or move an actor to another DID. Full nomadic identity is still open in
#413.
Hosting a portable actor
A portable actor starts with an Ed25519 key pair. Its DID is made from the public key with exportDidKey(), and whoever holds the private key can act as the actor, so store it with the actor and keep it safe:
import { generateCryptoKeyPair } from "
@fedify/fedify";
import { exportDidKey } from "
@fedify/vocab-runtime";
const { publicKey, privateKey } = await generateCryptoKeyPair("Ed25519");
const did = await exportDidKey(publicKey); // did:key:z6Mk...
// The verification method that the actor's proofs refer to:
const didKeyId = new URL(`${did}#${did.slice("did:key:".length)}`);
The actor dispatcher returns a portable actor as it would an ordinary one. Context.getPortableActorUri() and its siblings for inboxes, outboxes, collections, and objects build portable IDs from the dispatcher's paths and the DID, and signObject() signs the actor with the DID's key:
federation
.setActorDispatcher("/users/{identifier}", async (ctx, identifier) => {
const user = await findUser(identifier);
if (user == null) return null;
// A request through the gateway endpoint names the DID in its path,
// e.g., GET /.well-known/apgateway/did:key:z6Mk.../users/alice:
if (
ctx.portableRequest != null &&
ctx.portableRequest.authority !== user.did
) {
return null;
}
// This server's gateway keys for the actor (see below):
const keys = await ctx.getActorKeyPairs(identifier);
return await signObject(
new Person({
id: ctx.getPortableActorUri(identifier, user.did), // ap+ef61://did:key:z6Mk.../users/alice
preferredUsername: user.username,
inbox: ctx.getPortableInboxUri(identifier, user.did),
outbox: ctx.getPortableOutboxUri(identifier, user.did),
followers: ctx.getPortableFollowersUri(identifier, user.did),
gateways: [new URL("
https://example.com")],
publicKeys: keys.map((key) => key.cryptographicKey),
assertionMethods: keys.map((key) => key.multikey),
}),
user.didKeyPair.privateKey,
new URL(`${user.did}#${user.did.slice("did:key:".length)}`),
);
})
.setKeyPairsDispatcher(async (ctx, identifier) => {
const user = await findUser(identifier);
// This server's own key pair for the actor, not the DID's:
return user == null ? [] : [user.gatewayKeyPair];
})
.mapPortableActorId(async (ctx, identifier) => {
const user = await findUser(identifier);
return user == null ? null : ctx.getPortableActorUri(identifier, user.did);
});
With this dispatcher, Fedify serves the actor at its compatible identifier,
https://example.com/.well-known/apgateway/did:key:z6Mk.../users/alice which is how other servers retrieve it. It serves it through WebFinger as
@alice@example.com, since the handle's domain comes from the first gateway in gateways, and at its ordinary URL as before. On the gateway endpoint, Fedify serves a document only if its ID is the requested portable ID and it carries a proof made with a key of that DID.
The key pairs dispatcher and the new ActorCallbackSetters.mapPortableActorId() give the actor gateway keys. These are the server's own keys for the actor, and they sign only the HTTP requests the server makes on the actor's behalf, such as deliveries. They never sign the actor's activities or objects; only the DID's key does that. The actor document lists them under assertionMethods, as FEP-521a describes, so that other servers can verify the HTTP Signatures. See Dispatching the actor and Gateway keys of portable actors for the details.
Object and collection dispatchers serve portable objects and collections through the gateway endpoint in the same way, routed by the path after the DID. Two rules protect the actor's data. A non-public portable object is served only if the dispatcher has an authorization predicate, because FEP-ef61 forbids a gateway to show it to anyone outside its audience; the new RequestContext.isSignedByAudience() helps to write one. Without a predicate, a request for such an object gets 404 Not Found, as though the gateway did not store it. A deleted object is served as a signed Tombstone with 410 Gone. Resources that portable objects refer to by SHA-256 hashlinks, such as GET /.well-known/apgateway/hl:zQm..., are served by the new Federatable.setHashlinkMediaDispatcher().
Sending and receiving
A portable actor's activities have to be signed by its DID, which Fedify's key pairs dispatcher does not know about. Sign them with signObject() before sending, and pass normalizeExistingProofs: true so that the activity goes out in the form its proof covers. An activity that embeds a portable object, such as the Note of a Create, is signed inside out:
const actor = withGatewayHints(
ctx.getPortableActorUri(user.identifier, user.did),
[new URL("
https://example.com")],
); // ap+ef61://did:key:z6Mk.../users/alice?
@gateway=https%3A%2F%2Fexample.com
const note = await signObject(
new Note({
id: ctx.getPortableObjectUri(
Note,
{ identifier: user.identifier, id: crypto.randomUUID() },
user.did,
),
attribution: actor,
to: PUBLIC_COLLECTION,
content: "Hello, world!",
}),
user.didKeyPair.privateKey,
didKeyId,
);
const create = await signObject(
new Create({
id: ctx.getPortableObjectUri(
Note,
{ identifier: user.identifier, id: crypto.randomUUID() },
user.did,
),
actor,
to: PUBLIC_COLLECTION,
object: note,
}),
user.didKeyPair.privateKey,
didKeyId,
);
await ctx.sendActivity(
{ identifier: user.identifier },
"followers",
create,
{ normalizeExistingProofs: true },
);
This example depends on a fix to signObject() that is useful outside FEP-ef61 as well. Previously, a signed object assigned to a typed parent was rebuilt under the parent's JSON-LD context when the parent was serialized. The child kept its proofValue but lost the document its proof covered, so it no longer verified on its own. signObject() now captures the exact document it signed, and nested serialization embeds that document verbatim. The captured document is a snapshot: clone() does not carry it, so sign a clone again if it has to be embedded. The design is in
#1044 and the fix in
#1051.
Context.sendActivity() refuses a portable activity that is unsigned, signed by the wrong key, or carries a Linked Data Signature, and throws a TypeError before anything is queued. It also refuses a few shapes of compound document that Fedify's own inboxes would reject, such as a received signed Follow embedded in an Accept; refer to such an object by its ID instead. Deliveries to portable inboxes go through the recipient's gateways, or else the
@gateway hints on the inbox, trying at most five of them until one accepts. Before this release, they failed with UrlError: Unsupported protocol: ap+ef61:. The rules are in Delivering to portable actors and Producing a compound document.
On the receiving side, a portable inbox is reached as POST /.well-known/apgateway/did:key:z6Mk.../users/alice/inbox and dispatched to the same inbox listeners as the ordinary inbox. Context.parseUri() gains a portable option, and the parsed result has the DID in a new authority property to check against the one you store. Fedify accepts an activity of a portable actor, or one with a portable ID, only if it has a valid proof by that DID; neither an HTTP Signature nor a Linked Data Signature authenticates it. Each portable object embedded in the activity is verified against its own proof before dispatch. An accepted activity that carries its own proof is forwarded to the actor's other gateways at most once, as FEP-ef61 recommends. Forwarding needs a key–value store that supports cas(), and the FederationOptions.portableInboxForwarding option tunes it. See Portable inboxes and Forwarding to other gateways.
Consuming portable objects
Applications that never host a portable actor still meet portable objects from other servers. Context.lookupObject() resolves portable IDs, compatible identifiers, and the fediverse handles of portable actors, and returns portable objects only if they verify:
const actor = await ctx.lookupObject("
@alice@example.com");
// A portable ID without
@gateway hints needs gateways to ask:
const note = await ctx.lookupObject("ap://did:key:z6Mk.../notes/1", {
gateways: ["
https://example.com"],
});
Property accessors fetch portable references through gateways as well, and they verify what they fetch with the new verifyPortableObject option. Context has a matching verifyPortableObject property, so passing a context as the options, as in await create.getObject(ctx), is enough. Activities received in inboxes use this verifier by default, and objects fetched through their accessors inherit it, so a chained call such as (await create.getObject(ctx))?.getAttribution() verifies each portable object along the way. A lookup asks at most five gateways, falling back to the next when one fails or serves something that does not verify. Unsigned collections are accepted only from a gateway that the owner lists, and only for an actor's inbox, outbox, followers, following, and liked, as FEP-ef61 allows. fetchPortableMedia() retrieves the media of a portable object and returns it only if it matches the object's digestMultibase. See Dereferencing portable references and Default verifiers.
Compatible identifiers are no longer trusted by origin
Software that does not understand ap: URIs can refer to a portable object by a compatible identifier, an HTTP(S) URL under a gateway's /.well-known/apgateway/ path such as
https://gw.example/.well-known/apgateway/did:key:z6Mk.../actor Some implementations, tootik among them, use compatible identifiers as the IDs of their portable actors.
Earlier versions of Fedify treated these URLs as ordinary web URLs and trusted them by the server that served them. Since anyone can serve a compatible identifier for any DID,
https://evil.example/.well-known/apgateway/did:key:z6MkAlice/actor could act as Alice without a proof by Alice's DID. Fedify 2.4.0 treats a compatible identifier as the portable object it stands for, as FEP-ef61 requires. Inboxes reject an activity from an actor whose ID is a compatible identifier with 401 Unauthorized unless it has a valid Object Integrity Proof by the actor's DID, and there is no option to turn this off. Actors that publish compatible identifiers without signing them are no longer accepted, and neither are those whose DIDs use key types that Fedify cannot verify yet. The change was tracked in
#1093 and made in
#1105.
Your own portable actors may still use compatible identifiers as their IDs, for software that rejects ap: IDs. Build them with toCompatibleEf61Id() before signing, and Fedify will treat them as portable wherever it serves or sends them. It also warns if one is malformed or does not point at the actor's first gateway. See Compatible identifiers as actor IDs.
Where Fedify's profile differs from the FEP
Two choices in Fedify's profile differ from the current FEP text or rest on semantics that are not settled yet. Fedify keeps both for the 2.x series, and either may change in Fedify 3.0.
The first is the scheme. FEP-ef61 recommends ap: and canonicalizes ap+ef61: to it, while also warning that the recommendation may change to ap+ef61:, since these IDs are meant only for portable objects. Fedify accepts both, compares them as equal, and serializes ap+ef61:. Parsing a document normalizes its portable IRIs to ap+ef61:, so re-serializing an object that another implementation signed with ap: IDs breaks its proof. Keep the received JSON of such documents, and compare portable IDs with arePortableUrisEqual() rather than as strings. The discussion is in
#826 and
#828, and the reasoning is in Canonical ap+ef61: scheme.
The second concerns compound documents. When a signed Note sits inside a signed Create, the verifier has to know which part of the JSON each proof covers, and neither FEP-8b32 nor Verifiable Credential Data Integrity defines that yet; the question is open in w3c/vc-data-integrity#350. Fedify uses an interim map-local profile, worked out in
#938. Each JSON map with a proof is its own secured document, each embedded portable object needs its own proof and its own
@context, and proof sets and chains are not supported. The profile authenticates the exact JSON values each proof covers; it does not promise that a child's JSON-LD expansion inside its parent matches its expansion on its own.
@silverpill@mitra.social,
@dmitrizagidulin, and
@by_caballero@mastodon.social reviewed the proposal in that thread, and
@silverpill@mitra.social reproduced its test vectors independently. See Map-local compound proofs.
What is not implemented
Fedify does not implement FEP-ae97, the companion proposal for client-side signing. There are no endpoints for registering actors, submitting client-signed activities to a portable outbox, or gateway discovery, and no media upload and deletion endpoints under /.well-known/apgateway-media. Your own outbox listeners can still relay activities that a client signed, unchanged. Fedify also does not copy or reconcile actors, objects, or collections between gateways, so running an actor on several gateways means keeping their data in sync yourself. There is no workflow for rotating a DID's key or migrating an actor to another DID. Fedify resolves verification methods only for did:key DIDs with Ed25519 keys; other DID methods verify only if your document loader resolves them. Gateways must be plain origins, since the arbitrary gateway paths that FEP-ef61 discusses are not supported. The full list is in Not supported.
Interoperability
The profile was tested against tootik v0.25.4 and Mitra v5.10.0 in
#1202. Fedify verifies tootik's portable actors, activities, and HTTP Signatures, and Mitra's gateway HTTP Signatures on activities that a client signed. Both accept the portable activities that Fedify sends. Two fixes came out of this testing. Fedify now reads a gateways list that tootik leaves unmapped in its JSON-LD context. It also serializes gateways as bare origins, because Mitra rejects a trailing slash. Fedify has not yet verified an actor or activity that Mitra signed itself, and Mastodon's handling of portable actors has not been tested. The FEP-ef61 interoperability section of FEDERATION.md records what was tested and how.
Tooling
fedify lookup looks up portable objects by their ap: and ap+ef61: IDs, compatible identifiers, and the handles of portable actors, and it verifies their proofs. When no gateway returns an acceptable object, it says why. A new --gateway option on fedify lookup, fedify inbox, and fedify webfinger names the gateways to ask. fedify inbox --follow follows portable actors, and fedify webfinger accepts portable actor IDs. See Looking up portable objects in the CLI manual.
The mock federation and contexts in
@fedify/testing support portable IDs, verification against fixture document loaders, gateway requests, and hashlink media, so tests can exercise portable objects without a live gateway.
@fedify/lint's actor URI rules accept the portable IDs that the getPortable*Uri() methods build.
@fedify/next now passes hashlink media requests to Fedify, a problem reported in
#1149 and fixed in
#1170; to have Next.js run the middleware for them, add { source: "/.well-known/apgateway/:path*" } to your matcher.
Background tasks
Fedify already runs activity delivery and inbox processing on queue workers, but applications usually have jobs of their own: digest emails, timeline rebuilds, link previews. Until now, those jobs could not use Fedify's queues, serialization, or retries. Fedify 2.4.0 opens the same machinery to application-defined tasks.
A task is defined once with defineTask() and enqueued from any Context with enqueueTask() or enqueueTaskMany(). Every task takes a Standard Schema, such as a Zod or Valibot schema, which types its payload. Fedify validates the payload when it is enqueued and again when a worker picks it up; the second check catches payloads from an earlier deployment that no longer match the schema:
import { createExponentialBackoffPolicy } from "
@fedify/fedify";
import { z } from "zod";
const sendDigest = federation.defineTask("sendDigest", {
schema: z.object({ userId: z.string(), since: z.date() }),
handler: async (ctx, data) => {
// data is typed as { userId: string; since: Date }
await sendEmail(data.userId, await buildDigest(data.userId, data.since));
},
retryPolicy: createExponentialBackoffPolicy({ maxAttempts: 3 }),
});
// Anywhere with a Context:
await ctx.enqueueTask(sendDigest, { userId: "alice", since: new Date() }, {
delay: { minutes: 30 },
deduplicationKey: "digest:alice",
});
Fedify serializes payloads with devalue, so Date, Map, Set, URL, bigint, Temporal values, circular references, and Activity Vocabulary objects all survive the trip through any message queue backend. A Note in a payload comes back as a Note. Failed handlers are retried with exponential backoff by default, and queues with native retries handle retries themselves. Tasks fall back to the outbox queue unless you give them their own. Use the new task slot of the queue option or a per-task queue for that, and startQueue(ctxData, { queue: "task" }) runs a task-only worker. Setting taskQueueResolution: "strict" turns the fallback into an error.
A deduplicationKey deduplicates enqueues. The feature came from
@julian@fietkau.social's point in
#206 that recurring tasks are hard to manage when you cannot tell whether one is already queued. A queue that declares nativeDeduplication enforces the key itself; otherwise, Fedify keeps a best-effort marker in the key–value store through cas(). Each task runs in a fedify.task span, and the queue metrics from 2.3.0 now include task queues. The Background tasks chapter covers routing, retries, deduplication, and the limitations; cron-style scheduling, result backends, and priorities are out of scope for now.
ChanHaeng Lee (
@2chanhaeng@hackers.pub) implemented the API: the core in
#803, deduplication in
#806, and observability in
#812, following the plans in
#797,
#798, and
#799. The work was merged in
#923, closing
#206, which had been open since February 2025.
Media uploads
Fedify 2.2.0 added client-to-server outbox listeners, but a C2S client also has to upload images and video before it can post them. That traffic does not go through POST /outbox. Fedify 2.4.0 supports the ActivityPub Media Upload extension, a SocialCG proposal last updated in 2017 that never reached W3C Recommendation status.
setMediaUploader() registers a multipart/form-data endpoint. Its callback receives the uploaded file and the object shell the client posted along with it. If the callback returns the created object, Fedify responds with 201 Created; if it returns a URL where the object will appear once processing finishes, Fedify responds with 202 Accepted:
federation
.setMediaUploader(
"/users/{identifier}/media",
async (ctx, identifier, file, object) => {
const stored = await uploadToStorage(file);
return new Image({
id: ctx.getObjectUri(Image, { uuid: stored.uuid }),
url: new URL(stored.publicUrl),
mediaType: file.type,
name: object.name,
});
},
)
.authorize(async (ctx, identifier) => {
const session = await verifyAccessToken(
ctx.request.headers.get("authorization"),
);
return session?.identifier === identifier;
});
The actor dispatcher advertises the endpoint itself by setting endpoints: new Endpoints({ uploadMedia: ctx.getMediaUploaderUri(identifier) }), the same way it places its inbox and outbox URIs. Without an authorize() hook, anyone who finds the endpoint can upload to it. For that reason, Fedify logs a warning when an uploader is registered without one, and when the returned object's URI does not match an object dispatcher or the actor does not advertise the endpoint. Four new
@fedify/lint rules catch the same mistakes before they run. Fedify reads the upload into memory and sets no size limit of its own, so cap the request size at your reverse proxy. Storing the file and serving the object back are up to the application. See the Media upload chapter; the work is in
#754 and
#927.
Inbox request reports
Fedify decides several things about every inbox delivery: which signature mechanisms applied, which keys they tried, whether the actor owned the key, and what happened to the activity. Before this release, applications saw only part of that. A Linked Data Signature by a key the actor did not own was counted the same as a bad signature, and the key that verified a request was never handed to the application. The request in
#1191 came from an effort to log these decisions for a debugging tool.
The new onRequestFinished() callback on inbox listeners receives an InboxRequestReport for every delivery to an inbox route, including rejected requests and requests that fail before verification:
federation
.setInboxListeners("/users/{identifier}/inbox", "/inbox")
.on(Follow, async (ctx, follow) => { /* ... */ })
.onRequestFinished(async (ctx, report) => {
await db.insertInboxLog({
inbox: report.inbox.kind, // "personal" | "shared" | "portable"
authentication: report.authentication.status,
outcome: report.outcome.type === "response"
? report.outcome.disposition // "processed" | "enqueued" | "duplicate" | ...
: `exception:${report.outcome.stage}`,
keyIds: report.attempts
.flatMap((attempt) => attempt.checks)
.flatMap((check) => check.triedKeys)
.map((key) => key.id?.href),
});
});
Each HTTP Signature, Linked Data Signature, or Object Integrity Proof check appears as an attempt with the actual keys it tried, including a stale cached key and its refreshed replacement. The report also carries the final authentication decision, such as actorKeyMismatch or proofPolicy, and the response or exception that ended the request. Fedify awaits the callback whether or not the trace is sampled. Errors it throws are logged without changing the response, and enqueued means the queue accepted the activity, not that a worker later processed it. Mock federations in
@fedify/testing accept the same callback. See Observing inbox requests; the implementation is in
#1201.
Tombstones for deleted objects
Actor dispatchers have been able to return a Tombstone since 2.2.0, but object dispatchers could only return null. A deleted post was answered with 404 Not Found, as if it had never existed, so applications that wanted 410 Gone, as ActivityPub recommends, needed their own route in front of Fedify.
Object dispatchers may now return a Tombstone, which Fedify serves with 410 Gone and the serialized tombstone after applying the authorization predicate:
federation.setObjectDispatcher(
Note,
"/users/{identifier}/notes/{id}",
async (ctx, values) => {
const post = await getPost(values.identifier, values.id);
if (post == null) return null;
if (post.deletedAt != null) {
return new Tombstone({
id: ctx.getObjectUri(Note, values),
formerType: Note,
deleted: post.deletedAt,
});
}
return new Note({ id: ctx.getObjectUri(Note, values), content: post.content });
},
);
The return type of ObjectDispatcher widens to TObject | Tombstone | null. RequestContext.getObject() still returns null for a tombstone unless you pass { tombstone: "passthrough" } or ask for the Tombstone or Object class itself. Dispatchers registered for Tombstone or Object that already returned tombstones now respond with 410 rather than 200. See Deleted objects; the change was proposed in
#1112 and made in
#1117.
Limits on what a remote peer can make Fedify do
Much of what Fedify fetches is chosen by the sender of an incoming request. Key IDs in signatures are one example, and the servers behind them can be slow on purpose. Several changes in 2.4.0 bound that work.
As
#1130 points out, a request may carry several RFC 9421 signatures, and each one can make Fedify fetch a key from a URL of the sender's choosing. Fedify now verifies at most the first three, in Signature-Input order, and ignores the rest. A signature counts toward the limit even if it fails before its key is fetched, and a key named by several signatures is looked up once. The new FederationOptions.maxHttpSignatures option, added with the limit in
#1166, changes it.
The built-in document loaders now give each call ten seconds by default, a limit proposed in
#1131 and added in
#1169. The time limit covers every redirect, alternate document, double-knocking retry, and the response body. A timed-out call throws a FetchError whose cause is a DOMException named "TimeoutError". Error responses are read in full before the loader throws, up to 1 MiB, so that a server cannot send a 404 header and then stall the body. FederationOptions.documentLoaderTimeout changes the limit or turns it off with null, and custom document loaders are not affected. Since
#913, getDocumentLoader() also rejects HTML responses that do not advertise an ActivityPub alternate with a FetchError, rather than failing inside JSON.parse(), which
#912 found cluttering error trackers.
Cached public keys and remembered HTTP Message Signatures specs used to live forever in the key–value store.
#1017 reports a production Redis instance holding 194,424 public-key entries, about 165 MiB, for actors that had mostly stopped federating. Keys now expire after 30 days and specs after 90, configurable through FederationOptions.publicKeyTtl and FederationOptions.httpMessageSignaturesSpecTtl. Entries written by earlier versions have no expiry until they are next written. The Clearing legacy cache entries section shows how to remove them for Redis, PostgreSQL, and other stores. Heewon Chae (
@heeoneie) implemented this in
#1027, their first contribution to Fedify.
const federation = createFederation({
kv,
maxHttpSignatures: 1, // default: 3
documentLoaderTimeout: { seconds: 5 }, // default: 10 seconds
publicKeyTtl: { days: 7 }, // default: 30 days
httpMessageSignaturesSpecTtl: { days: 30 }, // default: 90 days
});
Finally, verifyProof() now authenticates every option of an Ed25519 JCS proof except proofValue, including expires, domain, challenge, and nonce. It also rejects expired or malformed ones. Previously, a field such as expires could be added to an already signed proof without invalidating it. Jiwon Kwon (
@z9mb1@hackers.pub) spotted this in review of
#968. Callers can now require a domain and challenge through VerifyProofOptions to prevent cross-domain or replayed use.
New packages
@fedify/adonisjs
@fedify/adonisjs integrates Fedify with AdonisJS. Running node ace add
@fedify/adonisjs registers a service provider that owns the federation's lifecycle and a server middleware that mounts it. It also scaffolds config/fedify.ts, start/federation.ts, and app/federation/main.ts. Controllers get a ctx.federation request context:
// app/federation/main.ts
import federation from "
@fedify/adonisjs/services/builder";
import { Person } from "
@fedify/vocab";
federation.setActorDispatcher("/actors/{identifier}", (ctx, identifier) =>
new Person({ id: ctx.getActorUri(identifier), preferredUsername: identifier }));
The middleware sits first in AdonisJS's server stack rather than its router stack. That way Fedify sees paths the router does not know, such as /.well-known/webfinger, and reads request bodies before the body parser consumes them. The package targets Node.js and is published to npm only. See the AdonisJS section of the integration guide.
Samuel Brinkmann (
@sabrinkmann@hachyderm.io) contributed the package in
#1006, closing
#139, and built it on a prototype that Emelia Smith (
@thisismissem@hachyderm.io) attached to that issue.
npm add
@fedify/adonisjs
pnpm add
@fedify/adonisjs
yarn add
@fedify/adonisjs
@fedify/interaction-controls
GoToSocial interaction controls, FEP-044f quote authorization, and FEP-7aa9 featured collections share a request-and-authorization flow. A server asks to reply to, quote, or feature a post, and the author's server approves according to the post's interactionPolicy.
@fedify/interaction-controls implements that flow for like, reply, announce, quote, and feature interactions. Each has a helper, such as likeInteraction or quoteInteraction, that creates and verifies requests and authorizations, evaluates policies, and recognizes interactions that arrived without a request:
import { likeInteraction } from "
@fedify/interaction-controls";
// When a LikeRequest arrives:
const verified = await likeInteraction.verifyRequest(ctx, { request });
if (verified.verified) {
const decision = await likeInteraction.evaluatePolicy(ctx, {
subject: note,
requester: request.actorId!,
});
if (decision.result === "automatic") { // or "manual" or "denied"
const authorization = likeInteraction.createAuthorization({
id: new URL("
https://example.com/authorizations/1"),
attributedTo: owner,
interactingObject: like,
interactionTarget: note,
});
// ...
}
}
The package does not install inbox listeners or store anything; the application decides where requests and authorizations live and when a human needs to approve. Verification fails closed. Without a policy, likes, replies, and announces are approved automatically, while quotes and features are denied.
@fedify/vocab gains the FEP-7aa9 types this needs: FeaturedCollection, FeaturedItem, FeatureRequest, and FeatureAuthorization, along with actors' featuredCollections and InteractionPolicy.canFeature. Samuel Brinkmann asked for them in
#810 once Mastodon 4.6 shipped the FEP. See the Interaction controls chapter; the work is in
#914 and
#929.
npm add
@fedify/interaction-controls
pnpm add
@fedify/interaction-controls
yarn add
@fedify/interaction-controls
deno add jsr:
@fedify/interaction-controls
bun add
@fedify/interaction-controls
@fedify/netlify
@fedify/netlify lets a Fedify application run on Netlify Functions without an external database or queue. NetlifyMessageQueue submits jobs as Netlify Async Workloads events, and createNetlifyQueueHandler() turns a Function into their consumer, with delayed delivery, native retries, and per-key FIFO ordering. NetlifyBlobsKvStore is a key–value store on Netlify Blobs with expiration, prefix listing, and compare-and-swap:
import {
createNetlifyQueueHandler,
NetlifyBlobsKvStore,
NetlifyMessageQueue,
} from "
@fedify/netlify";
import { AsyncWorkloadsClient } from "
@netlify/async-workloads";
import { getStore } from "
@netlify/blobs";
export const kv = new NetlifyBlobsKvStore(
getStore({ name: "fedify", consistency: "strong" }),
);
export const queue = new NetlifyMessageQueue({
client: new AsyncWorkloadsClient(),
orderingKv: kv,
});
// netlify/functions/fedify-queue.ts
export default createNetlifyQueueHandler({
queue,
maxRetries: 4,
federation: () => builder.build({ kv, queue, manuallyStartQueue: true }),
});
The key–value store exists because of cost.
#1010 describes a static blog whose ActivityPub traffic kept a Netlify Database from ever idling, which used most of the account's monthly credits. Jiwon Kwon contributed NetlifyBlobsKvStore in
#1029, and the queue landed in
#934. See Netlify Functions in the deployment guide.
npm add
@fedify/netlify
pnpm add
@fedify/netlify
yarn add
@fedify/netlify
deno add jsr:
@fedify/netlify
bun add
@fedify/netlify
@fedify/pglite
@fedify/pglite provides PgliteKvStore, a KvStore on an embedded PGlite database that you create and pass in. It uses the same schema as PostgresKvStore. It is meant for a single PGlite instance in a single runtime isolate, so it does not include a message queue: PGlite does not share data between processes.
import { PGlite } from "
@electric-sql/pglite";
import { PgliteKvStore } from "
@fedify/pglite";
const federation = createFederation({
kv: new PgliteKvStore(new PGlite("./data/fedify")),
});
ChanHaeng Lee contributed the package in
#1020, together with testKvStore() in
@fedify/testing. testKvStore() is a conformance suite for KvStore implementations, the counterpart to testMessageQueue(). See PgliteKvStore.
npm add
@fedify/pglite
pnpm add
@fedify/pglite
yarn add
@fedify/pglite
deno add jsr:
@fedify/pglite
bun add
@fedify/pglite
Compare-and-swap for PostgreSQL and Redis
Portable inbox forwarding, task deduplication, Netlify queue ordering, and the delivery circuit breaker all need an atomic compare-and-swap on the key–value store. PostgresKvStore now implements cas(), added in
#934, and so does RedisKvStore, requested in
#1163 and added in
#1167. The Redis version uses a single-key Lua script, which works on standalone Redis and Redis Cluster. Before this, the circuit breaker fell back to racy updates on Redis.
Both come with conditions. RedisKvStore needs Redis to permit EVAL, and custom codecs must encode equal values identically. PostgresKvStore now creates logged tables by default, because losing sequence state in crash recovery could block queued events for good. It migrates existing unlogged tables when it initializes. That one-time migration rewrites the table and locks it exclusively, so schedule the upgrade accordingly if the table is large or busy; unlogged: true keeps the old behavior.
fedify init and the CLI
fedify init can now scaffold a SvelteKit project, contributed by Jang Hanarae (
@menele@hackers.pub) in
#971. Jang Hanarae also added a test task to generated projects in
#990. It starts the app, waits for it to be ready, and checks that it resolves a local actor, which gives new projects a smoke test to run after scaffolding and after later changes. Before generating anything, fedify init now checks that the selected Deno, Bun, or Node.js meets Fedify's minimum version, or a framework's higher one, such as Astro's Node.js 22.12. It fails with a clear error in non-interactive mode, and in interactive mode it disables the affected package managers. Lee Jeongmin (
@userjmmm@hackers.pub) contributed the check in
#981. Astro projects now use Astro 7, and since
#936 @fedify/astro is tested against Astro 5, 6, and 7 with real builds on Node.js, Deno, and Bun, as
#931 asked.
fedify tunnel gains fedify.com.es, a tunneling service run by the Fedify project that needs no account; the CLI pins its SSH host key and refuses a mismatched server before exposing a local port. localhost.run is removed in the same change,
#940, because the service no longer exists. fedify lookup now times out each request after ten seconds when -T/--timeout is not given, and the option now also bounds the wait for a DNS lookup. The CLI moves to Optique 1.3.2 in
#1197, which handles attached values like --timeout=30 consistently, gives better suggestions for mistyped options, and no longer hides errors for known options behind positional arguments before --.
Lint rules
@fedify/lint gains several rules beyond the media upload ones mentioned above. actor-preferred-username-required, requested in
#895 and added in
#1022, warns when an actor dispatcher returns an actor without preferredUsername. outbox-listener-delivery-not-awaited, from
#1057 and
#1067, reports an outbox listener that calls ctx.sendActivity() or ctx.forwardActivity() and drops the promise. On Cloudflare Workers, such an activity may never leave, because pending work is discarded once the response returns. await, return, Promise.all(), Promise.allSettled(), and waitUntil() count as handling the promise, while void, Promise.race(), and Promise.any() are accepted as a deliberate choice not to wait. The rule is a warning in the ESLint recommended configuration and an error in strict. Oxlint users enable it by name, and it is not available in Deno Lint.
In
#1050, which resolves
#900, the existing outbox-listener-delivery-required rule began following control flow instead of scanning the listener's source as text. It reports a listener whose only delivery calls sit in a dead branch, after an unconditional return or throw, or in a function that is never used, and it stays quiet when it cannot tell. Jae-Hyuk-Jang (
@jhyuk@hackers.pub) contributed this change and both new rules. archie (
@ArchieTansaria) then taught both delivery rules about statically false loops and loop binding patterns in
#1088. See the linting guide.
Other changes
@fedify/vocab supports the FEP-22cd draft for translations. A Translation records a translated version's language, translators, source object, and source review time, and the new Object.translations property attaches them to a post without creating separate posts. See Translation metadata. (
#1037,
#1038)
@fedify/vocab-tools gains an extraContext property option, which adds a JSON-LD context only when its terms are used, and a trustEmbeddedObjects type option. (
#1037,
#1038)
Vocabulary fetch and parse failures that suppressError: true handles are now logged as warnings rather than errors, so that they no longer show up as application errors. Contributed by Jae Hui Hong (
@axz0612@hackers.pub). (
#933,
#1035)
A queue whose enqueueMany() makes separate sends can set MessageQueue.atomicEnqueueMany to false. Fedify then rejects a multi-message batch governed by one deduplicationKey up front, since a partial send followed by a retry could enqueue duplicates. (
#930,
#934)
CommonJS builds that use Temporal bundle temporal-polyfill instead of requiring
@js-temporal/polyfill at runtime, and type declarations rely on the standard esnext.temporal lib. (
#823,
#925)
The document loaders' Accept header now includes the ActivityStreams profile on the JSON-LD media type, as ActivityPub and FEP-ef61 gateways require. (
#834,
#1077)
The relay documentation now uses the canonical actor and shared inbox URIs, separates Mastodon-style and LitePub-style subscriptions, and explains what remains the application's responsibility. Contributed by Jiwon Kwon. (
#899,
#996)
Bug fixes
Fixed outbound delivery circuit breaker transitions on key–value stores that compare encoded values. Existing half-open states can recover after switching to a CAS-capable store. (
#1163,
#1167)
Fixed fedify lookup --recurse reporting a timeout or other network failure as a possibly private object; it now reports the actual cause. (
#1156,
#1199)
Fixed the -p/--allow-private-address option of fedify webfinger being ignored. (
#1156,
#1199)
Fixed outbox-listener-delivery-required and outbox-listener-delivery-not-awaited losing track of an object's functions when a nested helper assigns another property of that object. (
#1125,
#1140)
Upgrading
npm add
@fedify/fedify@2.4.0
pnpm add
@fedify/fedify@2.4.0
yarn add
@fedify/fedify@2.4.0
deno add jsr:
@fedify/fedify@2.4.0
bun add
@fedify/fedify@2.4.0
Update the other
@fedify/* packages you use to 2.4.0 at the same time. To update the CLI, run npm install -g
@fedify/cli@2.4.0, or see the installation instructions for other package managers.
Most applications need no code changes, but these changes in behavior may affect you:
Activities from actors whose IDs are FEP-ef61 compatible identifiers are rejected with 401 Unauthorized unless they carry a valid Object Integrity Proof by the actor's DID. Keys at compatible identifiers, and keys at ordinary URLs that claim a portable owner, are no longer trusted by origin.
Property accessors given a Context as their options, such as await create.getObject(ctx), now verify the portable objects they dereference, including references to compatible identifiers from objects with ordinary HTTP(S) IDs.
Your dispatchers may be called for requests to /.well-known/apgateway/, and Context.sendActivity() may reject an activity that embeds others' portable objects. Next.js applications need the matcher shown above to serve hashlink media.
Only the first three RFC 9421 signatures of a request are verified. Set maxHttpSignatures if you need more.
The built-in document loaders time out after ten seconds, and fedify lookup does too.
Cached public keys expire after 30 days and HTTP Message Signatures specs after 90 days.
Object dispatchers registered for Tombstone or Object that return tombstones now respond with 410 Gone instead of 200 OK.
PostgresKvStore migrates existing unlogged tables to logged tables on initialization, which locks the table.
RedisKvStore needs EVAL permission for cas().
Queue workers from older versions deliver queued activities for portable inboxes only through the first gateway. Upgrade workers before the servers that enqueue deliveries.
Custom implementations of the Context and RequestContext interfaces need the new getPortable*Uri() methods and isSignedByAudience().
fedify tunnel no longer supports localhost.run.
Acknowledgments
Thanks to this release's contributors:
Samuel Brinkmann (
@sabrinkmann@hachyderm.io):
@fedify/adonisjs, and the request for FEP-7aa9 vocabulary
Jang Hanarae (
@menele@hackers.pub): SvelteKit support and the test task in fedify init
Lee Jeongmin (
@userjmmm@hackers.pub): runtime version verification in fedify init
Jae-Hyuk-Jang (
@jhyuk@hackers.pub): the actor-preferred-username-required and outbox-listener-delivery-not-awaited lint rules, and control-flow analysis for outbox-listener-delivery-required
archie (
@ArchieTansaria): loop handling in the outbox delivery lint rules
Jae Hui Hong (
@axz0612@hackers.pub): warning-level logging for suppressed vocabulary failures
Heewon Chae (
@heeoneie): expiring public key and HTTP Message Signatures spec caches
ChanHaeng Lee (
@2chanhaeng@hackers.pub) and Jiwon Kwon (
@z9mb1@hackers.pub) joined as maintainers after 2.3.0. ChanHaeng built the background task API and
@fedify/pglite, Jiwon built NetlifyBlobsKvStore and rewrote the relay documentation, and both reviewed much of the rest of this release.
Many people added tests, documentation, and infrastructure during this cycle, often starting from a good first issue: Seoa Yoon (
@bananamilk452@hackers.pub), Lim Kyoujin (
@dktsudgg@hackers.pub),
@m2nsp@hackers.pub, Cho Seongmin (
@seongmin36@hackers.pub), Safal Shrestha (
@Safal-Shrestha-SS), Jo Youngjae (
@jaonz6057@hackers.pub),
@kecan0406@hackers.pub, Loi Nguyen (
@lntutor), Oh Taejun (
@0w0@hackers.pub), Yerin Park (
@dstforye@hackers.pub), Lee Dogeon (
@moreal@hackers.pub), and Sae Jin Kim (
@siliconsjang@hackers.pub).
The FEP-ef61 work owes a lot to people outside the project.
@anotherdoesnm opened the request in
#288.
@silverpill@mitra.social, the author of FEP-ef61 and FEP-ae97, clarified the gateway trust model, reviewed the compound proof profile, and checked its test vectors.
@dmitrizagidulin and
@by_caballero@mastodon.social weighed in on the profile's JSON-LD questions in
#938. Testing against tootik and Mitra led to two of the interoperability fixes in this release.
See CHANGES.md for the complete changelog.
