Update README.md

Author: grigoriev-semyon

README.md

@@ -1,80 +1,59 @@
-1. Архитектура 
+# auth-api
+ API сервиса аутентификации и авторизации в приложение Твой ФФ!
 
-Для добавления методов авторизации используется плагинная архитектура. Это сделано для того, чтобы очень быстро, практически не меняя существующий код внедрять новые методы авторизации. Новые методы внедряются с помощью наследованния от метакласса AuthMethod. Все остальное сделано по обычным паттернам.
+## Запуск
 
-2. Регистрация через email
+1) Перейдите в папку проекта
 
-Чтобы зарегистрироваться через email надо дернуть ручку /email/registrate. Туда передается email и пароль через json. Регистрация через email доступна для незарегестрированных пользователей или для пользователей у которых определены методы регистрации, но не email. Возможны несколько исходов регистрации:
+2) Создайте виртуальное окружение командой и активируйте его:
+```console
+foo@bar:~$ python3 -m venv venv
+foo@bar:~$ source ./venv/bin/activate  # На MacOS и Linux
+foo@bar:~$ venv\Scripts\activate  # На Windows
+```
 
-    1. Успешно - 201
+3) Установите библиотеки
+```console
+foo@bar:~$ pip install -r requirements.txt
+```
+4) Запускайте приложение!
+```console
+foo@bar:~$ python -m auth_backend
+```
 
-    Если пользователь зарегестрирован. Ему отправляется письмо для подтверждения почты, где есть ссылка, переходя нна которую происходит подтверждение.
+## ENV-file description
 
-    2. Успешно - 200
-  
-    Если пользщователь уже регестрировался, но не подтвердил свою почту. Ему отправляется повторное письмо, где есть новый линк. 
+DB_DSN=postgresql://admin:admin@localhost:5432/?
+EMAIL_PASS=
+EMAIL=
+HOST=
 
-    3. AlreadyExists - 409
+---
 
-    Если пользователь уже зарегистрироваля и подтвердил почту.
+## Сценарий использования
+### Что надо сделать чтобы зарегистрировать пользователя через email
 
-    4. ObjectNotFound - 404
+1. Дернуть ручку `POST /email/registrate` . Вы передаете `{email: "", password: ""}`
+2. На почту приходит письмо с линком на `GET /email/approve?token='...'`, если по ней перейти то почта будет подтверждена и регистрацию можно считать завершенной.
 
-    Если указано для какого пользователя добавить метод регистрации и этого пользователя не существует.
+### Что надо сделать чтобы залогиниться через email
 
-    5. SessionExpired - 403
+1. Дернуть ручку `POST /email/login`. там всего один вариант логина, никуда не денетесь 
+2. Вам придет токен, сохраняйте его кууда нибудь, срок действия ограничен.
 
-    Если указано для какого пользователя добавить метод регистрации, указана его сессия, которая, в свою очередь, протухла.
+### Забыли пароль
 
-При любом исходе возвращает т.н ResponseModel = {status: str, message: str}
+1. Дернуть ручку `POST /email/reset/password/request`. Вы передаете `{email: ""}`в нагрузке 
+2. Вам придет письмо, где будет ссылка НА ФРОНТ(надо сделать это), в ссылке будет reset_token
+3. Токен надо передать в ручку `POST /email/reset/password` в заголовках, вместе с `{email: "", new_password: ""}` и пароль будет изменен. email не понадобится после решения #36
+        
+### Смена пароля 
 
-3. Логин через email. 
+1. Если пароль не забыт, а просто надо его поменять. Тогда в `POST /email/reset/password/request` передается токен авторизации, в теле вы передаете `{email: "", password: "", new_password: ""}`
+2. Отправляете запрос и всё, пароль изменен, вам придет письмо с уведомлением о смене пароляю
 
-Чтобы залогиниться надо дернуть ручку email/login. Туда передается email, password. Что может быть, если дернуть ручку:
+### Что надо сделать, чтобы поменять почту
 
-    1. AuthFailed - 401
-
-    Если логин+пароль неправильный или если пользователь не подтвердил email.
-
-    2. Успешно - 200
-
-    Возвращает в таком случае объект UserSession = {id: int, token: str, expires: datetime}
-
-4. Смена пароля
-
-Чтобы поменять пароль, существует два варианта: либо поменять его из открытой сессии: нужен email, password, new_password, token, либо в случае забытого пароля можно пользоваться только email.
-
-    1. Восстановление без сессии
-
-    Надо дернуть ручку /email/password/reset/request, передать туда email. На почту приходит письмо со ссылкой на фронт, где можно поменять пароль, там     есть reset_token в ссылке. Далее этот токен надо отправить в ручку /email/password/reset, туда отправляется email, reset_token в хедере, new_password в json. 
-    2. Восстановление с сессией
-    
-    Надо дернуть ручку /email/password/reset/request, передать туда email, token, password, new_password. Пароль просто поменяется, придет письмо об этом.
-    
-    3. Ручка /email/password/reset/request может кидать:
-            1. SessionExpired - 403, если переданная сессия закончилась
-            2. 401, Auth method restricted for this user
-            3. AuthFailed - 401, Incorrect password  || Registration wasn't completed.
-            4. 403, Incorrect user session, если переданная сессия не принадлежит юзеру.
-            5. Успешно - 200, Возвращает ResponseModel
-            6. 404, Email not found
-            
-    4. Ручка /email/password/reset может кидать:
-            1. 404, Email not found
-            2. 403, Incorrect reset token
-            3. Успешно - 200, возвращает ResponseModel
-5. Смена почты 
-
-Чтобы поменять почту, надо дернууть ручку /email/reset/email/request, туда передается новая почта и токен. На новую почту приходит письмо, в котором лежит ссылка на подтверждение новой почты. Ссылка на ручку /email/reset/email.
-
-        1. Ручка /email/reset/email/request:
-                1. 401, Unauthorized, если сессия не передана
-                2. SessionExpired - 403
-                3. IncorrectUserAuthType - 403, у юзера нет такого способа входа
-                4. AuthFailed - 401, Registration wasn't completed
-                5. 401, Email incorrect
-                6. Успешно - 200
-         2. Ручка /email/reset/email
-                1. AuthFailed - 401
-                2. 403, Incorrect new email || Incorrect confirmation token
-                3. Успешно - 200
+1. Дернуть ручку `POST /email/reset/email/request`. Всего один вариант, передаете новое мыло в теле `{email: ""}` и токен атворизации в заголовках
+2. На почту придет письмо с подтверждением почты, там будет токен подтверждения в query параметрах. Ссылка ведет на ручку GET пока что, но надо переделать, чтобы тоже вела на фронт.
+