Commit 905483e5 authored by Eugen Rochko's avatar Eugen Rochko

Update 2018-06-23_How-to-implement-a-basic-activitypub-server.md

parent d939d06d
Pipeline #38 passed with stages
in 0 seconds
......@@ -10,9 +10,9 @@ tags:
- activitypub
---
Today we'll be looking at how to connect the protocols powering Mastodon in the simplest way possible to enter the federated network. We will use static files, standard command-line tools, and some simple Ruby scripting, although the functionality should be easily adaptable to other programming languages.
Today well be looking at how to connect the protocols powering Mastodon in the simplest way possible to enter the federated network. We will use static files, standard command-line tools, and some simple Ruby scripting, although the functionality should be easily adaptable to other programming languages.
First, what's the end goal of this exercise? We want to send a Mastodon user a message from our own, non-Mastodon server.
First, whats the end goal of this exercise? We want to send a Mastodon user a message from our own, non-Mastodon server.
So what are the ingredients required? The message itself will be formatted with ActivityPub, and it must be attributed to an ActivityPub actor. The actor must be discoverable via Webfinger, and the delivery itself must be cryptographically signed by the actor.
......@@ -40,9 +40,9 @@ The actor is a publicly accessible JSON-LD document answering the question "who"
}
```
The `id` must be the URL of the document (it's a self-reference), and all URLs should be using HTTPS. You need to include an `inbox` even if you don't plan on receiving messages in response, because for legacy purposes Mastodon doesn't acknowledge inbox-less actors as compatible.
The `id` must be the URL of the document (it’s a self-reference), and all URLs should be using HTTPS. You need to include an `inbox` even if you don’t plan on receiving messages in response, because for legacy purposes Mastodon doesn’t acknowledge inbox-less actors as compatible.
The most complicated part of this document is the `publicKey` as it involves cryptography. The `id` will in this case refer to the actor itself, with a fragment (the part after `#`) to identify it--this is because we are not going to host the key in a separate document (although we could). The `owner` must be the actor's `id`. Now to the hard part: You'll need to generate an RSA keypair.
The most complicated part of this document is the `publicKey` as it involves cryptography. The `id` will in this case refer to the actor itself, with a fragment (the part after `#`) to identify it--this is because we are not going to host the key in a separate document (although we could). The `owner` must be the actor’s `id`. Now to the hard part: You’ll need to generate an RSA keypair.
You can do this using OpenSSL:
......@@ -53,7 +53,7 @@ The contents of the `public.pem` file is what you would put into the `publicKeyP
### Webfinger
What is Webfinger? It is what allows us to ask a website, "Do you have a user with this username?" and receive resource links in response. Implementing this in our case is really simple, since we're not messing with any databases and can hardcode what we want.
What is Webfinger? It is what allows us to ask a website, "Do you have a user with this username?" and receive resource links in response. Implementing this in our case is really simple, since were not messing with any databases and can hardcode what we want.
The Webfinger endpoint is always under `/.well-known/webfinger`, and it receives queries such as `/.well-known/webfinger?resource=acct:bob@my-example.com`. Well, in our case we can cheat, and just make it a static file:
......@@ -71,13 +71,13 @@ The Webfinger endpoint is always under `/.well-known/webfinger`, and it receives
}
```
The `subject` property here consists of the username (same as `preferredUsername` earlier) and the domain you're hosting on. This is how your actor will be stored on other Mastodon servers and how people will be able to mention it in toots. Only one link is required in the Webfinger response, and it's the link to the actor document.
The `subject` property here consists of the username (same as `preferredUsername` earlier) and the domain you’re hosting on. This is how your actor will be stored on other Mastodon servers and how people will be able to mention it in toots. Only one link is required in the Webfinger response, and it’s the link to the actor document.
After this is uploaded to your webhost and available under your domain with a valid SSL certificate, you could already look up your actor from another Mastodon by entering `alice@my-example.com` into the search bar. Although it'll look quite barren.
After this is uploaded to your webhost and available under your domain with a valid SSL certificate, you could already look up your actor from another Mastodon by entering `alice@my-example.com` into the search bar. Although itll look quite barren.
### The message
ActivityPub messages practically consist of two parts, the message itself (the object) and a wrapper that communicates what's happening with the message (the activity). In our case, it's going to be a `Create` activity. Let's say "Hello world" in response to my toot about writing this blog post:
ActivityPub messages practically consist of two parts, the message itself (the object) and a wrapper that communicates what’s happening with the message (the activity). In our case, it’s going to be a `Create` activity. Let’s say "Hello world" in response to my toot about writing this blog post:
{{< mastodon "https://mastodon.social/@Gargron/100254678717223630" >}}
......@@ -103,15 +103,15 @@ Here is how the document could look:
}
```
With the `inReplyTo` property we're chaining our message to a parent. The `content` property may contain HTML, although of course it will be sanitized by the receiving servers according to their needs--different implementations may find use for a different set of markup. Mastodon will only keep `p`, `br`, `a` and `span` tags. With the `to` property we are defining who should be able to view our message, in this case it's a special value to mean "everyone".
With the `inReplyTo` property we’re chaining our message to a parent. The `content` property may contain HTML, although of course it will be sanitized by the receiving servers according to their needs — different implementations may find use for a different set of markup. Mastodon will only keep `p`, `br`, `a` and `span` tags. With the `to` property we are defining who should be able to view our message, in this case it’s a special value to mean "everyone".
For our purposes, we don't actually need to host this document publicly, although ideally both the activity and the object would be separately available under their respective `id`. Let's just save it under `create-hello-world.json` because we'll need it later.
For our purposes, we don’t actually need to host this document publicly, although ideally both the activity and the object would be separately available under their respective `id`. Let’s just save it under `create-hello-world.json` because we’ll need it later.
So the next question is, how do we send this document over, where do we send it, and how will Mastodon be able to trust it?
### HTTP signatures
To deliver our message, we will use POST it to the inbox of the person we are replying to (in this case, me). That inbox is `https://mastodon.social/inbox`. But a simple POST will not do, for how would anyone know it comes from the real @alice@my-example.com and not literally anyone else? For that purpose, we need a HTTP signature. It's a HTTP header signed by the RSA keypair that we generated earlier, and that's associated with our actor.
To deliver our message, we will use POST it to the inbox of the person we are replying to (in this case, me). That inbox is `https://mastodon.social/inbox`. But a simple POST will not do, for how would anyone know it comes from the real @alice@my-example.com and not literally anyone else? For that purpose, we need a HTTP signature. It’s a HTTP header signed by the RSA keypair that we generated earlier, and that’s associated with our actor.
HTTP signatures is one of those things that are much easier to do with actual code instead of manually. The signature looks like this:
......@@ -125,7 +125,7 @@ The to-be-signed string would look something like this:
host: mastodon.social
date: Sun, 06 Nov 1994 08:49:37 GMT
Mind that there is only a +-30 seconds time window when that signature would be considered valid, which is a big reason why it's quite difficult to do manually. Anyway, assuming we've got the valid date in there, we now need to build a signed string out of it. Let's put it all together:
Mind that there is only a ±30 seconds time window when that signature would be considered valid, which is a big reason why it’s quite difficult to do manually. Anyway, assuming we’ve got the valid date in there, we now need to build a signed string out of it. Let’s put it all together:
```ruby
require 'http'
......@@ -142,4 +142,8 @@ HTTP.headers({ 'Host': 'mastodon.social', 'Date': date, 'Signature': header })
.post('https://mastodon.social/inbox', body: document)
```
Let's save it as `deliver.rb`. I am using the HTTP.rb gem here, so you'll need to have that installed (`gem install http`). Finally, run the file with `ruby deliver.rb`, and your message should appear as a reply on my toot!
\ No newline at end of file
Let’s save it as `deliver.rb`. I am using the HTTP.rb gem here, so you’ll need to have that installed (`gem install http`). Finally, run the file with `ruby deliver.rb`, and your message should appear as a reply on my toot!
### Conclusion
We have covered how to create a discoverable ActivityPub actor and how to send replies to other people. But there is a lot we haven’t covered: How to follow and be followed (it requires a working inbox), how to have a prettier profile, how to support document forwarding with LD-Signatures, and more.
\ No newline at end of file
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment