backend-login/README.md

# backend-login

Beep backend handling login. Call `/init` and then `/verify` in sequence. `/login` is legacy to provide an easy source of tokens for testing, and will be removed someday™.

## Environment variables

Supply environment variables by either exporting them or editing ```.env```.

| ENV | Description | Default |
| ---- | ----------- | ------- |
| LISTEN | Host and port number to listen on | :8080 |
| SECRET | JWT secret | secret |

## API

| Contents |
| -------- |
| Init Auth |
| Verify Code |
| Create Token (temporary) |
| Register User |

---

### Init Auth

```
POST /init
```

Kick off SMS verification process.

#### Body

| Name | Type | Description |
| ---- | ---- | ----------- |
| phone_number | String | Verifying phone number in format `<country code><8 digits>`. |

#### Success (200 OK)

A nonce, to be used for `/verify` to add additional entropy.

#### Errors

| Code | Description |
| ---- | ----------- |
| 400 | Error parsing body/phone_number is not a valid phone number |
| 500 | Error generating nonce/Making request to Twilio SMS |

---

### Verify Code

```
POST /verify
```

Second half of the verification process, verifying the code and returning a JWT. If the user does not exist in the database, a blank one is created.

#### Body

| Name | Type | Description |
| ---- | ---- | ----------- |
| code | String | Verification code received by SMS. |
| nonce | String | Nonce returned by `/init`. |
| clientid | String | ID unique to device, e.g. MAC Address |

#### Success (200 OK)

JWT token.

```json
{
  "userid": "<userid>",
  "clientid": "<clientid>"
}
```

#### Errors

| Code | Description |
| ---- | ----------- |
| 400 | Error parsing body |
| 404 | Code with nonce supplied was not found |
| 500 | Error retrieving record from Redis/querying postgres/creating user ID/generating token |

---

### Create Token (temporary)

```
POST /login
```

Just a simple little endpoint to get a valid token without having to jump through the (expensive) hoops of SMS Authentication.

#### Body

| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| userid | String | User's ID. | ✓ |
| clientid | String | Device's ID. Must be unique to the device. I suggest something based on MAC address. | ✓ |

#### Success (200 OK)

JWT token.

#### Errors

| Code | Description |
| ---- | ----------- |
| 400 | Required fields in body were not supplied |
| 500 | Error creating the JWT |

---

### Register User

```
POST /register/:code/:nonce
```

Register a new user. Proxies `core`'s CreateUser endpoint, adding in a dummy token. Admittedly not the most secure implementation ever, but sue me it's 3AM now. Requires a code and nonce supplied from querying the `/init` endpoint.

#### Params

| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| code | String | OTP code SMS-ed to the user. Initiated with the `/init` endpoint. | ✓ |
| nonce | String | Nonce returned by the `/init` endpoint response. | ✓ | 

#### Body

| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| first_name | String | First name of the added user. | ✓ |
| last_name | String | Last name of the added user. | ✓ |
| phone_number | String | Phone number of the added user. Shouldn't be needed but makes life easier. | X |

#### Success Response (200 OK)

Created user object.

```json
{
  "id": "<id>",
  "first_name": "<first_name>",
  "last_name": "<last_name>",
  "phone_number": "<phone_number>"
}
```

#### Errors

| Code | Description |
| ---- | ----------- |
| 400 | Error parsing submitted body, or fields first_name or last_name have a length of 0 |
| 401 | Supplied OTP is invalid |
| 500 | Error occurred inserting entry into database/proxying |