7.6 KiB
ForgeFed/ActivityPub Federation in Vervis
At the time of writing, here's the current status of federation implemented in Vervis.
Summary:
- To post a comment on a local ticket (same server), log in and browse to the ticket's page and use the ticket reply form, the regular way it's been on Vervis.
- To post a comment on a remote ticket (other server), log in and browse to the /publish page, fill the form and the comment will be delivered to the right place
For more details, read below.
Federation triggered by regular UI
- Ticket comments are federated. If you submit a ticket comment, local and remote users who previously commented on the same ticket will get your comment delivered to their inboxes. The user who created the ticket's project will have it delivered to them too.
- If you comment on a ticket, you automatically become a ticket follower, and all future comments on the ticket will be delivered to your inbox.
- You can see users' outboxes.
- You can see your inbox.
- If you create a project, all comments on all tickets of the project will be delivered to your inbox.
- There is UI for notifications about comments on tickets you commented on or whose projects you created. However there's no JS to display them in real-time and no email integration.
The ticket comment UI allows to see tickets and comments, and if you're logged in, you can post new comments. If you wish to post a comment on a ticket hosted on another server, not the one on which your account is hosted, see the dedicated federation pages listed below.
GET endpoints
GET /publish
A page where you can write and publish a ticket comment, either on a local ticket (i.e. a ticket on a project hosted on the same server as your account) or on a remote ticket (i.e. a ticket on a project hosted on some other server).
GET /inbox
A test page that displays received activities and the result of their processing.
GET /s/joe/inbox
A page that displays your personal inbox. It should list all ticket comments on projects you've created and and ticket comments on tickets you previously commented on.
GET /s/joe/outbox
A page that displays your personal outbox. It should list all the activities you're published, all ticket comments you've made.
POST endpoints
POST /s/joe/outbox
Personal endpoint for publishing ticket comments. When you submit the form in the /publish page, this is where it is sent. In the future you'll be able to see the content of your outbox, and other people will be able to see the public items in your outbox.
You can access this endpoint without using the /publish page, but Vervis doesn't have OAuth2 support yet, so you'll need to log in first and grab the cookie, and send it along with the request.
POST /s/joe/inbox
Personal endpoint to which other servers deliver ticket comments for you to see. These are comments on tickets on which you previously commented, and thus automatically became a follower of thosr tickets.
POST /s/joe/p/proj/inbox
Per-project inbox, to which projects receive ticket comments from other servers. If someone on another server publishes a comment on your project, then your project will receive the comment at this endpoint and the comment will be displayed when you visit the ticket page.
Spec
Federation in Vervis is done using ActivityPub. Below comes a description of the details that aren't already common on the Fediverse. The details are written informally in the form of short simple proposals.
(A) Authentication
Vervis uses HTTP Signatures to authenticate messages received in inboxes. The Host, (request-target), Date and Digest headers are required to be present and used in the signature, and the Digest header must be verified by computing the hash of the request body. Other headers may need signing too, as specified in the proposals below.
The publicKeyPem field maps to the PEM encoding of the key. The PEM encoding
contains not just the key itself, but also a code specifying the key type. The
Fediverse de-facto standard is RSA, more precisely PKCS#1 v1.5, and used with
the SHA-256 hash algorithm. This is often referred to as RSA-SHA256.
If the algorithm is specified in the Signature header, it must match the key
type in the PEM. But algorithm isn't required, and we should probably stop
using it.
(1) Actor key(s) in a separate document
Allow an actor's signing key to be a separate document, rather than embedded in the actor document. In Vervis, the use of that is for server-scope keys (see proposal below), but otherwise, an embedded key is just as good.
GET /users/aviva/keys/key1
{ "@context": "https://w3id.org/security/v1"
, "@id": "https://example.dev/users/aviva/keys/key1"
, "@type": "Key"
, "owner": "https://example.dev/users/aviva"
, "publicKeyPem": "-----BEGIN PUBLIC KEY----- ..."
}
GET /users/aviva
{ "@context":
[ "https://www.w3.org/ns/activitystreams"
, "https://w3id.org/security/v1"
]
, "id": "https://example.dev/users/aviva
, "type": "Person"
, "preferredUsername": "aviva"
, "name": "Aviva"
, "inbox": "https://example.dev/users/aviva/inbox"
, "outbox": "https://example.dev/users/aviva/outbox"
, "publicKey": "https://example.dev/users/aviva/keys/key1"
}
Authentication requirements:
- The
keyIdfrom the signature header matches the@idin the document you receive - The and key and the owner actor IDs are on the same host
- They key specifies the
owner, and the owner actor'spublicKeylinks back to the key
(2) Multiple actor keys
Allow an actor to specify more than one key, or no key at all. This means that when you examine the owner actor of the key, you verify the actor links back to the key by checking that the key is listed among the actor's keys (instead of requiring/expecting only a single key to be specified by the actor).
The reason this is used in Vervis is for key rotation using a pair of server-cope keys (see proposal below).
When used along with proposal A.1, each key may be either embedded in the document, or a URI specifying the ID of a key defined in a separate document.
Actors that never need to post activities can simply not specify any keys at all.
GET /users/aviva
{ "@context":
[ "https://www.w3.org/ns/activitystreams"
, "https://w3id.org/security/v1"
]
, "id": "https://example.dev/users/aviva
, "type": "Person"
, "preferredUsername": "aviva"
, "name": "Aviva"
, "inbox": "https://example.dev/users/aviva/inbox"
, "outbox": "https://example.dev/users/aviva/outbox"
, "publicKey":
[ { "id": "https://example.dev/users/aviva#main-key"
, "type": "Key"
, "owner": "https://example.dev/users/aviva"
, "publicKeyPem": "-----BEGIN PUBLIC KEY----- ..."
}
, "https://example.dev/users/aviva/extra-keys/extra-key1"
, "https://example.dev/users/aviva/extra-keys/extra-key2"
]
}