# 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&type=cert`
	- `host`: get file for which host?
	- `type`: `cert` for certs or `key` for keys
- **RESPONSE:** The requested SSL certificate or key file

## 2. Admin service

### 2.1. Dashboard

There are four sections to the admin dashboard (then, at the bottom, a place where new configs are shown)

#### Add user

This is where you add a new user. You'll have to provide a hostname for their initial device. Adding a user like this will generate a wireguard configuration that you can send to the invited person over a secure channel. 

#### Delete user

Deletes a user and all their peers. Totally removes the user from the network and deletes all their data. 

#### Peer list

A (possibly long) list of all peers on the network, including servers (don't delete them!).  Here you can delete a single peer from any user. 

#### Add peer

This section lets you add a new peer for any existing user. 

### 2.2 API

The admin API has no authentication so it should be blocked to all except admin IP ranges. 

#### 2.2.1. List devices

- **REQUEST:** `GET /peer`
- **FILE:** `back/lib/admin/peer/list`
- **QUERYSTRING:** `?un=$username`
	- `un`: A username, optionally, to show only that user's peers
- **RESPONSE:** A token and array of peers in JSON
```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="
		}
	]
}

```

#### 2.2.2. Add device

- **REQUEST:** `POST /peer`
- **FILE:** `back/lib/admin/peer/add`
- **QUERYSTRING:** `?t=$token&host=$newhostname&user=$username&num=$usernumber`
	- `t`: The token from a GET request
	- `host`: The hostname chosen for the new peer
	- `user`: The user's username
	- `num`: The user's subnet number
- **RESPONSE:** 
	- `202`: Added
	- `400`: Invalid input
	- `403`: Bad token
	- `409`: Hostname already exists
	- `500`: Error

#### 2.2.3. Delete device

- **REQUEST:** `DELETE /peer`
- **FILE:** `back/lib/admin/peer/del`
- **QUERYSTRING:** `?t=$token&pubkey=$pubkey`
	- `t`: The token from a GET request
	- `pubkey`: Wireguard public key of the peer to remove
- **RESPONSE:** 
	- `202`: Deleted
	- `400`: Attempted to delete self
	- `403`: Bad token
	- `404`: Peer not found
	- `500`: Other server error

#### 2.2.4. Add user

- **REQUEST:** `POST /user`
- **FILE:** `back/lib/admin/user/add`
- **QUERYSTRING:** `?t=$token&host=$hostname&user=$username`
	- `t`: The token from a GET request
	- `host`: The hostname chosen for the new peer
	- `user`: The username chosen
- **RESPONSE:** 
	- `202`: Added
	- `400`: Invalid input
	- `403`: Bad token
	- `409`: Username already taken
	- `500`: Error

#### 2.2.5. Delete user

- **REQUEST:** `DELETE /user`
- **FILE:** `back/lib/admin/user/del`
- **QUERYSTRING:** `?t=$token&user=$username&un=$usernumber`
	- `t`: The token from a GET request
	- `user`: The username to delete
	- `un`: The user's subnet number
- **RESPONSE:** 
	- `202`: Deleted
	- `400`: Bad username or number
	- `403`: Bad token
	- `500`: Other server error