Skip to content

README-RU.md

Latest commit

 

History

History
331 lines (222 loc) · 28.9 KB

README-RU.md

File metadata and controls

331 lines (222 loc) · 28.9 KB
Raw

Версия 1.2.0

Содержание

web-soft-auth

Модуль авторизации/аутентификации для использования совместно с пакетом web-soft-server. Используется авторизация/аутентификация на основе механизма сессий. За хранение сессий отвечает пакет web-soft-server. На данный момент доступно два модуля: простой модуль AuthModule и модуль с двухфакторной аутентификацией TwoFactorAuthModule.

Пример использования простого модуля AuthModule:

const { Server, logger } = require('web-soft-server');
const { AuthModule } = require('../index');
const modules = require('./modules');

let server = {};

const start = async () => {
  try {
    server = new Server({ host: '0.0.0.0', port: 8000, cors: false });
    server.start({ ...modules, auth: AuthModule });
  } catch (error) {
    logger.fatal(error);
  }
};

start();

Пример использования модуля с двухфакторной аутентификацией TwoFactorAuthModule. В данном случае необходимо передать объекту messageService объект транспорта, который должен реализовывать интерфейс MessageTransport, иначе при попытке отправки сообщения будет выбрасываться исключение:

const { Server, logger } = require('web-soft-server');
const { TwoFactorAuthModule, messageService } = require('../index');
const messageTransport = require('./message-transport.js');
const modules = require('./modules');

messageService.setTransport(messageTransport);
let server = {};

const start = async () => {
  try {
    server = new Server({ host: '0.0.0.0', port: 8000, cors: false });
    server.start({ ...modules, auth: TwoFactorAuthModule });
  } catch (error) {
    logger.fatal(error);
  }
};

start();

Class: web-soft-auth.Auth

Предоставляет методы связанные с простой авторизацией/аутентификацией. Является базовым классом для класса TwoFactorAuth.

new Auth([manager])

auth.register(data, context)

  • data <object> объект с данными нового пользователя:
    • username <string> имя аккаунта пользователя, минимальная длина 2 символа.
    • password <string> пароль.
  • context <Client> объект имплементирующий интерфейс Client для инициализации сессии пользователя, после успешной регистрации.
  • Returns: <Promise<object>>
    • username <string> имя аккаунта созданного пользователя.
    • role <string> роль созданного пользователя.
    • createdTime <string> время добавления пользователя в БД.

Метод регистрации нового пользователя.

В целях безопасности, к паролю предъявляются следующие требования: минимальная длина - 12 символов, максимальная длина - 128 символов, все повторяющиеся подряд идущие пробельные символы заменяются одним пробельным символом, так же пароль не должен входить в список 1000 наиболее частых используемых паролей представленным тут.

twoFactorAuth.login(data, context)

  • data <object> объект с данными пользователя.
    • username <string> имя аккаунта пользователя.
    • password <string> пароль.
  • context <Client> объект имплементирующий интерфейс Client для инициализации сессии пользователя, после успешной аутентификации.
  • Returns: <Promise<object>>
    • username <string> имя аккаунта пользователя.
    • role <string> роль пользователя.
    • createdTime <string> время добавления пользователя в БД.

Метод аутентификации пользователя.

auth.logout(data, context)

  • data <object> пустой объект, нужен исключительно для соблюдения контракта и передачи вторым аргументом объекта context.
  • context <Client> объект имплементирующий интерфейс Client для удаления сессии пользователя.
  • Returns: <Promise<void>>

Метод деавторизации пользователя.

auth.me(data, context)

  • data <object> пустой объект, нужен исключительно для соблюдения контракта и передачи вторым аргументом объекта context.
  • context <Client> объект имплементирующий интерфейс Client для получения информации о текущем пользователе.
  • Returns: <Promise<object>>
    • username <string> имя аккаунта пользователя.
    • role <string> роль пользователя.
    • createdTime <string> время добавления пользователя в БД.

Метод для получения информации о текущем авторизованном пользователе.

auth.changePassword(data, context)

  • data <object> объект с данными пользователя.
    • oldPassword <string> текущий пароль пользователя.
    • newPassword <string> новый пароль пользователя.
  • context <Client> объект имплементирующий интерфейс Client для получения информации о текущем пользователе.
  • Returns: <Promise<object>>
    • username <string> имя аккаунта пользователя.
    • role <string> роль пользователя.
    • createdTime <string> время добавления пользователя в БД.

Метод для смены пароля текущего авторизованного пользователя.

Class: web-soft-auth.LockoutManager

Отвечает за отслеживание неудачных попыток пользователей пройти аутентификацию и временную блокировку их учётных записей в случае превышения лимита попыток аутентификации.

lockoutManager.access(username)

  • username <string> имя аккаунта пользователя.
  • Returns: <boolean>

Метод для проверки заблокирован ли аккаунт пользователя, если нет возвращает true, иначе выбрасывает исключение ACCOUNT_LOCKOUT_ERROR.

lockoutManager.fail(username)

  • username <string> имя аккаунта пользователя.

Метод для регистрации неудачной попытки аутентификации пользователя. Если при регистрации неудачной попытки, аккаунт пользователя будет временно заблокирован, будет выброшено исключение ACCOUNT_LOCKOUT_ERROR.

Class: web-soft-auth.TwoFactorAuth

Наследник класса Auth. Переопределяет метод регистрации, добавляет метод восстановления пароля. Не отвечает за отправку кодов, а лишь меняет реализацию базового класса, добавляя логику подтверждения с помощью кода, и предоставляет интерфейс для получения кода.

new TwoFactorAuth([service, [manager]])

twoFactorAuth.register(data, context)

  • data <object> объект с данными нового пользователя:
    • username <string> имя аккаунта пользователя, минимальная длина 2 символа.
    • password <string> пароль.
    • code <number> полученный код подтверждения.
  • context <Client> объект имплементирующий интерфейс Client для инициализации сессии пользователя, после успешной регистрации.
  • Returns: <Promise<object>>
    • username <string> имя аккаунта созданного пользователя.
    • role <string> роль созданного пользователя.
    • createdTime <string> время добавления пользователя в БД.

Метод регистрации нового пользователя с подверждением с помощью кода.

В целях безопасности, к паролю предъявляются следующие требования: минимальная длина - 12 символов, максимальная длина - 128 символов, все повторяющиеся подряд идущие пробельные символы заменяются одним пробельным символом, так же пароль не должен входить в список 1000 наиболее частых используемых паролей представленным тут.

twoFactorAuth.restore(data)

  • data <object> объект с данными для восстановления доступа:
    • username <string> имя аккаунта пользователя.
    • password <string> пароль.
    • code <number> полученный код подтверждения.
  • Returns: <Promise<string>>

Метод для восстановления доступа пользователя к системе путём смены пароля. Владение аккаунтом подтверждается через уникальный код, отправленный реализованным приложением способом. В случае успеха, возвращает имя аккаунта пользвателя.

twoFactorAuth.send(data)

  • data <object> объект с информацией об отправке:
    • destination <string> адрес отправки кода, может быть номером телефона, адресом почты и т.д.
  • Returns: <Promise<string>>

Метод для отправки кода по указанному адресу. Возвращает параметр destination в случае успешной отправки.

Class: web-soft-auth.MessageService

Отвечает за отправку и сообщейний с кодом и валидацию полученных кодов. В целях переиспользования кода класс не отвечает непосредственно за доставку сообщений, поэтому для полноценной работы классу необходимо передать объект транспорта, реализующий интерфейс MessageTransport.

messageService.setTransport(transport)

  • transport <MessageTransport> объект, отвечающий за доставку сообщений пользователю по указанному адресу.

Метод для установки транспорта сообщений, созданному экземпляру класса.

messageService.setCodeTimeOut(timeout)

  • timeout <number> время, спустя которое код, отправленный в сообщении, станет недействительным.

messageService.send(destination)

  • destination <string> адрес отправки кода, может быть номером телефона, адресом почты и т.д.
  • Returns: <Promise<string>>

Метод для отправки кода по указанному адресу. Возвращает параметр destination в случае успешной отправки.

messageService.checkDestination(destination)

  • destination <string> адрес отправки кода, может быть номером телефона, адресом почты и т.д.
  • Returns: <boolean>

Метод проверяет наличие уже отправленного кода по указанному адресу назначения. Если код уже отправлен и всё ещё действителен, выбрасывается исключение CODE_EXISTS_ERROR, иначе возвращает true.

messageService.getCode(destination)

  • destination <string> адрес, для которого нужно получить код.
  • Returns: <number>

Метод возвращает отправленный код для указанного адреса назначения. Если код для указанного адреса не найден, будет выбрашено исключение CODE_NOT_FOUND_ERROR.

messageService.deleteCode(destination)

  • destination <string> адрес, для которого нужно удалить код.

Метод удаляет код для указанного адреса.

ВАЖНО: Так как коды храняться в оперативной памяти, необходимо вызывать функцию удаления после подтверждения кода.

Module: web-soft-auth.AuthModule

Модуль простой авторизации/аутентификации для пакета web-soft-server.

Module: web-soft-auth.TwoFactorAuthModule

Модуль с двухфакторной аутентификацией для пакета web-soft-server.

Interface: web-soft-auth.MessageTransport

Интерфейс объекта, отвечающего за доставку сообщения пользователю.

messageTransport.send(destination, code)

  • destination <string> адрес, по которому нужно доставить код.
  • code <number> код.

Метод отправляет сообщение с кодом адресату. Выбрасывает исключение, в случае неудачной отправки.

web-soft-auth.messageService

Глобальный экземпляр класса MessageService, используемый по умолчанию классом TwoFactorAuth.

web-soft-auth.lockoutManager

Глобальный экземпляр класса LockoutManager, используемый по умолчанию классом Auth.

web-soft-auth.CODE_TIMEOUT

  • <number> время жизни кода после отправки пользователю, 300000 мс.

web-soft-auth.OBSERVATION_WINDOW

  • <number> период времени, в течение которого должны произойти неудачные попытки аутентификации для блокировки аккаунта пользователя, 300000 мс.

web-soft-auth.LOCKOUT_THRESHOLD

  • <number> количество неудачных попыток аутентификации для блокировки аккаунта пользователя, 3.

web-soft-auth error codes

Коды ошибок, использованные в пакете web-soft-auth.

SECURITY_PASSWORD_ERROR

  • code <number> 40600.
  • message <string> Problem with password strength.

ACCOUNT_LOCKOUT_ERROR

  • code <number> 40601.
  • message <string> Too many fail attempts to login.

CODE_NOT_FOUND_ERROR

CODE_EXISTS_ERROR

  • code <number> 40603.
  • message <string> Code already exists, try later.