# Аутентификация и безопасность учётных записей

Стартовый проект Auth Starter Elang включает регистрацию, вход через сессию, подтверждение адреса, восстановление пароля, обновление профиля, смену пароля и API-токены с областями доступа. Включите его через AuthProvider; стартовый проект уже делает это за вас.

## Создание приложения с аутентификацией

```bash
elang new my-app --starter=auth
cd my-app
php elang serve
```

После однократной настройки установщика эта команда создаёт приложение через Composer. Зависимости, ключ приложения, миграции схемы и проверки doctor входят в настройку проекта. Откройте `/register`, чтобы создать собственную учётную запись. Общий пароль администратора не предусмотрен.

## Сессии и защищённые маршруты

AuthProvider объединяет браузерные маршруты учётной записи за middleware сессии, CSRF и ограничения частоты запросов. При входе обновляются идентификатор сессии и токен CSRF. При выходе сессия аннулируется. Тела запросов и значения авторизации не записываются Elang Studio.

Используйте RequireAuth на закрытых браузерных маршрутах после SessionMiddleware. Он помещает текущего User в атрибут запроса `_user`. Временный пароль перенаправляет пользователя на `/password`, прежде чем ему станут доступны закрытые возможности.

```php
$router->get('/private', fn () => ['message' => 'Signed in'])
    ->middleware(SessionMiddleware::class, RequireAuth::class);
```

Для форм, изменяющих состояние, используйте полную группу middleware из стартового проекта, включая CsrfMiddleware. Защищённому маршруту по-прежнему нужны проверки принадлежности данных или политик, специфичные для приложения.

## Пароли и восстановление

Пользовательские пароли должны содержать не менее 12 символов; поддерживаются длинные парольные фразы. Сохраняемое значение — хеш Argon2id. Из доверенного терминала можно создать временный пароль, который потребуется сменить при первом входе.

Ссылки восстановления и подтверждения используют случайные одноразовые токены. В базе данных хранятся только хеши токенов с назначением и сроком действия. Успешная смена пароля аннулирует остальные сессии и отзывает API-токены. Сброс пароля не выполняет незаметный вход в новом браузере.

## Локальная почта и почта в рабочей среде

При APP_ENV=local и пустом почтовом транспорте сообщения учётной записи сохраняются в зашифрованном виде в закрытом почтовом ящике разработки. Откройте `/_elang/studio/mail` локально, чтобы воспользоваться ссылкой подтверждения или сброса.

В рабочей среде настройте MAILER_DSN и MAIL_FROM. Пустой транспорт не заявляет об успешной доставке писем учётной записи; восстановление сообщает о недоступности сервиса. Локальный почтовый ящик и Studio не предоставляются в рабочей среде.

## Авторизация и роли

При регистрации всегда создаётся обычный пользователь. Переданные поля роли не принимаются. Доверенная процедура подготовки может создать администратора; RequireAdmin также требует подтверждённый адрес электронной почты. Gate позволяет приложению задавать явные политики:

```php
$gate->define('post.update', fn (User $user, Post $post) =>
    $post->author_id === $user->id
);
$gate->authorize('post.update', $user, $post);
```

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

## API-токены

Создавайте токены на странице учётной записи после подтверждения адреса и пароля. Исходный токен показывается один раз. Строки базы данных хранят хеш SHA-256, явные области доступа, владельца и срок действия. BearerAuth аутентифицирует токен; RequireScope проверяет значение `_scope` по умолчанию у маршрута. Владелец токена никогда не определяется из тела запроса.