diff --git a/README.md b/README.md index 52383326..3d2a9707 100644 --- a/README.md +++ b/README.md @@ -77,6 +77,10 @@ the following section will show a step-by-step guide on how to get your own emai [3. Contributing Guide](#contributing) +[4. API](#api) + +[5. OAuth2/OpenID Connect](#oauth) + ## General Architecture @@ -615,7 +619,49 @@ then open http://localhost:7777, you should be able to login with the following john@wick.com / password ``` -### API +### Database migration + +The database migration is handled by `alembic` + +Whenever the model changes, a new migration has to be created. + +If you have Docker installed, you can create the migration by the following script: + +```bash +sh new_migration.sh +``` + +Make sure to review the migration script before committing it. +Sometimes (very rarely though), the automatically generated script can be incorrect. + +We cannot use the local database to generate migration script as the local database doesn't use migration. +It is created via `db.create_all()` (cf `fake_data()` method). This is convenient for development and +unit tests as we don't have to wait for the migration. + +### Code structure + +The repo consists of the three following entry points: + +- wsgi.py and server.py: the webapp. +- email_handler.py: the email handler. +- cron.py: the cronjob. + +Here are the small sum-ups of the directory structures and their roles: + +- app/: main Flask app. It is structured into different packages representing different features like oauth, api, dashboard, etc. +- local_data/: contains files to facilitate the local development. They are replaced during the deployment. +- migrations/: generated by flask-migrate. Edit these files will be only edited when you spot (very rare) errors on the database migration files. +- static/: files available at `/static` url. +- templates/: contains both html and email templates. +- tests/: tests. We don't really distinguish unit, functional or integration test. A test is simply here to make sure a feature works correctly. + +The code is formatted using https://github.com/psf/black, to format the code, simply run + +``` +black . +``` + +## API SimpleLogin current API clients are Chrome/Firefox/Safari extension and mobile (iOS/Android) app. These clients rely on `API Code` for authentication. @@ -638,6 +684,90 @@ Some errors should be fixed during development however: for example error like ` All following endpoint return `401` status code if the API Key is incorrect. +### Authentication 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 +- 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. + +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. @@ -659,6 +789,7 @@ Output: if api key is correct, return a json with user name and whether user is If api key is incorrect, return 401. +### Alias endpoints #### GET /api/v4/alias/options @@ -751,115 +882,6 @@ If success, 201 with the new alias, for example } ``` -#### 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 -- 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. - -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/mailboxes - -Get user verified mailboxes. - -Input: -- `Authentication` header that contains the api key - -Output: -List of mailboxes. Each mailbox has id, email field. - -```json -{ - "mailboxes": [ - { - "email": "a@b.c", - "id": 1 - }, - { - "email": "m1@example.com", - "id": 2 - } - ] -} -``` - #### GET /api/v2/aliases Get user aliases. @@ -1087,7 +1109,6 @@ If success, 200 with the list of contacts, for example: 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. @@ -1113,6 +1134,35 @@ Return 409 if contact is already added. } ``` +### Mailbox endpoints + +#### GET /api/mailboxes + +Get user verified mailboxes. + +Input: +- `Authentication` header that contains the api key + +Output: +List of mailboxes. Each mailbox has id, email field. + +```json +{ + "mailboxes": [ + { + "email": "a@b.c", + "id": 1 + }, + { + "email": "m1@example.com", + "id": 2 + } + ] +} +``` + +### Contact endpoints + #### DELETE /api/contacts/:contact_id Delete a contact @@ -1131,6 +1181,7 @@ If success, 200. } ``` +### Misc endpoints #### POST /api/apple/process_payment Process payment receipt @@ -1144,49 +1195,8 @@ Output: 200 if user is upgraded successfully 4** if any error. -### Database migration -The database migration is handled by `alembic` - -Whenever the model changes, a new migration has to be created. - -If you have Docker installed, you can create the migration by the following script: - -```bash -sh new_migration.sh -``` - -Make sure to review the migration script before committing it. -Sometimes (very rarely though), the automatically generated script can be incorrect. - -We cannot use the local database to generate migration script as the local database doesn't use migration. -It is created via `db.create_all()` (cf `fake_data()` method). This is convenient for development and -unit tests as we don't have to wait for the migration. - -### Code structure - -The repo consists of the three following entry points: - -- wsgi.py and server.py: the webapp. -- email_handler.py: the email handler. -- cron.py: the cronjob. - -Here are the small sum-ups of the directory structures and their roles: - -- app/: main Flask app. It is structured into different packages representing different features like oauth, api, dashboard, etc. -- local_data/: contains files to facilitate the local development. They are replaced during the deployment. -- migrations/: generated by flask-migrate. Edit these files will be only edited when you spot (very rare) errors on the database migration files. -- static/: files available at `/static` url. -- templates/: contains both html and email templates. -- tests/: tests. We don't really distinguish unit, functional or integration test. A test is simply here to make sure a feature works correctly. - -The code is formatted using https://github.com/psf/black, to format the code, simply run - -``` -black . -``` - -### OAuth flow +## OAuth SL currently supports code and implicit flow. diff --git a/app/alias_utils.py b/app/alias_utils.py index 5111da11..b3087da7 100644 --- a/app/alias_utils.py +++ b/app/alias_utils.py @@ -16,6 +16,7 @@ from app.models import ( Directory, User, DeletedAlias, + DomainDeletedAlias, ) @@ -130,15 +131,27 @@ def try_auto_create_catch_all_domain(address: str) -> Optional[Alias]: def delete_alias(alias: Alias, user: User): - email = alias.email Alias.delete(alias.id) db.session.commit() - # try to save deleted alias - try: - DeletedAlias.create(email=email) - db.session.commit() - # this can happen when a previously deleted alias is re-created via catch-all or directory feature - except IntegrityError: - LOG.error("alias %s has been added before to DeletedAlias", email) - db.session.rollback() + # save deleted alias to either global or domain trash + if alias.custom_domain_id: + try: + DomainDeletedAlias.create( + user_id=user.id, email=alias.email, domain_id=alias.custom_domain_id + ) + db.session.commit() + except IntegrityError: + LOG.error( + "alias %s domain %s has been added before to DeletedAlias", + alias.email, + alias.custom_domain_id, + ) + db.session.rollback() + else: + try: + DeletedAlias.create(email=alias.email) + db.session.commit() + except IntegrityError: + LOG.error("alias %s has been added before to DeletedAlias", alias.email) + db.session.rollback() diff --git a/app/api/views/new_custom_alias.py b/app/api/views/new_custom_alias.py index 61408698..afca282a 100644 --- a/app/api/views/new_custom_alias.py +++ b/app/api/views/new_custom_alias.py @@ -9,7 +9,14 @@ from app.config import MAX_NB_EMAIL_FREE_PLAN from app.dashboard.views.custom_alias import verify_prefix_suffix, signer from app.extensions import db from app.log import LOG -from app.models import Alias, AliasUsedOn, User, CustomDomain, DeletedAlias +from app.models import ( + Alias, + AliasUsedOn, + User, + CustomDomain, + DeletedAlias, + DomainDeletedAlias, +) from app.utils import convert_to_id @@ -137,15 +144,25 @@ def new_custom_alias_v2(): LOG.d("full alias already used %s", full_alias) return jsonify(error=f"alias {full_alias} already exists"), 409 - alias = Alias.create( - user_id=user.id, email=full_alias, mailbox_id=user.default_mailbox_id, note=note - ) - + custom_domain_id = None if alias_suffix.startswith("@"): alias_domain = alias_suffix[1:] domain = CustomDomain.get_by(domain=alias_domain) - LOG.d("set alias %s to domain %s", full_alias, domain) - alias.custom_domain_id = domain.id + + # check if the alias is currently in the domain trash + if domain and DomainDeletedAlias.get_by(domain_id=domain.id, email=full_alias): + LOG.d(f"Alias {full_alias} is currently in the {domain.domain} trash. ") + return jsonify(error=f"alias {full_alias} in domain trash"), 409 + + custom_domain_id = domain.id + + alias = Alias.create( + user_id=user.id, + email=full_alias, + mailbox_id=user.default_mailbox_id, + note=note, + custom_domain_id=custom_domain_id, + ) db.session.commit() diff --git a/app/dashboard/templates/dashboard/domain_detail/base.html b/app/dashboard/templates/dashboard/domain_detail/base.html index 81484eaa..a2cd6cc7 100644 --- a/app/dashboard/templates/dashboard/domain_detail/base.html +++ b/app/dashboard/templates/dashboard/domain_detail/base.html @@ -15,6 +15,11 @@ class="list-group-item list-group-item-action {{ 'active' if domain_detail_page == 'dns' }}"> DNS + + + Deleted Alias + diff --git a/app/dashboard/templates/dashboard/domain_detail/trash.html b/app/dashboard/templates/dashboard/domain_detail/trash.html new file mode 100644 index 00000000..a4931a54 --- /dev/null +++ b/app/dashboard/templates/dashboard/domain_detail/trash.html @@ -0,0 +1,50 @@ +{% extends 'dashboard/domain_detail/base.html' %} + +{% set domain_detail_page = "trash" %} + +{% block title %} + {{ custom_domain.domain }} deleted aliases +{% endblock %} + +{% block domain_detail_content %} +