> For the complete documentation index, see [llms.txt](https://docs.johncms.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.johncms.com/10.0/polzovateli/zhurnal-vkhodov.md).

# Журнал входов (аудит)

Всё, что меняет доступ к аккаунту, записывается в таблицу `auth_events`: входы и отказы, смена пароля, восстановление, завершение сессий, выдача и снятие ролей. Журнал отвечает на вопрос «что случилось с этой учётной записью и кто это сделал» — до 10.0 такой записи не велось вовсе.

Смотреть журнал — в админке, `/admin/auth-log`. Экран открывается по праву `admin.auth_log.view` (по умолчанию у роли `admin`), список фильтруется по пользователю и по типу события.

## Что попадает в запись

| Колонка            | Что в ней                                                                                |
| ------------------ | ---------------------------------------------------------------------------------------- |
| `user_id`          | о ком событие; пусто, если вход пытались выполнить под несуществующим логином            |
| `actor_id`         | кто это сделал, если не сам владелец: администратор или тот, кто вошёл под пользователем |
| `event`            | ключ события, например `login.success`                                                   |
| `ip`, `user_agent` | откуда пришёл запрос                                                                     |
| `context`          | произвольные подробности события: причина отказа, введённый логин, слаг роли             |
| `created_at`       | когда это произошло                                                                      |

Ключи событий ядра: `login.success`, `login.failed`, `logout`, `password.changed`, `password.reset.requested`, `password.reset.completed`, `session.revoked`, `role.granted`, `role.revoked`.

Попытки, отклонённые троттлингом, не записываются: они следствие уже записанных неудач, и иначе таблицу можно было бы заполнить простым перебором.

## Запись события из модуля

Логгер инжектится по интерфейсу:

```php
use Johncms\Auth\Events\AuthEventLoggerInterface;

final readonly class BanUserUseCase
{
    public function __construct(private AuthEventLoggerInterface $eventLogger)
    {
    }

    public function execute(int $userId): void
    {
        // ...
        $this->eventLogger->log('shop.subscription.revoked', $userId, ['plan' => 'gold']);
    }
}
```

Первым аргументом можно передать как `AuthEventType`, так и свою строку — ключи модулей ядро не проверяет и показывает в журнале как есть. IP, User-Agent и `actor_id` логгер заполняет сам: их не нужно (и нельзя) передавать вручную.

## Срок хранения

Записи чистит задача `auth:cleanup` — та же, что удаляет мёртвые сессии. По умолчанию журнал хранится 180 суток (`--event-retention-days`), заметно дольше сессий: аудит читают, когда разбираются в происшествии, а это случается спустя месяцы.