wagon/USAGE.md

# Wagon usage

## 1. User service

### 1.1. Frontend

The sample frontend shows a user's devices in a table like this:

> ```
> Host	               	SSL       	
> mypc.myuser.mynet    	cert / key	[DELETE]
> myphone.myuser.mynet 	cert / key	[DELETE]
> mylaptop.myuser.mynet	cert / key	[DELETE]
> ```

The first column is each host's domain name. The next column has links for users to download an SSL cert/key for that device. Finally there is a button to delete that host. (Every host has a DELETE button, but the backend will not let you delete the device you are connecting from)

Below the devices list is a self-explanitory place to add a device: 

> ### Add a peer
> 
> To add a new peer, type in a hostname and click add. The hostname must be 3-10 lowercase letters and numbers `/[a-z0-9]{3,10}/`. Keep it short for your own sake!
> 
> _______________ [ADD]
> 
> After clicking "Add", the new peer's config will appear below. Copy and paste it into your wireguard client and start the service. **This configuration will not be shown again!** If you lose the config, you will need to delete the peer and recreate it. 

As it says, there is no renaming of peers (yet), only deleting and re-adding. 

### 1.2. API

There are four endpoints that power the user dashboard. Since the IP source address is used for authentication, a token must be provided when making changes (adding/deleting peers) to prevent IP spoofing. That is, a hacker at `10.99.6.1` should not be able to change our user's `10.99.1.0/24` network. However, this hacker could spoof their source IP to send a "delete" request and not care about receiving a response. 

To prevent this, a token is generated on the server and sent to the user when requesting the `list`.  This token can only be recieved by the actual source address, so a user can make a `list` request, get the token, and use it to authenticate `add` and `delete` requests.  A spoofer would never recieve the token and not be able to send such changes.  Thus, to `add` or `delete` a peer, two requests must be made; one for the token, and one for the actual command. 

#### 1.2.1. List devices

- **REQUEST:** `GET /`
- **FILE:** `back/lib/dashboard/peer/list`
- **QUERYSTRING:** None
- **RESPONSE:** JSON with a token and array of user peers:
```json
{
  "token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
	"peers": [
		{
			"domain": "myhost1.myuser.mynet",
			"ipv4": "10.99.1.1",
			"ipv6": "fd69:1337:0:420:f4:99:1:1",
			"pubkey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX="
		},{
			"domain": "myhost2.myuser.mynet",
			"ipv4": "10.99.1.2",
			"ipv6": "fd69:1337:0:420:f4:99:1:2",
			"pubkey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX="
		}
	]
}
```

#### 1.2.2. Add device

- **REQUEST:** `POST /`
- **FILE:** `back/lib/dashboard/peer/add`
- **QUERYSTRING:** `?token=XXXX&name=mynewhostname`
	- `token`: The token provided in a `list devices` response
	- `name`: The new hostname for the peer
- **RESPONSE:** 
	- **202:** Success
	- **403:** Wrong token provided
	- **409:** Hostname already exists
	- **500:** Other server-side error

#### 1.2.3. Delete device

- **REQUEST:** `DELETE /`
- **FILE:** `back/lib/dashboard/peer/del`
- **QUERYSTRING:** `?token=XXXX&pubkey=XXXX`
	- `token`: The token provided in a `list devices` response
	- `pubkey`: The peer's wireguard public key
- **RESPONSE:** 
	- **202:** Success
	- **403:** Wrong token provided
	- **500:** Other server-side error

### 1.2.4. Get SSL certs

- **REQUEST:** `GET /ssl`
- **FILE:** `back/lib/dashboard/ssl`
- **QUERYSTRING:** `?host=myhostname&ext=crt`
	- `host`: get file for which host?
	- `ext`: `crt` for certs or `key` for keys
- **RESPONSE:** The requested SSL certificate or key file

## 2. Admin service

### 2.1. Dashboard



### 2.2 API

#### 2.2.1. List devices

TODO

#### 2.2.2. Add device

TODO

#### 2.2.3. Delete device

TODO

#### 2.2.4. List users

TODO

#### 2.2.5. Add user

TODO

#### 2.2.6. Delete user

TODO