## 1. Project Overview & Quickstart (simple-login/app)

## File: README.md

[SimpleLogin](https://simplelogin.io) | Protect your online identity with email alias
---

<a href="https://chrome.google.com/webstore/detail/dphilobhebphkdjbpfohgikllaljmgbn">
    
</a>

<a href="https://addons.mozilla.org/firefox/addon/simplelogin/">

</a>

<a href="./LICENSE">

</a>

<a href="https://twitter.com/simplelogin">

</a>





---

Your email address is your **online identity**. When you use the same email address everywhere, you can be easily tracked.
More information on https://simplelogin.io

This README contains instructions on how to self host SimpleLogin.

Once you have your own SimpleLogin instance running, you can change the `API URL` in SimpleLogin's Chrome/Firefox extension, Android/iOS app to your server.

SimpleLogin roadmap is at https://github.com/simple-login/app/projects/1 and our forum at https://github.com/simple-login/app/discussions, feel free to submit new ideas or vote on features.

### Prerequisites

- a Linux server (either a VM or dedicated server). This doc shows the setup for Ubuntu 18.04 LTS but the steps could be adapted for other popular Linux distributions. As most of components run as Docker container and Docker can be a bit heavy, having at least 2 GB of RAM is recommended. The server needs to have the port 25 (email), 80, 443 (for the webapp), 22 (so you can ssh into it) open.

- a domain that you can config the DNS. It could be a sub-domain. In the rest of the doc, let's say it's `mydomain.com` for the email and `app.mydomain.com` for SimpleLogin webapp. Please make sure to replace these values by your domain name whenever they appear in the doc. A trick we use is to download this README file on your computer and replace all `mydomain.com` occurrences by your domain.

Except for the DNS setup that is usually done on your domain registrar interface, all the below steps are to be done on your server. The commands are to run with `bash` (or any bash-compatible shell like `zsh`) being the shell. If you use other shells like `fish`, please make sure to adapt the commands.

### Some utility packages

These packages are used to verify the setup. Install them by:

```bash
sudo apt update && sudo apt install -y dnsutils
```

Create a directory to store SimpleLogin data:

```bash
mkdir sl
mkdir sl/pgp # to store PGP key
mkdir sl/db # to store database
mkdir sl/upload # to store quarantine emails
```

### DKIM

From Wikipedia https://en.wikipedia.org/wiki/DomainKeys_Identified_Mail

> DomainKeys Identified Mail (DKIM) is an email authentication method designed to detect forged sender addresses in emails (email spoofing), a technique often used in phishing and email spam.

Setting up DKIM is highly recommended to reduce the chance your emails ending up in the recipient's Spam folder.

First you need to generate a private and public key for DKIM:

```bash
openssl genrsa -out dkim.key -traditional 1024
openssl rsa -in dkim.key -pubout -out dkim.pub.key
```

You will need the files `dkim.key` and `dkim.pub.key` for the next steps.

For email gurus, we have chosen 1024 key length instead of 2048 for DNS simplicity as some registrars don't play well with long TXT record.

### DNS

Please note that DNS changes could take up to 24 hours to propagate. In practice, it's a lot faster though (~1 minute or so in our test). In DNS setup, we usually use domain with a trailing dot (`.`) at the end to force using absolute domain.


#### MX record
Create a **MX record** that points `mydomain.com.` to `app.mydomain.com.` with priority 10.

To verify if the DNS works, the following command

```bash
dig @1.1.1.1 mydomain.com mx
```

should return:

```
mydomain.com.	3600	IN	MX	10 app.mydomain.com.
```

#### A record
An **A record** that points `app.mydomain.com.` to your server IP.
If you are using CloudFlare, we recommend to disable the "Proxy" option.
To verify, the following command

```bash
dig @1.1.1.1 app.mydomain.com a
```

should return your server IP.

#### DKIM
Set up DKIM by adding a TXT record for `dkim._domainkey.mydomain.com.` with the following value:

```
v=DKIM1; k=rsa; p=PUBLIC_KEY
```

with `PUBLIC_KEY` being your `dkim.pub.key` but
- remove the `-----BEGIN PUBLIC KEY-----` and `-----END PUBLIC KEY-----`
- join all the lines on a single line.

For example, if your `dkim.pub.key` is

```
-----BEGIN PUBLIC KEY-----
ab
cd
ef
gh
-----END PUBLIC KEY-----
```

then the `PUBLIC_KEY` would be `abcdefgh`.

You can get the `PUBLIC_KEY` by running this command:

```bash
sed "s/-----BEGIN PUBLIC KEY-----/v=DKIM1; k=rsa; p=/g" $(pwd)/dkim.pub.key | sed 's/-----END PUBLIC KEY-----//g' |tr -d '\n' | awk 1
```

To verify, the following command

```bash
dig @1.1.1.1 dkim._domainkey.mydomain.com txt
```

should return the above value.

#### SPF

From Wikipedia https://en.wikipedia.org/wiki/Sender_Policy_Framework

> Sender Policy Framework (SPF) is an email authentication method designed to detect forging sender addresses during the delivery of the email

Similar to DKIM, setting up SPF is highly recommended.
Add a TXT record for `mydomain.com.` with the value:

```
v=spf1 mx ~all
```

What it means is only your server can send email with `@mydomain.com` domain.
To verify, the following command

```bash
dig @1.1.1.1 mydomain.com txt
```

should return the above value.

#### DMARC

From Wikipedia https://en.wikipedia.org/wiki/DMARC

> It (DMARC) is designed to give email domain owners the ability to protect their domain from unauthorized use, commonly known as email spoofing

Setting up DMARC is also recommended.
Add a TXT record for `_dmarc.mydomain.com.` with the following value

```
v=DMARC1; p=quarantine; adkim=r; aspf=r
```

This is a `relaxed` DMARC policy. You can also use a more strict policy with `v=DMARC1; p=reject; adkim=s; aspf=s` value.

To verify, the following command

```bash
dig @1.1.1.1 _dmarc.mydomain.com txt
```

should return the set value.

For more information on DMARC, please consult https://tools.ietf.org/html/rfc7489

### Docker

Now the boring DNS stuffs are done, let's do something more fun!

If you don't already have Docker installed on your server, please follow the steps on [Docker CE for Ubuntu](https://docs.docker.com/v17.12/install/linux/docker-ce/ubuntu/) to install Docker.

You can also install Docker using the [docker-install](https://github.com/docker/docker-install) script which is

```bash
curl -fsSL https://get.docker.com | sh
```

### Prepare the Docker network

This Docker network will be used by the other Docker containers run in the next steps.
Later, we will setup Postfix to authorize this network.

```bash
sudo docker network create -d bridge \
    --subnet=10.0.0.0/24 \
    --gateway=10.0.0.1 \
    sl-network
```

### Postgres

This section creates a Postgres database using Docker.

If you already have a Postgres database in use, you can skip this section and just copy the database configuration (i.e. host, port, username, password, database name) to use in the next sections.

Run a Postgres Docker container as your Postgres database server. Make sure to replace `myuser` and `mypassword` with something more secret.

```bash
docker run -d \
    --name sl-db \
    -e POSTGRES_PASSWORD=mypassword \
    -e POSTGRES_USER=myuser \
    -e POSTGRES_DB=simplelogin \
    -p 127.0.0.1:5432:5432 \
    -v $(pwd)/sl/db:/var/lib/postgresql/data \
    --restart always \
    --network="sl-network" \
    postgres:12.1
```

To test whether the database operates correctly or not, run the following command:

```bash
docker exec -it sl-db psql -U myuser simplelogin
```

you should be logged in the postgres console. Type `exit` to exit postgres console.

### Postfix

Install `postfix` and `postfix-pgsql`. The latter is used to connect Postfix and the Postgres database in the next steps.

```bash
sudo apt-get install -y postfix postfix-pgsql -y
```

Choose "Internet Site" in Postfix installation window then keep using the proposed value as *System mail name* in the next window.




Replace `/etc/postfix/main.cf` with the following content. Make sure to replace `mydomain.com` by your domain.

```
/* Detailed source-code truncated for AI context efficiency. */
```

Check that the ssl certificates `/etc/ssl/certs/ssl-cert-snakeoil.pem` and `/etc/ssl/private/ssl-cert-snakeoil.key` exist. Depending on the linux distribution you are using they may or may not be present. If they are not, you will need to generate them with this command:

```bash
openssl req -x509 -nodes -days 3650 -newkey rsa:2048 -keyout /etc/ssl/private/ssl-cert-snakeoil.key -out /etc/ssl/certs/ssl-cert-snakeoil.pem
```

Create the `/etc/postfix/pgsql-relay-domains.cf` file with the following content.
Make sure that the database config is correctly set, replace `mydomain.com` with your domain, update 'myuser' and 'mypassword' with your postgres credentials.

```
# postgres config
hosts = localhost
user = myuser
password = mypassword
dbname = simplelogin

query = SELECT domain FROM custom_domain WHERE domain='%s' AND verified=true
    UNION SELECT '%s' WHERE '%s' = 'mydomain.com' LIMIT 1;
```

Create the `/etc/postfix/pgsql-transport-maps.cf` file with the following content.
Again, make sure that the database config is correctly set, replace `mydomain.com` with your domain, update 'myuser' and 'mypassword' with your postgres credentials.

```
# postgres config
hosts = localhost
user = myuser
password = mypassword
dbname = simplelogin

# forward to smtp:127.0.0.1:20381 for custom domain AND email domain
query = SELECT 'smtp:127.0.0.1:20381' FROM custom_domain WHERE domain = '%s' AND verified=true
    UNION SELECT 'smtp:127.0.0.1:20381' WHERE '%s' = 'mydomain.com' LIMIT 1;
```

Finally, restart Postfix

```bash
sudo systemctl restart postfix
```

### Run SimpleLogin Docker containers

To run SimpleLogin, you need a config file at `$(pwd)/simplelogin.env`. Below is an example that you can use right away, make sure to

- replace `mydomain.com` by your domain,
- set `FLASK_SECRET` to a secret string,
- update 'myuser' and 'mypassword' with your database credentials used in previous step.

All possible parameters can be found in [config example](example.env). Some are optional and are commented out by default.
Some have "dummy" values, fill them up if you want to enable these features (Paddle, AWS, etc).

```.env
# WebApp URL
URL=http://app.mydomain.com

# domain used to create alias
EMAIL_DOMAIN=mydomain.com

# transactional email is sent from this email address
SUPPORT_EMAIL=support@mydomain.com

# custom domain needs to point to these MX servers
EMAIL_SERVERS_WITH_PRIORITY=[(10, "app.mydomain.com.")]

# By default, new aliases must end with ".{random_word}". This is to avoid a person taking all "nice" aliases.
# this option doesn't make sense in self-hosted. Set this variable to disable this option.
DISABLE_ALIAS_SUFFIX=1

# the DKIM private key used to compute DKIM-Signature
DKIM_PRIVATE_KEY_PATH=/dkim.key

# DB Connection
DB_URI=postgresql://myuser:mypassword@sl-db:5432/simplelogin

FLASK_SECRET=put_something_secret_here

GNUPGHOME=/sl/pgp

LOCAL_FILE_UPLOAD=1

POSTFIX_SERVER=10.0.0.1
```


Before running the webapp, you need to prepare the database by running the migration:

```bash
docker run --rm \
    --name sl-migration \
    -v $(pwd)/sl:/sl \
    -v $(pwd)/sl/upload:/code/static/upload \
    -v $(pwd)/dkim.key:/dkim.key \
    -v $(pwd)/dkim.pub.key:/dkim.pub.key \
    -v $(pwd)/simplelogin.env:/code/.env \
    --network="sl-network" \
    simplelogin/app:3.4.0 flask db upgrade
```

This command could take a while to download the `simplelogin/app` docker image.

Init data

```bash
docker run --rm \
    --name sl-init \
    -v $(pwd)/sl:/sl \
    -v $(pwd)/simplelogin.env:/code/.env \
    -v $(pwd)/dkim.key:/dkim.key \
    -v $(pwd)/dkim.pub.key:/dkim.pub.key \
    --network="sl-network" \
    simplelogin/app:3.4.0 python init_app.py
```

Now, it's time to run the `webapp` container!

```bash
docker run -d \
    --name sl-app \
    -v $(pwd)/sl:/sl \
    -v $(pwd)/sl/upload:/code/static/upload \
    -v $(pwd)/simplelogin.env:/code/.env \
    -v $(pwd)/dkim.key:/dkim.key \
    -v $(pwd)/dkim.pub.key:/dkim.pub.key \
    -p 127.0.0.1:7777:7777 \
    --restart always \
    --network="sl-network" \
    simplelogin/app:3.4.0
```

Next run the `email handler`

```bash
docker run -d \
    --name sl-email \
    -v $(pwd)/sl:/sl \
    -v $(pwd)/sl/upload:/code/static/upload \
    -v $(pwd)/simplelogin.env:/code/.env \
    -v $(pwd)/dkim.key:/dkim.key \
    -v $(pwd)/dkim.pub.key:/dkim.pub.key \
    -p 127.0.0.1:20381:20381 \
    --restart always \
    --network="sl-network" \
    simplelogin/app:3.4.0 python email_handler.py
```

And finally the `job runner`

```bash
docker run -d \
    --name sl-job-runner \
    -v $(pwd)/sl:/sl \
    -v $(pwd)/sl/upload:/code/static/upload \
    -v $(pwd)/simplelogin.env:/code/.env \
    -v $(pwd)/dkim.key:/dkim.key \
    -v $(pwd)/dkim.pub.key:/dkim.pub.key \
    --restart always \
    --network="sl-network" \
    simplelogin/app:3.4.0 python job_runner.py
```

### Nginx

Install Nginx and make sure to replace `mydomain.com` by your domain

```bash
sudo apt-get install -y nginx
```

Then, create `/etc/nginx/sites-enabled/simplelogin` with the following lines:

```nginx
server {
    server_name  app.mydomain.com;

    location / {
        proxy_pass              http://localhost:7777;
    	proxy_set_header        Host $host;
    }
}
```

Note: If `/etc/nginx/sites-enabled/default` exists, delete it or certbot will fail due to the conflict. The `simplelogin` file should be the only file in `sites-enabled`.

Reload Nginx with the command below

```bash
sudo systemctl reload nginx
```

At this step, you should also setup the SSL for Nginx. [Here's our guide how](./docs/ssl.md).

### Enjoy!

If all the above steps are successful, open http://app.mydomain.com/ and create your first account!

By default, new accounts are not premium so don't have unlimited alias. To make your account premium,
please go to the database, table "users" and set "lifetime" column to "1" or "TRUE":

```
docker exec -it sl-db psql -U myuser simplelogin
UPDATE users SET lifetime = TRUE;
exit
```

Once you've created all your desired login accounts, add these lines to `/simplelogin.env` to disable further registrations:

```.env
DISABLE_REGISTRATION=1
DISABLE_ONBOARDING=true
```

Then restart the web app to apply: `docker restart sl-app`

### Donations Welcome

You don't have to pay anything to SimpleLogin to use all its features.
If you like the project, you can make a donation on our Open Collective page at https://opencollective.com/simplelogin

### Misc

The above self-hosting instructions correspond to a freshly Ubuntu server and doesn't cover all possible server configuration.
Below are pointers to different topics:

- [Troubleshooting](docs/troubleshooting.md)
- [Enable SSL](docs/ssl.md)
- [UFW - uncomplicated firewall](docs/ufw.md)
- [SES - Amazon Simple Email Service](docs/ses.md)
- [Upgrade existing SimpleLogin installation](docs/upgrade.md)
- [Enforce SPF](docs/enforce-spf.md)
- [Postfix TLS](docs/postfix-tls.md)
- [Postfix - DNSBL with Spamhaus](docs/spamhaus-dqs.md)

## ❤️ Contributors

Thanks go to these wonderful people:



| [**Dung Nguyen Van**](https://www.linkedin.com/in/vandungnguyen/) | [**Giuseppe Federico**](https://www.linkedin.com/in/giuseppe-f-83449ba4/) | [**Ninh Dinh**](https://github.com/NinhDinh) | [**Tung Nguyen V. N.**](https://github.com/ntung) | [**Son Nguyen Kim**](https://www.linkedin.com/in/nguyenkims/) | [**Raymond Nook**](https://github.com/developStorm) | [**Sibren Vasse**](https://github.com/SibrenVasse) | [**Sylvia van Os**](https://github.com/TheLastProject) |
| --- | --- | --- | --- | --- | --- | --- | --- |

---

## File: docs/api.md

## API

[Account endpoints](#account-endpoints)
- [POST /api/auth/login](#post-apiauthlogin): Authentication
- [POST /api/auth/mfa](#post-apiauthmfa): 2FA authentication
- [POST /api/auth/facebook](#post-apiauthfacebook) (deprecated)
- [POST /api/auth/google](#post-apiauthgoogle) (deprecated)
- [POST /api/auth/register](#post-apiauthregister): Register a new account.
- [POST /api/auth/activate](#post-apiauthactivate): Activate new account.
- [POST /api/auth/reactivate](##post-apiauthreactivate): Request a new activation code.
- [POST /api/auth/forgot_password](#post-apiauthforgot_password): Request reset password link.
- [GET /api/user_info](#get-apiuser_info): Get user's information.
- [PATCH /api/sudo](#patch-apisudo): Enable sudo mode.
- [DELETE /api/user](#delete-apiuser): Delete the current user.
- [GET /api/user/cookie_token](#get-apiusercookie_token): Get a one time use token to exchange it for a valid cookie
- [PATCH /api/user_info](#patch-apiuser_info): Update user's information.
- [POST /api/api_key](#post-apiapi_key): Create a new API key.
- [GET /api/stats](#get-apistats): Get user's stats.
- [GET /api/logout](#get-apilogout): Log out.

[Alias endpoints](#alias-endpoints)
- [GET /api/v5/alias/options](#get-apiv5aliasoptions): Get alias options. Used by create alias process.
- [POST /api/v3/alias/custom/new](#post-apiv3aliascustomnew): Create new alias.
- [POST /api/alias/random/new](#post-apialiasrandomnew): Random an alias.
- [GET /api/v2/aliases](#get-apiv2aliases): Get user's aliases.
- [GET /api/aliases/:alias_id](#get-apialiasesalias_id): Get alias information.
- [DELETE /api/aliases/:alias_id](#delete-apialiasesalias_id): Delete an alias.
- [POST /api/aliases/:alias_id/toggle](#post-apialiasesalias_idtoggle): Enable/disable an alias.
- [GET /api/aliases/:alias_id/activities](#get-apialiasesalias_idactivities): Get alias activities.
- [PATCH /api/aliases/:alias_id](#patch-apialiasesalias_id): Update alias information.
- [GET /api/aliases/:alias_id/contacts](#get-apialiasesalias_idcontacts): Get alias contacts.
- [POST /api/aliases/:alias_id/contacts](#post-apialiasesalias_idcontacts): Create a new contact for an alias.

[Mailbox endpoints](#mailbox-endpoints)
- [POST /api/mailboxes](#post-apimailboxes): Create a new mailbox.
- [DELETE /api/mailboxes/:mailbox_id](#delete-apimailboxesmailbox_id): Delete a mailbox.
- [PUT /api/mailboxes/:mailbox_id](#put-apimailboxesmailbox_id): Update a mailbox.

[Custom domain endpoints](#custom-domain-endpoints)
- [GET /api/custom_domains](#get-apicustom_domains): Get custom domains.
- [PATCH /api/custom_domains/:custom_domain_id](#patch-apicustom_domainscustom_domain_id): Update custom domain's information.
- [GET /api/custom_domains/:custom_domain_id/trash](#get-apicustom_domainscustom_domain_idtrash): Get deleted aliases of a custom domain.

[Contact endpoints](#contact-endpoints)
- [DELETE /api/contacts/:contact_id](#delete-apicontactscontact_id): Delete a contact.
- [POST /api/contacts/:contact_id/toggle](#post-apicontactscontact_idtoggle): Block/unblock a contact.

[Notification endpoints](#notification-endpoints)
- [GET /api/notifications](#get-apinotifications): Get notifications.
- [POST /api/notifications/:notification_id](#post-apinotificationsnotification_id): Mark as read a notification.

[Settings endpoints](#settings-endpoints)
- [GET /api/setting](#get-apisetting): Get user's settings.
- [PATCH /api/setting](#patch-apisetting): Update user's settings.
- [GET /api/v2/setting/domains](#get-apiv2settingdomains): Get domains that user can use to create random alias.

[Import and export endpoints](#import-and-export-endpoints)
- [GET /api/export/data](#get-apiexportdata): Export user's data.
- [GET /api/export/aliases](#get-apiexportaliases): Export aliases into a CSV.

[MISC endpoints](#misc-endpoints)
- [POST /api/apple/process_payment](#post-apiappleprocess_payment): Process Apple's receipt.

[Phone endpoints](#phone-endpoints)
- [GET /api/phone/reservations/:reservation_id](#get-apiphonereservationsreservation_id): Get messages received during a reservation.

---

SimpleLogin current API clients are Chrome/Firefox/Safari extension and mobile (iOS/Android) app. These clients rely
on `API Code` for authentication.

Once the `Api Code` is obtained, either via user entering it (in Browser extension case) or by logging in (in Mobile
case), the client includes the `api code` in `Authentication` header in almost all requests.

For some endpoints, the `hostname` should be passed in query string. `hostname` is the the URL hostname (
cf https://en.wikipedia.org/wiki/URL), for ex if URL is http://www.example.com/index.html then the hostname
is `www.example.com`. This information is important to know where an alias is used in order to suggest user the same
alias if they want to create on alias on the same website in the future.

If error, the API returns 4** with body containing the error message, for example:

```json
{
  "error": "request body cannot be empty"
}
```

The error message could be displayed to user as-is, for example for when user exceeds their alias quota. Some errors
should be fixed during development however: for example error like `request body cannot be empty` is there to catch
development error and should never be shown to user.

All following endpoint return `401` status code if the API Key is incorrect.

### Account endpoints

#### POST /api/auth/login

Input:

- email
- password
- device: device name. Used to create the API Key. Should be humanly readable so user can manage later on the "API Key"
  page.

Output:

- name: user name, could be an empty string
- email: user email
- mfa_enabled: boolean
- mfa_key: only useful when user enables MFA. In this case, user needs to enter their OTP token in order to login.
- api_key: if MFA is not enabled, the `api key` is returned right away.

The `api_key` is used in all subsequent requests. It's empty if MFA is enabled. If user hasn't enabled MFA, `mfa_key` is
empty.

Return 403 if user has enabled FIDO. The client can display a message to suggest user to use the `API Key` instead.

#### POST /api/auth/mfa

Input:

- mfa_token: OTP token that user enters
- mfa_key: MFA key obtained in previous auth request, e.g. /api/auth/login
- device: the device name, used to create an ApiKey associated with this device

Output:

- name: user name, could be an empty string
- api_key: if MFA is not enabled, the `api key` is returned right away.
- email: user email

The `api_key` is used in all subsequent requests. It's empty if MFA is enabled. If user hasn't enabled MFA, `mfa_key` is
empty.

#### POST /api/auth/facebook

Input:

- facebook_token: Facebook access token
- device: device name. Used to create the API Key. Should be humanly readable so user can manage later on the "API Key"
  page.

Output: Same output as for `/api/auth/login` endpoint

#### POST /api/auth/google

Input:

- google_token: Google access token
- device: device name. Used to create the API Key. Should be humanly readable so user can manage later on the "API Key"
  page.

Output: Same output as for `/api/auth/login` endpoint

#### POST /api/auth/register

Input:

- email
- password

Output: 200 means user is going to receive an email that contains an *activation code*. User needs to enter this code to
confirm their account -> next endpoint.

#### POST /api/auth/activate

Input:

- email
- code: the activation code

Output:

- 200: account is activated. User can login now
- 400: wrong email, code
- 410: wrong code too many times. User needs to ask for an reactivation -> next endpoint

#### POST /api/auth/reactivate

Input:

- email

Output:

- 200: user is going to receive an email that contains the activation code.

#### POST /api/auth/forgot_password

Input:

- email

Output: always return 200, even if email doesn't exist. User need to enter correctly their email.

#### GET /api/user_info

Given the API Key, return user name and whether user is premium. This endpoint could be used to validate the api key.

Input:

- `Authentication` header that contains the api key

Output: if api key is correct, return a json with user name and whether user is premium, for example:

```json
{
  "name": "John Wick",
  "is_premium": false,
  "email": "john@wick.com",
  "in_trial": true,
  "trial_end_timestamp": 1234567890,
  "profile_picture_url": "https://profile.png",
  "max_alias_free_plan": 5
}
```

`trial_end_timestamp`: Unix timestamp (integer) of when the trial ends, or `null` if no trial.

If api key is incorrect, return 401.

#### PATCH /api/user_info

Update user info

Input:

- profile_picture: the profile picture in base64. Setting to `null` remove the current profile picture.
- name

Output: same as GET /api/user_info

#### GET /api/stats

Given the API Key, return stats about the number of aliases, number of emails forwarded/replied/blocked

Input:

- `Authentication` header that contains the api key

Output: if api key is correct, return a json with the following fields:

```json
{"nb_alias": 1, "nb_block": 0, "nb_forward": 0, "nb_reply": 0}
```

If api key is incorrect, return 401.

#### PATCH /api/sudo

Enable sudo mode

Input:

- `Authentication` header that contains the api key
- password: User password to validate the user presence and enter sudo mode

```json
{
  "password": "yourpassword"
}
```

Output:

- 200 with ```{"ok": true}``` if sudo mode has been enabled.
- 403 with ```{"error": "Some error"}``` if there is an error.

#### DELETE /api/user

Delete the current user. It requires sudo mode.

Input:

- `Authentication` header that contains the api key

Output:

- 200 with ```{"ok": true}``` if account is scheduled to be deleted.
- 440 with ```{"error": "Need sudo"}``` if sudo mode is not enabled.
- 403 with ```{"error": "Some error"}``` if there is an error.


#### GET /api/user/cookie_token

Get a one time use cookie to exchange it for a valid cookie in the web app

Input:

- `Authentication` header that contains the api key

Output:

- 200 with ```{"token": "token value"}```
- 403 with ```{"error": "Some error"}``` if there is an error.

#### POST /api/api_key

Create a new API Key

Input:

- `Authentication` header that contains the api key
- Or the correct cookie is set, i.e. user is already logged in on the web
- device: device's name

Output

- 401 if user is not authenticated
- 201 with the `api_key`

```json
{
  "api_key": "long string"
}
```

#### GET /api/logout

Log user out

Input:

- `Authentication` header that contains the api key
- Or the correct cookie is set, i.e. user is already logged in on the web

Output:

- 401 if user is not authenticated
- 200 if success

### Alias endpoints

#### GET /api/v5/alias/options

User alias info and suggestion. Used by the first extension screen when user opens the extension.

Input:

- `Authentication` header that contains the api key
- (Optional but recommended) `hostname` passed in query string.

Output: a json with the following field:

- can_create: boolean. Whether user can create new alias
- suffixes: list of alias suffix that user can use.
  Each item is a dictionary with `suffix`, `signed-suffix`, `is_custom`, `is_premium` as keys.
  The `signed-suffix` is necessary to avoid request tampering.
- prefix_suggestion: string. Suggestion for the `alias prefix`. Usually this is the website name extracted
  from `hostname`. If no `hostname`, then the `prefix_suggestion` is empty.
- recommendation: optional field, dictionary. If an alias is already used for this website, the recommendation will be
  returned. There are 2 subfields in `recommendation`: `alias` which is the recommended alias and `hostname` is the
  website on which this alias is used before.

For ex:

```json
{
  "can_create": true,
  "prefix_suggestion": "test",
  "suffixes": [
    {
      "signed_suffix": ".cat@d1.test.X6_7OQ.0e9NbZHE_bQvuAapT6NdBml9m6Q",
      "suffix": ".cat@d1.test",
      "is_custom": true,
      "is_premium": false
    },
    {
      "signed_suffix": ".chat@d2.test.X6_7OQ.TTgCrfqPj7UmlY723YsDTHhkess",
      "suffix": ".chat@d2.test",
      "is_custom": false,
      "is_premium": false
    },
    {
      "signed_suffix": ".yeah@sl.lan.X6_7OQ.i8XL4xsMsn7dxDEWU8eF-Zap0qo",
      "suffix": ".yeah@sl.lan",
      "is_custom": true,
      "is_premium": false
    }
  ]
}
```

#### POST /api/v3/alias/custom/new

Create a new custom alias.

Input:

- `Authentication` header that contains the api key
- (Optional but recommended) `hostname` passed in query string
- Request Message Body in json (`Content-Type` is `application/json`)
    - alias_prefix: string. The first part of the alias that user can choose.
    - signed_suffix: should be one of the suffixes returned in the `GET /api/v5/alias/options` endpoint.
    - mailbox_ids: list of mailbox_id that "owns" this alias
    - (Optional) note: alias note
    - (Optional) name: alias name

Output:
If success, 201 with the new alias info. Use the same format as in GET /api/aliases/:alias_id

#### POST /api/alias/random/new

Create a new random alias.

Input:

- `Authentication` header that contains the api key
- (Optional but recommended) `hostname` passed in query string
- (Optional) mode: either `uuid` or `word` passed in query string. By default, use the user setting when creating new random alias.
- Request Message Body in json (`Content-Type` is `application/json`)
    - (Optional) note: alias note

Output:
If success, 201 with the new alias info. Use the same format as in GET /api/aliases/:alias_id

#### GET /api/v2/aliases

Get user aliases.

Input:

- `Authentication` header that contains the api key
- `page_id` in query. Used for the pagination. The endpoint returns maximum 20 aliases for each page. `page_id` starts
  at 0.
- (Optional) `pinned` in query. If set, only pinned aliases are returned.
- (Optional) `disabled` in query. If set, only disabled aliases are returned.
- (Optional) `enabled` in query. If set, only enabled aliases are returned.
  Please note `pinned`, `disabled`, `enabled` are exclusive, i.e. only one can be present.
- (Optional) query: included in request body. Some frameworks might prevent GET request having a non-empty body, in this
  case this endpoint also supports POST.

Output:
If success, 200 with the list of aliases. Each alias has the following fields:

- id
- email
- name
- enabled
- creation_timestamp
- note
- nb_block
- nb_forward
- nb_reply
- support_pgp: whether an alias can support PGP, i.e. when one of alias's mailboxes supports PGP.
- disable_pgp: whether the PGP is disabled on this alias. This field should only be used when `support_pgp` is true. By
  setting `disable_pgp=true`, a user can explicitly disable PGP on an alias even its mailboxes support PGP.
- mailbox: obsolete, should use `mailboxes` instead.
    - id
    - email
- mailboxes: list of mailbox, contains at least 1 mailbox.
    - id
    - email
- (nullable) latest_activity:
    - action: forward|reply|block|bounced
    - timestamp
    - contact:
        - email
        - name
        - reverse_alias
- pinned: whether an alias is pinned

Here's an example:

```json
{
  "aliases": [
    {
      "creation_date": "2020-04-06 17:57:14+00:00",
      "creation_timestamp": 1586195834,
      "email": "prefix1.cat@sl.lan",
      "name": "A Name",
      "enabled": true,
      "id": 3,
      "mailbox": {
        "email": "a@b.c",
        "id": 1
      },
      "mailboxes": [
        {
          "email": "m1@cd.ef",
          "id": 2
        },
        {
          "email": "john@wick.com",
          "id": 1
        }
      ],
      "latest_activity": {
        "action": "forward",
        "contact": {
          "email": "c1@example.com",
          "name": null,
          "reverse_alias": "\"c1 at example.com\" <re1@SL>"
        },
        "timestamp": 1586195834
      },
      "nb_block": 0,
      "nb_forward": 1,
      "nb_reply": 0,
      "note": null,
      "pinned": true
    }
  ]
}
```

#### GET /api/aliases/:alias_id

Get alias info

Input:

- `Authentication` header that contains the api key
- `alias_id` in url

Output:
Alias info, use the same format as in /api/v2/aliases. For example:

```json
{
  "creation_date": "2020-04-06 17:57:14+00:00",
  "creation_timestamp": 1586195834,
  "email": "prefix1.cat@sl.lan",
  "name": "A Name",
  "enabled": true,
  "id": 3,
  "mailbox": {
    "email": "a@b.c",
    "id": 1
  },
  "mailboxes": [
    {
      "email": "m1@cd.ef",
      "id": 2
    },
    {
      "email": "john@wick.com",
      "id": 1
    }
  ],
  "latest_activity": {
    "action": "forward",
    "contact": {
      "email": "c1@example.com",
      "name": null,
      "reverse_alias": "\"c1 at example.com\" <re1@SL>"
    },
    "timestamp": 1586195834
  },
  "nb_block": 0,
  "nb_forward": 1,
  "nb_reply": 0,
  "note": null,
  "pinned": true
}
```

#### DELETE /api/aliases/:alias_id

Delete an alias

Input:

- `Authentication` header that contains the api key
- `alias_id` in url.

Output:
If success, 200.

```json
{
  "deleted": true
}
```

#### POST /api/aliases/:alias_id/toggle

Enable/disable alias

Input:

- `Authentication` header that contains the api key
- `alias_id` in url.

Output:
If success, 200 along with the new alias status:

```json
{
  "enabled": false
}
```

#### GET /api/aliases/:alias_id/activities

Get activities for a given alias.

Input:

- `Authentication` header that contains the api key
- `alias_id`: the alias id, passed in url.
- `page_id` used in request query (`?page_id=0`). The endpoint returns maximum 20 aliases for each page. `page_id`
  starts at 0.

Output:
If success, 200 with the list of activities, for example:

```json
{
  "activities": [
    {
      "action": "reply",
      "from": "yes_meo_chat@sl.lan",
      "timestamp": 1580903760,
      "to": "marketing@example.com",
      "reverse_alias": "\"marketing at example.com\" <reply@a.b>",
      "reverse_alias_address": "reply@a.b"
    }
  ]
}
```

#### PATCH /api/aliases/:alias_id

Update alias info.

Input:

- `Authentication` header that contains the api key
- `alias_id` in url.
- (optional) `note` in request body
- (optional) `mailbox_id` in request body
- (optional) `name` in request body
- (optional) `mailbox_ids` in request body: array of mailbox_id
- (optional) `disable_pgp` in request body: boolean
- (optional) `pinned` in request body: boolean

Output:
If success, return 200

#### GET /api/aliases/:alias_id/contacts

Get contacts for a given alias.

Input:

- `Authentication` header that contains the api key
- `alias_id`: the alias id, passed in url.
- `page_id` used in request query (`?page_id=0`). The endpoint returns maximum 20 contacts for each page. `page_id`
  starts at 0.

Output:
If success, 200 with the list of contacts, for example:

```json
{
  "contacts": [
    {
      "id": 1,
      "contact": "marketing@example.com",
      "creation_date": "2020-02-21 11:35:00+00:00",
      "creation_timestamp": 1582284900,
      "last_email_sent_date": null,
      "last_email_sent_timestamp": null,
      "reverse_alias": "marketing at example.com <reply+bzvpazcdedcgcpztehxzgjgzmxskqa@sl.co>",
      "block_forward": false
    },
    {
      "id": 2,
      "contact": "newsletter@example.com",
      "creation_date": "2020-02-21 11:35:00+00:00",
      "creation_timestamp": 1582284900,
      "last_email_sent_date": "2020-02-21 11:35:00+00:00",
      "last_email_sent_timestamp": 1582284900,
      "reverse_alias": "newsletter at example.com <reply+bzvpazcdedcgcpztehxzgjgzmxskqa@sl.co>",
      "reverse_alias_address": "reply+bzvpazcdedcgcpztehxzgjgzmxskqa@sl.co",
      "block_forward": true
    }
  ]
}
```

Please note that last_email_sent_timestamp and last_email_sent_date can be null.

#### POST /api/aliases/:alias_id/contacts

Create a new contact for an alias.

Input:

- `Authentication` header that contains the api key
- `alias_id` in url.
- `contact` in request body

Output:
If success, return 201.

Return 200 and `existed=true` if contact is already added.

```json
{
  "id": 1,
  "contact": "First Last <first@example.com>",
  "creation_date": "2020-03-14 11:52:41+00:00",
  "creation_timestamp": 1584186761,
  "last_email_sent_date": null,
  "last_email_sent_timestamp": null,
  "reverse_alias": "First Last first@example.com <ra+qytyzjhrumrreuszrbjxqjlkh@sl.lan>",
  "reverse_alias_address": "reply+bzvpazcdedcgcpztehxzgjgzmxskqa@sl.co",
  "existed": false
}
```

It can return 403 with an error if the user cannot create reverse alias.

```json
{
  "error": "Please upgrade to create a reverse-alias"
}
```

### Mailbox endpoints

#### GET /api/v2/mailboxes

Get user's mailboxes, including unverified ones.

Input:

- `Authentication` header that contains the api key

Output:
List of mailboxes. Each mailbox has id, email, default, creation_timestamp field

```json
{
  "mailboxes": [
    {
      "email": "a@b.c",
      "id": 1,
      "default": true,
      "creation_timestamp": 1590918512,
      "nb_alias": 10,
      "verified": true
    },
    {
      "email": "m1@example.com",
      "id": 2,
      "default": false,
      "creation_timestamp": 1590918512,
      "nb_alias": 0,
      "verified": false
    }
  ]
}
```

## Mailbox endpoints
#### POST /api/mailboxes

Create a new mailbox

Input:

- `Authentication` header that contains the api key
- email: the new mailbox address

Output:

- 201 along with the following response if new mailbox is created successfully. User is going to receive a verification
  email.
    - id: integer
    - email: the mailbox email address
    - verified: boolean.
    - default: whether is the default mailbox. User cannot delete the default mailbox
- 400 with error message otherwise. The error message can be displayed to user.

#### DELETE /api/mailboxes/:mailbox_id

Delete a mailbox. User cannot delete the default mailbox

Input:

- `Authentication` header that contains the api key
- `mailbox_id`: in url
- (optional) `transfer_aliases_to`: in body as json. id of the new mailbox for the aliases. If omitted or set to -1, the aliases will be delete with the mailbox.

Output:

- 200 if deleted successfully
- 400 if error

#### PUT /api/mailboxes/:mailbox_id

Update a mailbox.

Input:

- `Authentication` header that contains the api key
- `mailbox_id`: in url
- (optional) `default`: boolean. Set a mailbox as default mailbox.
- (optional) `email`: email address. Change a mailbox email address.
- (optional) `cancel_email_change`: boolean. Cancel mailbox email change.

Output:

- 200 if updated successfully
- 400 if error

### Custom domain endpoints

#### GET /api/custom_domains

Return user's custom domains

Input:

- `Authentication` header that contains the api key

Output:
List of custom domains.

```json
[
  {
    "catch_all": false,
    "creation_date": "2021-03-10 21:36:08+00:00",
    "creation_timestamp": 1615412168,
    "domain_name": "test1.org",
    "id": 1,
    "is_verified": true,
    "mailboxes": [
      {
        "email": "a@b.c",
        "id": 1
      }
    ],
    "name": null,
    "nb_alias": 0,
    "random_prefix_generation": false
  },
  {
    "catch_all": false,
    "creation_date": "2021-03-10 21:36:08+00:00",
    "creation_timestamp": 1615412168,
    "domain_name": "test2.org",
    "id": 2,
    "is_verified": false,
    "mailboxes": [
      {
        "email": "a@b.c",
        "id": 1
      }
    ],
    "name": null,
    "nb_alias": 0,
    "random_prefix_generation": false
  }
]
```

#### PATCH /api/custom_domains/:custom_domain_id

Update custom domain's information

Input:

- `Authentication` header that contains the api key
- `custom_domain_id` in url.
- (optional) `catch_all`: boolean, in request body
- (optional) `random_prefix_generation`: boolean, in request body
- (optional) `name`: text, in request body
- (optional) `mailbox_ids`: array of mailbox id, in request body

Output:
If success, return 200 along with updated custom domain

#### GET /api/custom_domains/:custom_domain_id/trash

Get deleted alias for a custom domain

Input:

- `Authentication` header that contains the api key

Output:
List of deleted alias.

```json
{
  "aliases": [
    {
      "alias": "first@test1.org",
      "deletion_timestamp": 1605464595
    }
  ]
}
```

### Contact endpoints

#### DELETE /api/contacts/:contact_id

Delete a contact

Input:

- `Authentication` header that contains the api key
- `contact_id` in url.

Output:
If success, 200.

```json
{
  "deleted": true
}
```

#### POST /api/contacts/:contact_id/toggle

Block/unblock contact

Input:

- `Authentication` header that contains the api key
- `contact_id` in url.

Output:
If success, 200 along with the new alias status:

```json
{
  "block_forward": false
}
```

### Notification endpoints

#### GET /api/notifications

Get notifications

Input:

- `Authentication` in header: the api key
- page in url: the page number, starts at 0

Output:

- more: whether there's more notifications
- notifications: list of notification, each notification has:
    - id
    - message: the message in html
    - title: the message title
    - read: whether the user has read the notification
    - created_at: when the notification is created

For example

```json
{
  "more": false,
  "notifications": [
    {
      "created_at": "2 minutes ago",
      "id": 1,
      "message": "Hey!",
      "read": false
    }
  ]
}
```

#### POST /api/notifications/:notification_id

Mark a notification as read

Input:

- `Authentication` in header: the api key
- notification_id in url: the page number, starts at 0

Output:
200 if success

### Settings endpoints

#### GET /api/setting

Return user setting.

```json
{
  "alias_generator": "word",
  "notification": true,
  "random_alias_default_domain": "sl.lan",
  "sender_format": "AT",
  "random_alias_suffix": "random_string"
}
```

#### PATCH /api/setting

Update user setting. All input fields are optional.

Input:

- alias_generator (string): `uuid` or `word`
- notification (boolean): `true` or `false`
- random_alias_default_domain (string): one of the domains returned by `GET /api/setting/domains`
- sender_format (string): possible values are `AT`, `A`, `NAME_ONLY`, `AT_ONLY`, `NO_NAME`
- random_alias_suffix (string): possible values are `word`, `random_string`

Output: same as `GET /api/setting`

#### GET /api/v2/setting/domains

Return domains that user can use to create random alias

`is_custom` is true if this is a user's domain, otherwise false.

```json
[
  {
    "domain": "d1.test",
    "is_custom": false
  },
  {
    "domain": "d2.test",
    "is_custom": false
  },
  {
    "domain": "sl.lan",
    "is_custom": false
  },
  {
    "domain": "ab.cd",
    "is_custom": true
  }
]
```

### Import and export endpoints

#### GET /api/export/data

Export user data

Input:

- `Authentication` in header: the api key

Output:
Alias, custom domain and app info

#### GET /api/export/aliases

Export user aliases in an importable CSV format

Input:

- `Authentication` in header: the api key

Output:
A CSV file with alias information that can be imported in the settings screen

### Misc endpoints

#### POST /api/apple/process_payment

Process payment receipt

Input:

- `Authentication` in header: the api key
- `receipt_data` in body: the receipt_data base64Encoded returned by StoreKit, i.e. `rawReceiptData.base64EncodedString`
- (optional) `is_macapp` in body: if this field is present, the request is sent from the MacApp (Safari Extension) and
  not iOS app.

Output:
200 if user is upgraded successfully 4** if any error.

### Phone endpoints

#### GET /api/phone/reservations/:reservation_id

Get messages received during a reservation.

Input:

- `Authentication` in header: the api key
- `reservation_id`

Output:
List of messages for this reservation and whether the reservation is ended.

```json
{
  "ended": false,
  "messages": [
    {
      "body": "body",
      "created_at": "just now",
      "from_number": "from_number",
      "id": 7
    }
  ]
}
```

---

## File: docs/build-image.md

To build a multi-architecture image, you need to use `buildx`.

Here's the command to build and push the images from a Mac M1:

1) First create a new buildx environment (or context). This is only necessary for the first time.

```bash
docker buildx create --use
```

2) Build and push the image. Replace `simplelogin/name:tag` by the correct docker image name and tag.

```bash
docker buildx build --platform linux/amd64,linux/arm64 --push -t simplelogin/name:tag
```

---

## File: docs/code-structure.md

# TODO

`local_data/`: contain files used only locally. In deployment, these files should be replaced.
    - jwtRS256.key: generated using

```bash
ssh-keygen -t rsa -b 4096 -m PEM -f jwtRS256.key
# Don't add passphrase
openssl rsa -in jwtRS256.key -pubout -outform PEM -out jwtRS256.key.pub
```

---

## File: docs/enforce-spf.md

Some email services like Gmail, Proton Mail, etc don't have a strict SPF record (`-all`) to support the "classic" email forwarding
that is usually used for group mailing list. In this scenario, an email is sent to a group is forwarded as-is,
breaking therefore the SPF.

A malicious hacker could use this security fail to impersonate your alias via the reverse-alias. This rarely happens
as the reverse-alias is generated randomly and is unique for each sender.

However if you want to prevent this kind of attack, you can enforce the SPF policy even if your mailbox uses a "soft" policy.

1) Install `postfix-pcre`

```bash
apt install -y postfix-pcre
```

2) Add `/etc/postfix/body_checks.pcre` file with the following content

```
/^X-SimpleLogin-Client-IP:/    IGNORE
```

3) Add `/etc/postfix/client_headers.pcre` with the following content

```
/^([0-9a-f:.]+)$/ prepend X-SimpleLogin-Client-IP: $1
```

4) Add the following lines to your Postfix config file at `/etc/postfix/main.cf`

```
body_checks = pcre:/etc/postfix/body_checks.pcre
smtpd_client_restrictions = pcre:/etc/postfix/client_headers.pcre
```

5) Enable `ENFORCE_SPF` in your SimpleLogin config file

```
ENFORCE_SPF=true
```

6) Restart Postfix

```bash
systemctl restart postfix
```

7) Restart SimpleLogin mail handler

```bash
sudo docker restart sl-email
```

---

## File: docs/gmail-relay.md

# Using Gmail as SMTP relay to send email from SimpleLogin

###### port 25 blocked by ISP...?

> you can use postfix with a Gmail SMTP relay... So Postfix will send on port 587.

## How to:

- create a Gmail account
- set MFA
- create an app password

- update firewall's rules for port 587

- update Postfix conf:

=> nano /etc/postfix/master.cf
```
...
# ==========================================================================
# service type  private unpriv  chroot  wakeup  maxproc command + args
#               (yes)   (yes)   (no)    (never) (100)
# ==========================================================================
smtp      inet  n       -       y       -       -       smtpd
#smtp      inet  n       -       y       -       1       postscreen
#smtpd     pass  -       -       y       -       -       smtpd
#dnsblog   unix  -       -       y       -       0       dnsblog
#tlsproxy  unix  -       -       y       -       0       tlsproxy
submission inet n       -       y       -       -       smtpd
  -o syslog_name=postfix/submission
  -o smtpd_tls_security_level=encrypt
  -o smtpd_sasl_auth_enable=yes
  -o smtpd_tls_auth_only=yes
#  -o smtpd_reject_unlisted_recipient=no
#  -o smtpd_client_restrictions=$mua_client_restrictions
#  -o smtpd_helo_restrictions=$mua_helo_restrictions
...
```
=> nano /etc/postfix/sasl_passwd
```
[smtp.gmail.com]:587 email_created@gmail.com:app_password_created
```
=> postmap /etc/postfix/sasl_passwd

=> chmod 600 /etc/postfix/sasl_passwd

=> nano /etc/postfix/main.cf
```
/* Detailed source-code truncated for AI context efficiency. */
```
>cat /etc/hosts
>
>127.0.0.1       localhost.localdomain   localhost

- restart Postfix:

=> systemctl reload postfix

=> service postfix restart

- update SimpleLogin conf:

=> nano /simplelogin.env
```
# WebApp URL
URL=http://app.mydomain.com

# domain used to create alias
EMAIL_DOMAIN=mydomaine.com

# transactional email is sent from this email address
SUPPORT_EMAIL=support@mydomain.com

# custom domain needs to point to these MX servers
EMAIL_SERVERS_WITH_PRIORITY=[(10, "app.mydomain.com.")]

# By default, new aliases must end with ".{random_word}". This is to avoid a person taking all "nice" aliases.
# this option doesn't make sense in self-hosted. Set this variable to disable this option.
DISABLE_ALIAS_SUFFIX=1

# the DKIM private key used to compute DKIM-Signature
DKIM_PRIVATE_KEY_PATH=/dkim.key

# DB Connection
DB_URI=postgresql://mysqluser:mysqlpassword@sl-db:5432/simplelogin

FLASK_SECRET=SomeThing_Secret

GNUPGHOME=/sl/pgp

LOCAL_FILE_UPLOAD=1

# Postfix 587 TLS
POSTFIX_PORT=587

POSTFIX_SUBMISSION_TLS=true

# Enforce SPF
ENFORCE_SPF=true

```
- restart SL-Mail:

=> docker restart sl-email

=> reboot

> for debug:
>
> view system logs => tail -f /var/log/syslog
>
> view postfix logs => tail -f /var/log/mail.log
>
> view postfix queue => mailq
>
> delete postfix queue => postsuper -d ALL

;-)

---

## File: docs/oauth.md

## OAuth

SL currently supports code and implicit flow.

#### Code flow

To trigger the code flow locally, you can go to the [following url](http://localhost:7777/oauth/authorize?client_id=client-id&state=123456&response_type=code&redirect_uri=http%3A%2F%2Flocalhost%3A7000%2Fcallback&state=random_string) after running `python server.py`:


You should see the authorization page where user is asked for permission to share their data. Once user approves, user is redirected to this url with an `authorization code`: `http://localhost:7000/callback?state=123456&code=the_code`

Next, exchange the code to get the token with `{code}` replaced by the code obtained in previous step. The `http` tool used here is [httpie](https://httpie.org)

```
http -f -a client-id:client-secret http://localhost:7777/oauth/token grant_type=authorization_code code={code}
```

This should return an `access token` that allows to get user info via the following command. Again, `http` is used.

```
http http://localhost:7777/oauth/user_info 'Authorization:Bearer {token}'
```

#### Implicit flow

Similar to code flow, except for the the `access token` which we we get back with the redirection.
For implicit flow, you can use [this url](http://localhost:7777/oauth/authorize?client_id=client-id&state=123456&response_type=token&redirect_uri=http%3A%2F%2Flocalhost%3A7000%2Fcallback&state=random_string)

#### OpenID and OAuth2 response_type & scope

According to the sharing web blog titled [Diagrams of All The OpenID Connect Flows](https://medium.com/@darutk/diagrams-of-all-the-openid-connect-flows-6968e3990660), we should pay attention to:

- `response_type` can be either `code, token, id_token`  or any combination of those attributes.
- `scope` might contain `openid`

Below are the potential combinations that are taken into account in SL until now:

```
response_type=code
    scope:
	    with `openid` in scope, return `id_token` at /token: OK
	    without: OK

response_type=token
    scope:
	    with and without `openid`, nothing to do: OK

response_type=id_token
    return `id_token` in /authorization endpoint

response_type=id_token token
    return `id_token` in addition to `access_token` in /authorization endpoint

response_type=id_token code
    return `id_token` in addition to `authorization_code` in /authorization endpoint

```

---

## File: docs/postfix-tls.md

In case your Postfix server is on another server, it's recommended to enable TLS on Postfix submission to
secure the connection between SimpleLogin email handler and Postfix.

This can be enabled by adding those lines at the end of `/etc/postfix/master.cf`

```
submission inet n       -       y       -       -       smtpd
  -o syslog_name=postfix/submission
  -o smtpd_tls_security_level=encrypt
  -o smtpd_sasl_auth_enable=yes
  -o smtpd_tls_auth_only=yes
```

Make sure to set the `POSTFIX_SUBMISSION_TLS` variable to `true` in the SimpleLogin `simplelogin.env` file.

---

## File: docs/ses.md

Contribution from https://github.com/havedill/

## Integrating with Amazon SES

If you're self hosting, here is the method I used to route emails through Amazon's SES service.

For me, when hosting on AWS the public IP is widely blacklisted for abuse. If you have an SES account, you are whitelisted, use TLS, and amazon creates the DKIM records.

First, I modify the postfix inet protocols to only route via IPv4: in `/etc/postfix/main.cf`, change `inet_protocols = ipv4`

### Amazon Simple Email Service Console:

First, verify your domain with SES, and check off "Generate DKIM Records".



I use Route53, so pressing the Use Route53 button will automatically generate my DNS values. If you do not use Route53, you will have to create them on your DNS provider.

If you do choose route53, this is what generating the record sets looks like


Now, in SES we need to generate SMTP Credentials to use. Go to the SMTP settings tab, and create credentails. Also note your server name, port, etc.



Now on your server, run the following (Updating the SMTP DNS address to match what you see in the SMTP settings tab of SES)
```
sudo postconf -e "relayhost = [email-smtp.us-east-1.amazonaws.com]:587" \
"smtp_sasl_auth_enable = yes" \
"smtp_sasl_security_options = noanonymous" \
"smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd" \
"smtp_use_tls = yes" \
"smtp_tls_security_level = may" \
"smtp_tls_note_starttls_offer = yes"
```

Now let's create `/etc/postfix/sasl_passwd` and inside put your SMTP Setting values;
`[email-smtp.us-east-1.amazonaws.com]:587 SMTPUSERNAME:SMTPPASSWORD`

Create a hashmap with `sudo postmap hash:/etc/postfix/sasl_passwd`

Secure the files (optional but recommended)
```
sudo chown root:root /etc/postfix/sasl_passwd /etc/postfix/sasl_passwd.db
sudo chmod 0600 /etc/postfix/sasl_passwd /etc/postfix/sasl_passwd.db
```

For Ubuntu, we point postfix to the CA Certs;

```bash
sudo postconf -e 'smtp_tls_CAfile = /etc/ssl/certs/ca-certificates.crt'
```

Also make sure that Postfix is able to authenticate successfully by installing the SASL package:

```bash
sudo apt install libsasl2-modules
```

Then restart postfix

```bash
sudo systemctl restart postfix
```

and you should see the mail in `/var/log/mail.log` and in your alias emails routed through Amazons servers!

---

## File: docs/ssl.md

# SSL, HTTPS, HSTS and additional security measures

It's highly recommended to enable SSL/TLS on your server, both for the web app and email server.

## Using Certbot to get a certificate

This doc will use https://letsencrypt.org to get a free SSL certificate for app.mydomain.com that's used by both Postfix and Nginx. Let's Encrypt provides Certbot, a tool to obtain and renew SSL certificates.

To install Certbot, please follow instructions on https://certbot.eff.org

Then obtain a certificate for Nginx, use the following command. You'd need to provide an email so Let's Encrypt can send you notifications when your domain is about to expire.

```bash
sudo certbot --nginx
```

After this step, you should see some "managed by Certbot" lines in `/etc/nginx/sites-enabled/simplelogin`

### Securing Postfix

Now let's use the new certificate for our Postfix.

Replace these lines in /etc/postfix/main.cf

```
smtpd_tls_cert_file=/etc/ssl/certs/ssl-cert-snakeoil.pem
smtpd_tls_key_file=/etc/ssl/private/ssl-cert-snakeoil.key
```

with

```
smtpd_tls_cert_file = /etc/letsencrypt/live/app.mydomain.com/fullchain.pem
smtpd_tls_key_file = /etc/letsencrypt/live/app.mydomain.com/privkey.pem
```

Make sure to replace app.mydomain.com with your own domain.

### Updating `simplelogin.env`

Make sure to change the `URL` in `simplelogin.env` to `https://app.mydomain.com`, otherwise not all page assets will load securely, and some functionality (e.g. Webauthn) will break.
You will need to reload the docker containers for this to take effect.

## HTTP Strict Transport Security (HSTS)

HSTS is an extra step you can take to protect your web app from certain man-in-the-middle attacks. It does this by specifying an amount of time (usually a really long one) for which you should only accept HTTPS connections, not HTTP ones. Because of this **you should only enable HSTS once you know HTTPS is working correctly**, as otherwise you may find your browser blocking you from accessing your own web app.

To enable HSTS, add the following line to the `server` block of the Nginx configuration file:

```
add_header Strict-Transport-Security "max-age: 31536000; includeSubDomains" always;
```

(The `max-age` is the time in seconds to not permit a HTTP connection, in this case it's one year.)

Now, reload Nginx:

```bash
sudo systemctl reload nginx
```

## Additional security measures

For additional security, we recommend you take some extra steps.

### Enable Certificate Authority Authorization (CAA)

[Certificate Authority Authorization](https://letsencrypt.org/docs/caa/) is a step you can take to restrict the list of certificate authorities that are allowed to issue certificates for your domains.

Use [SSLMate’s CAA Record Generator](https://sslmate.com/caa/) to create a **CAA record** with the following configuration:

- `flags`: `0`
- `tag`: `issue`
- `value`: `"letsencrypt.org"`

To verify if the DNS works, the following command

```bash
dig @1.1.1.1 mydomain.com caa
```

should return:

```
mydomain.com.	3600	IN	CAA	0 issue "letsencrypt.org"
```

### SMTP MTA Strict Transport Security (MTA-STS)

[MTA-STS](https://datatracker.ietf.org/doc/html/rfc8461) is an extra step you can take to broadcast the ability of your instance to receive and, optionally enforce, TSL-secure SMTP connections to protect email traffic.

Enabling MTA-STS requires you serve a specific file from subdomain `mta-sts.domain.com` on a well-known route.

Create a text file `/var/www/.well-known/mta-sts.txt` with the content:

```txt
version: STSv1
mode: testing
mx: app.mydomain.com
max_age: 86400
```

It is recommended to start with `mode: testing` for starters to get time to review failure reports. Add as many `mx:` domain entries as you have matching **MX records** in your DNS configuration.

Create a **TXT record** for `_mta-sts.mydomain.com.` with the following value:

```txt
v=STSv1; id=UNIX_TIMESTAMP
```

With `UNIX_TIMESTAMP` being the current date/time.

Use the following command to generate the record:

```bash
echo "v=STSv1; id=$(date +%s)"
```

To verify if the DNS works, the following command

```bash
dig @1.1.1.1 _mta-sts.mydomain.com txt
```

should return a result similar to this one:

```
_mta-sts.mydomain.com.	3600	IN	TXT	"v=STSv1; id=1689416399"
```

Create an additional Nginx configuration in `/etc/nginx/sites-enabled/mta-sts` with the following content:

```
server {
	server_name mta-sts.mydomain.com;
	root /var/www;
	listen 80;

	location ^~ /.well-known {}
}
```

Restart Nginx with the following command:

```sh
sudo service nginx restart
```

A correct configuration of MTA-STS, however, requires that the certificate used to host the `mta-sts` subdomain matches that of the subdomain referred to by the **MX record** from the DNS. In other words, both `mta-sts.mydomain.com` and `app.mydomain.com` must share the same certificate.

The easiest way to do this is to _expand_ the certificate associated with `app.mydomain.com` to also support the `mta-sts` subdomain using the following command:

```sh
certbot --expand --nginx -d app.mydomain.com,mta-sts.mydomain.com
```

## SMTP TLS Reporting

[TLSRPT](https://datatracker.ietf.org/doc/html/rfc8460) is used by SMTP systems to report failures in establishing TLS-secure sessions as broadcast by the MTA-STS configuration.

Configuring MTA-STS in `mode: testing` as shown in the previous section gives you time to review failures from some SMTP senders.

Create a **TXT record** for `_smtp._tls.mydomain.com.` with the following value:

```txt
v=TSLRPTv1; rua=mailto:YOUR_EMAIL
```

The TLSRPT configuration at the DNS level allows SMTP senders that fail to initiate TLS-secure sessions to send reports to a particular email address.  We suggest creating a `tls-reports` alias in SimpleLogin for this purpose.

To verify if the DNS works, the following command

```bash
dig @1.1.1.1 _smtp._tls.mydomain.com txt
```

should return a result similar to this one:

```
_smtp._tls.mydomain.com.	3600	IN	TXT	"v=TSLRPTv1; rua=mailto:tls-reports@mydomain.com"
```

## 2. Official Technical Reference & Guides (simple-login/website)

SimpleLogin - privacy-first email alias and Single Sign-On (SSO) Identity Provider
---

https://simplelogin.io

This repo contains the code behind the main website at https://www.simplelogin.io

It's developed using https://gohugo.io, a static site generator.

To run it locally, please install `hugo` first. This repo uses v0.92.1.

**Install Hugo on macOS (Apple Silicon):**

```bash
mkdir -p ~/.local/bin
curl -L https://github.com/gohugoio/hugo/releases/download/v0.92.1/hugo_extended_0.92.1_macOS-ARM64.tar.gz -o /tmp/hugo.tar.gz
tar -xzf /tmp/hugo.tar.gz -C /tmp hugo
mv /tmp/hugo ~/.local/bin/hugo
```

Make sure `~/.local/bin` is in your PATH (add to `~/.zshrc` if needed):

```bash
export PATH="$HOME/.local/bin:$PATH"
```

Then run the following command:

```bash
hugo server
```

The website is now available on http://localhost:1313/