Skip to content

Cattle Grid

Fediverse applications perform many actions, one of them is to process incoming requests. cattle_grid is meant as a first layer of processing incoming requests. It currently performs the following two tasks of the processing chain

  • Check if the request is signed with a HTTP signature, if yes check the signature
  • If valid: Add the signer to the request headers
  • If invalid: Reject the request
  • If the request is signed, check the signer against a domain blocklist. If the signer’s domain is on it, reject the request.

Due to the nature of the Fediverse, these are features that every Fediverse application should have. We furthermore, note that in order to verify HTTP signatures, cattle_grid needs to

  • Look up remote actor objects to retrieve their public keys.
  • Cache these public keys, they should not change.
  • Provide an actor, to be able to sign requests
  • Provide a webfinger endpoint.

Is cattle_grid for me?

This really depends on your view how to build a Fediverse application. If you are building many small applications, cattle_grid is for you. This means that all your applications get to share the same authentication layer (for incoming Fediverse requests).

If you are starting developing, and want to just build something small, cattle_grid can help you. However, one should be aware that you are trading implementing code for configuration. If you need an example of how a cattle_grid dependent application looks like take a look at [jskitten], which is a reply bot in JavaScript.

Combined with what I describe as an actor layer, one can use these two components to build applications whose main function is to either only post, e.g. an RSS to Fediverse bridge, or to process incoming messages in some fashion. The additional layer is needed to have common management of tasks such as followers management, which will be the same for all these applications.

Quick start

cattle_grid is a python application based on bovine. It can be installed from PyPI via

pip install cattle_grid

Then one needs to run

python -mcattle_grid.config

to create a configuration file, and can then run cattle_grid via

uvicorn --factory cattle_grid:create_app

One can then use it to verify the signatures of incoming requests by sending the headers to the /auth endpoint. The request flow is explained in here.

Warning

cattle_grid does not check that the digest is correct. This is the responsibility of your application. One can consider this a performance optimization, as it means that nginx only needs to transmit the headers to cattle_grid in order to get the authentication result.

Technical considerations

cattle_grid has so far only been tested with together with nginx and its auth_request directive. It should however be useable with other http servers, if they support a similar authentication request.

Next, I’m currently using cattle_grid with an sqlite database, it should not be complicated to exchange the database backend as long as tortoise-orm supports it.