# 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
```