From 2c17459d3367a579a03d9a759b9cb6aeaed10aa4 Mon Sep 17 00:00:00 2001
From: Hugo Thunnissen <hugo@hugot.nl>
Date: Sat, 23 Nov 2019 22:19:59 +0100
Subject: [PATCH] Improve README

---
 README.md | 91 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 91 insertions(+)

diff --git a/README.md b/README.md
index cbd2625..5a0033b 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,94 @@
 # Generic Mastodon Authenticator
 Implementing oauth is boring. This service will take care of that for
 you and your distributed mastodon app.
+
+## How does it work
+Your client connects to this server through a websocket connection.
+
+### 1. Request authentication
+Upon connection your client should send a message over the socket
+containing the following json object:
+
+```json
+{
+    "type": "auth",
+    "parameters": {
+        "host": "YOUR_MASTODON_INSTANCE_HOSTNAME"
+    }
+}
+```
+
+### 2. Validation
+If the hostname you provided is a valid hostname, your client can skip
+this step. If the hostname is incorrect, you will receive a message
+containing the following json object:
+
+```json
+{
+    "type": "invalid-host",
+    "parameters": {}
+}
+```
+
+You can then repeat step 1 until you have provided a valid hostname.
+
+### 3. User authentication
+If the hostname is valid, the server will accept the authentication
+request and provide your client with a request ID. The json you
+receive should look like this:
+
+```json
+{
+    "type": "set-id",
+    "arguments": {
+        "id": "THE REQUEST ID"
+    }
+}
+```
+
+You can then compose a URL to redirect/point the user to. The url
+should have the following format:
+http(s)://your-auth-server.tld/auth/{ID} .
+
+### 4. Request fulfillment
+When the user logs in successfully and authorizes your app, your
+client will receive one more json object with your access token. That
+object will look like this:
+
+```json
+{
+    "type": "fulfill",
+    "parameters": {
+        "token": "THE ACCESS TOKEN"
+    }
+}
+```
+    
+## Installation/Deployment
+This server uses an embedded database so you won't have to worry about
+setting one up. It also (as of right now) doesn't implement SSL, so it
+is recommended to run it behind a reverse proxy that has SSL enabled
+for your and your users' sake.
+
+The configuration is done through a yaml file, here is an example:
+
+```yaml
+# The name of your application. This will be visible to users when authenticating.
+app_name: example_app
+
+# Your server's hostname
+app_host: auth.example.com
+
+# http scheme your app is hosted on
+app_scheme: http
+
+# Storage location for database file (make sure it is an absolute path)
+db_path: /var/lib/generic-mastodon-authenticator/secrets.db
+
+# Your application's website
+website: https://example.com
+
+# Scopes your app will need (see https://docs.joinmastodon.org/api/permissions/)
+app_scopes:
+  - write:statuses
+```