Access control

This API is available since Fedify 0.7.0.

Fedify provides a flexible access control system that allows you to control who can access your resources through the method named authorized fetch, which is popularized by Mastodon. The method requires HTTP Signatures to be attached to even GET requests, and Fedify automatically verifies the signatures and derives the actor from the signature.

NOTE

Although the method is popularized by Mastodon, it is not a part of the ActivityPub specification, and clients are not required to use the method. Turning this feature on may limit the compatibility with some clients.

Enabling authorized fetch

To enable authorized fetch, you need to register an AuthorizePredicate callback with ActorCallbackSetters.authorize() or CollectionCallbackSetters.authorize(), or ObjectAuthorizePredicate callback with ObjectCallbackSetters.authorize(). The below example shows how to enable authorized fetch for the actor dispatcher:

import { federation } from "./your-federation.ts";
import { isBlocked } from "./your-blocklist.ts";

federation
  .setActorDispatcher("/users/{identifier}", async (ctx, identifier) => {
    // Omitted for brevity; see the related section for details.
  })
  .authorize(async (ctx, identifier) => {
    const signedKeyOwner = await ctx.getSignedKeyOwner();
    if (signedKeyOwner == null) return false;
    return !await isBlocked(identifier, signedKeyOwner);
  });

The equivalent method is available for collections as well:

import { federation } from "./your-federation.ts";
import { isBlocked } from "./your-blocklist.ts";

federation
  .setOutboxDispatcher("/users/{identifier}/outbox", async (ctx, identifier) => {
    // Omitted for brevity; see the related section for details.
  })
  .authorize(async (ctx, identifier) => {
    const signedKeyOwner  = await ctx.getSignedKeyOwner();
    if (signedKeyOwner == null) return false;
    return !await isBlocked(identifier, signedKeyOwner);
  });

If the predicate returns false, the request is rejected with a 401 Unauthorized response.

Fine-grained access control

You may not want to block everything from an unauthorized user, but only filter some resources. For example, you may want to show some private posts to a specific group of users. In such cases, you can use the RequestContext.getSignedKeyOwner() method inside the dispatcher to get the actor who signed the request and make a decision based on the actor.

The method returns the Actor object who signed the request (more precisely, the owner of the key that signed the request, if the key is associated with an actor). The below pseudo code shows how to filter out private posts:

import { federation } from "./your-federation.ts";
import { getPosts, toCreate } from "./your-model.ts";

federation
  .setOutboxDispatcher("/users/{identifier}/outbox", async (ctx, identifier) => {
    const posts = await getPosts(identifier);  // Get posts from the database
    const keyOwner = await ctx.getSignedKeyOwner();  // Get the actor who signed the request
    if (keyOwner == null) return { items: [] };  // Return an empty array if the actor is not found
    const items = posts
      .filter(post => post.isVisibleTo(keyOwner))  
      .map(toCreate);  // Convert model objects to ActivityStreams objects
    return { items };
  });

Instance actor

When you enable authorized fetch, you need to fetch actors from other servers to retrieve their public keys. However, fetching resources from other servers may cause an infinite loop if the other server also requires authorized fetch, which causes another request to your server for the public key, and so on.

The most common way to prevent it is a pattern called instance actor, which is an actor that represents the whole instance and exceptionally does not require authorized fetch. You can use the instance actor to fetch resources from other servers without causing an infinite loop.

Usually, many ActivityPub implementations name their instance actor as their domain name, such as example.com@example.com. Here is an example of how to implement an instance actor:

federation
  .setActorDispatcher("/actors/{identifier}", async (ctx, identifier) => {
    if (identifier === ctx.hostname) {
      // A special case for the instance actor:
      return new Application({
        id: ctx.getActorUri(identifier),
        // Omitted for brevity; other properties of the instance actor...
        // Note that you have to set the `publicKey` property of the instance
        // actor.
      });
    }

    // A normal case for a user actor:
    return new Person({
      id: ctx.getActorUri(identifier),
      // Omitted for brevity; other properties of the user actor...
    });
  })
  .authorize(async (ctx, identifier) => {
    // Allow the instance actor to access any resources:
    if (identifier === ctx.hostname) return true;
    // Create an authenticated document loader behalf of the instance actor:
    const documentLoader = await ctx.getDocumentLoader({
      identifier: ctx.hostname,
    });
    // Get the actor who signed the request:
    const signedKeyOwner = await ctx.getSignedKeyOwner({ documentLoader });
    if (signedKeyOwner == null) return false;
    return !await isBlocked(identifier, signedKeyOwner);
  });