# Обслуживание входа

Как устроены роли и владельцы приложения, что делают в админке SDK входа, как управлять пользователями из кода, вести данные пользователей, хранить и копировать хранилище SDK.

[Роли и владельцы](#роли-и-владельцы) | [Админка](#админка) | [Регистрация и приглашения](#регистрация-и-приглашения) | [Функции управления](#функции-управления) | [Сессии и устройства](#сессии-и-устройства) | [Данные пользователей](#данные-пользователей) | [Хранилище входа](#хранилище-входа) | [Команды](#команды) | [Секрет входа](#секрет-входа) | [Журналы](#журналы)

## Роли и владельцы

У пользователя приложения роль `user` или `admin`. Кроме неё учётной записи можно дать одну именованную роль из объявленных в коде.

### Владельцы и администраторы

Владелец — администратор, который вошёл по ссылке установки. Первого владельца создаёт команда `create-admin`: на сервере платформы её выполняет агент, когда включает вход или когда вы просите «создай админа приложения». Как работает ссылка, её срок и флаг `--reset` описывает [Админ по ссылке установки](../app-login.md#админ-по-ссылке-установки). Владельцев может быть несколько: каждая открытая ссылка добавляет ещё одного.

Остальных администраторов назначает владелец в админке или код приложения функцией `setRole`. В админке владелец может то, что администратору недоступно: назначать администраторов, снимать права с других администраторов и владельцев и проходить шаги мастера «Оператор данных», «Способы входа» и «Журнал». Функции управления это разделение не применяют, см. [Функции управления](#функции-управления).

Права администратора действуют 12 часов после входа через сервис входа. Позже `role` у пользователя читается как `user`, `isOwner` — как `false`, а `needsReauth` — как `true`. `requireUser({ role: 'admin' })` показывает такому администратору экран «Подтвердите вход» со ссылкой на повторный вход, а `fetch` получает `403 {"error":"reauth_required"}`. После повторного входа той же учётной записью права возвращаются.

Вне платформы администраторов задаёт и переменная `AUTH_ADMINS`: `<сервис>:<id>` через запятую, как `yandex:12345`. Такие администраторы — не владельцы. На сервере платформы `AUTH_ADMINS` прав не даёт.

### Именованные роли

Роли объявляют при создании:

```javascript
createAuth({ roles: { manager: { ru: 'Менеджер', en: 'Manager' } } })
```

Ключ роли — `[a-z][a-z0-9_-]{0,31}`, кроме `user` и `admin`, ролей не больше 50, подпись — до 64 символов. Ошибка в объявлении — `AuthConfigError` на старте. Роль выдаёт админка или `auth.setRoleName(userId, 'manager')`, снимает — `auth.setRoleName(userId, null)`. Роль `admin` она не меняет.

`requireUser({ role: 'manager' })` пропускает учётные записи с этой ролью и администраторов. Роль, не объявленная в `roles`, — исключение при создании обработчика, а не ответ на запрос.

## Админка

Админка открывается по адресу `<APP_URL>/_auth/admin` администратору приложения. Все пути под `/_auth/admin` обслуживает SDK: свой маршрут на этом пути не заводите. В админке:

- **Люди** — список учётных записей и карточка человека: роль, именованная роль, блокировка, выход на всех устройствах, выгрузка и удаление данных.
- **Журнал** — события входа и действий администраторов.
- **Приглашения** — ссылки для входа новых людей, см. [Регистрация и приглашения](#регистрация-и-приглашения).
- **Мастер настроек** — пять шагов: оператор данных, способы входа, регистрация, вид, журнал. Пока шаги «Оператор данных» и «Способы входа» не сохранены, клиенты не входят, а статус входа — `setup_pending`.

На сервере платформы способы входа, политику и название приложения задают только в мастере. Переменная с тем же именем в `env` деплоя запирает поле мастера. Как перейти с переменных на мастер у приложения, которое пришло со входа 0.3, описывает [Переход с входа 0.3](../app-login.md#переход-с-входа-0-3).

Дайте администраторам ссылку на админку в интерфейсе приложения. Кнопка «Открыть админку» есть и в карточке приложения в кабинете.

## Регистрация и приглашения

Новый человек при первом входе видит форму «Как к вам обращаться»: имя и согласие на обработку данных. Учётную запись из ссылки установки регистрация не спрашивает.

В шаге мастера «Регистрация» её можно закрыть — режим «по приглашению». Тогда новые люди входят только по ссылке, которую администратор создаёт в разделе «Приглашения» с ролью `user` или с именованной ролью. Ссылка живёт 48 часов и показывается один раз. По ней регистрируется тот, кто откроет её первым, поэтому не публикуйте её. Уже зарегистрированные входят как раньше.

Отказы приходят в обработчик `onEvent` из `createAuth` событием `error` с кодом `registration_closed` — регистрация закрыта, или `invite_invalid` — приглашение истекло, использовано или отозвано.

## Функции управления

Функции вызываются у объекта `auth`, который возвращает `createAuth()`. Все возвращают `Promise`.

| Функция | Что делает |
|---|---|
| `listUsers({ search, role, blocked, limit, cursor })` | Список пользователей: `{ items, nextCursor }`. `limit` — от 1 до 100. Следующая страница — с `cursor` из `nextCursor`, `nextCursor: null` — конец списка |
| `listEvents({ userId, type, limit, cursor })` | Журнал событий. Формат ответа и навигация — как у `listUsers` |
| `getIdentities(userId)` | Способы входа пользователя: `[{ provider, providerUserId }]` |
| `countSessions(userId)` | Число живых сессий пользователя |
| `setRole(userId, role, { actorId })` | Выдать или снять роль `admin`. Понижение владельца снимает и отметку владельца |
| `clearOwner(userId, { actorId })` | Снять отметку владельца, роль `admin` остаётся |
| `setRoleName(userId, name, { actorId })` | Выдать именованную роль или снять её значением `null` |
| `block(userId, { actorId, reason, until })` | Заблокировать пользователя. `reason` — причина до 200 символов, её видит заблокированный, в журнал она не пишется. `until` — время в unix-миллисекундах позже текущего, без него блокировка бессрочна. Сессии перестают действовать на следующем запросе |
| `unblock(userId, { actorId })` | Снять блокировку |
| `deleteUser(userId, { actorId })` | Удалить пользователя, его сессии, способы входа, устройства и согласия |
| `logoutEverywhere(userId, { actorId })` | Завершить все сессии пользователя и забыть его устройства. Отказов `SELF` и `ENV_ADMIN` у неё нет: из кода она завершает сессии кого угодно, в том числе свои и администратора из `AUTH_ADMINS` |
| `exportUser(userId, { actorId })` | Выгрузить всё о пользователе: учётную запись, способы входа, согласия, устройства и события |

`actorId` — `id` администратора, который выполняет действие. Он попадает в журнал событий и защищает от действия над собой. Права этого администратора функция не проверяет: код приложения действует от имени владельца, с `actorId` и без него. Кто может вызвать функцию, решает обработчик приложения — пропускайте к ней только `requireUser({ role: 'admin' })` и проверяйте сами, что администратор вправе это сделать, например что он не меняет владельца.

Выгрузку `exportUser` отдаёт с событиями потоком, `JSON.stringify` на ней бросает `INVALID_ARGUMENT`. Записывайте её функцией `exportChunks` из пакета:

```javascript
const { exportChunks } = require('@bitrix24/vibecode-auth')

const data = await auth.exportUser(userId, { actorId: req.authUser.id })
res.setHeader('Content-Type', 'application/json')
for await (const chunk of exportChunks(data)) res.write(chunk)
res.end()
```

Блокировку со сроком снимает следующий вход пользователя после срока, в журнал пишется событие `unblock`. Код с исчерпывающим `switch` по `type` события держит ветку `default`: список типов расширяется.

Ошибки — исключение `AuthError` с полем `code`:

| `code` | Когда |
|---|---|
| `INVALID_ARGUMENT` | `userId` не в формате идентификатора пользователя — 32 шестнадцатеричных символа, роль не `admin` и не `user`, именованная роль не объявлена, `until` не позже текущего момента, `limit` вне диапазона от 1 до 100 |
| `NOT_FOUND` | Пользователя с таким `userId` нет |
| `SELF` | Понизить, заблокировать, удалить себя или снять отметку владельца с себя: `actorId` совпадает с `userId` |
| `ENV_ADMIN` | Вне платформы: понизить, заблокировать или удалить администратора из `AUTH_ADMINS` |
| `LAST_ADMIN` | Понизить последнего незаблокированного администратора. Запрет действует и для кода без `actorId` |

Каждое изменение пользователя SDK решает и записывает под блокировкой администраторов в хранилище. Если блокировку не удалось взять за 5 секунд, функция бросает `StorageError` с `reason: 'busy'` — повторите позже.

## Сессии и устройства

- Сессия хранится в хранилище, в браузере — только её токен в куке `vauth_sid`: `HttpOnly`, `SameSite=Lax`, а вне режима разработки ещё `Secure` и префикс `__Host-`.
- Сессия гаснет после 14 дней без активности и в любом случае через 30 дней после входа.
- У пользователя не больше 50 живых сессий. Новая сессия сверх лимита завершает самую старую.
- Кука `vauth_dev` метит браузер, живёт 400 дней и выходом не стирается. По ней учётная запись помнит до 10 своих устройств, самое старое вытесняется. Ни `User-Agent`, ни IP-адрес SDK не хранит.
- Блокировка и выход на всех устройствах действуют на следующем запросе: кеша сессий в памяти у SDK нет.

Если в уведомлении приложения о куках есть перечень, внесите в него `vauth_sid`, `vauth_dev`, `vauth_lang` — язык экранов SDK, и временные куки `vauth_tx`, `vauth_pending` и `vauth_once`, которые живут от 60 секунд до 10 минут.

## Данные пользователей

Оператор персональных данных посетителей — автор приложения. Политику обработки данных он публикует сам или задаёт в мастере реквизиты оператора.

- **До регистрации** профиль от сервиса входа хранится только в зашифрованной куке браузера. Отказ на экране регистрации стирает куку, в хранилище ничего не записывается.
- **Согласие** запоминается вместе с версией и ссылкой политики и набором полей. Новое согласие запрашивается после смены версии политики и после добавления полей в `AUTH_REQUEST_FIELDS`. Поле, убранное из `AUTH_REQUEST_FIELDS`, очищается у всех пользователей.
- **«Мой аккаунт»** `/_auth/account` показывает человеку его имя, способы входа и устройства. Там он меняет имя, привязывает и отвязывает способы входа, завершает сессию на устройстве, выгружает свои данные и удаляет учётную запись. Привязка, выгрузка и удаление требуют входа не старше 10 минут: иначе SDK сначала проводит человека через повторный вход.
- **Удаление себя** стирает сессии, способы входа, устройства, согласия и самого пользователя одной транзакцией. Последний администратор удалить себя не может, SDK отвечает `409 LAST_ADMIN`: сначала назначьте другого. Ведите человека на «Мой аккаунт» ссылкой, а не вызовом `fetch` из своей кнопки.
- **Резервные копии** содержат персональные данные, в том числе пользователей, удалённых после создания копии.

## Хранилище входа

Таблицы `vauth_*` и каталог `/data/.vauth/` принадлежат SDK:

- не удаляйте и не очищайте их,
- исключите таблицы `vauth_*` из синхронизации схемы, которую ведёт ORM приложения — библиотека, строящая таблицы базы по моделям кода,
- не отдавайте содержимое `/data` как статические файлы. Файлы пользователей кладите в `/data/uploads/` под сгенерированными именами.

На SQLite каждое удаление учётной записи дописывает её идентификатор и время в журнал удалений рядом с базой, например `/data/.vauth/deleted.log`. Персональных данных в нём нет. По нему восстановление копии на месте снова удаляет тех, кто был удалён после её создания.

Хранилище помечено подписью, вычисленной из секрета входа. Приложение не стартует с хранилищем, которое создано под другим секретом:

```
- the store mark does not match VIBE_AUTH_SECRET (store_id 23e999b75da5dbbcf6d3e295802c1347): this store was created under none of this app's system secrets (current, previous or revoked). …
```

Базу в этом случае не пересоздавайте: выясните, откуда она взялась, например не указывает ли `AUTH_SQLITE_PATH` или `DATABASE_URL` на базу другого приложения.

Копии PostgreSQL и MySQL делают средствами базы — `pg_dump`, `mysqldump`: таблицы `vauth_*` — часть базы приложения. Приложение со входом восстанавливается из резервной копии сервера только на месте, см. [Перенос и восстановление](../app-secrets.md#перенос-и-восстановление).

## Команды

Команды запускают в каталоге приложения через `npx --no-install vibecode-auth`. Они читают те же секреты, что и приложение: на сервере платформы — `VIBE_AUTH_SECRET`, вне платформы — `AUTH_SECRET`.

### create-admin

```bash
npx --no-install vibecode-auth create-admin
```

Печатает одну строку — ссылку установки администратора `<APP_URL>/_auth/setup-admin#vauth:t=…`. Параметры: `--env-file <путь>` — файл с переменными, `--url <APP_URL>` — адрес приложения, `--reset` — оставить владельцем одного того, кто откроет ссылку. Не запускайте команду в фоне с записью вывода в журнал: кто откроет ссылку первым, тот и владелец. На сервере платформы команду выполняет агент синхронным [`exec`](/docs/infra/deploy/exec), на отдельной машине — с `--env-file /var/lib/vibe/app-login/<служба>.env`.

### migrate

При старте SDK сам создаёт и обновляет схему. С `AUTH_MIGRATIONS=off` схему обновляет команда:

```bash
npx --no-install vibecode-auth migrate
```

```
vibecode-auth: schema is up to date (store_id 23e999b75da5dbbcf6d3e295802c1347, sqlite /data/.vauth/vauth.sqlite)
```

Хранилище команда выбирает в таком порядке: параметр `--database-url`, затем `AUTH_SQLITE_PATH`, затем `DATABASE_URL`, если он начинается с `postgres://`, `postgresql://` или `mysql://`, иначе файл SQLite по умолчанию. Строка успеха называет, какое хранилище она тронула. Значение `--database-url` видно в списке процессов и истории оболочки.

### backup

Копия SQLite — командой SDK, а не копированием живого файла:

```bash
npx --no-install vibecode-auth backup --to /data/.vauth/backup.sqlite
```

```
vibecode-auth: backup of sqlite /data/.vauth/vauth.sqlite written to /data/.vauth/backup.sqlite
```

Если файл копии уже существует, команда отказывает с `the backup target already exists`. Если файла SQLite по пути `AUTH_SQLITE_PATH` нет, команда отказывает и называет путь. Из кода то же делает `await auth.backup('/data/.vauth/backup.sqlite')`. Журнал удалений в копию не входит.

## Секрет входа

На сервере платформы секретом входа управляет платформа: `VIBE_AUTH_SECRET` появляется при включении входа и доставляется приложению как системный секрет. Его значение не показывают ни кабинет, ни API. Задать, заменить или удалить системный секрет через API нельзя, см. [Секреты автора и системные секреты](../app-secrets.md#секреты-автора-и-системные-секреты).

Секрет подписывает сессии, ссылки установки и метку хранилища. SDK читает его один раз при старте и удаляет из `process.env`, поэтому код приложения секрета не видит.

## Журналы

- Исключите строку запроса `/_auth/callback/*` из журнала запросов приложения: в ней одноразовый код сервиса входа.
- SDK не пишет секрет, токены, коды и куки ни в события, ни в консоль, ни в текст исключений. Исключения — токен входа в режиме разработки, который SDK печатает в консоль, и ссылка установки, которую печатает `create-admin`.
- Имя, почта и телефон пользователя — недоверенные данные. Экранируйте их при выводе и не сопоставляйте учётные записи по почте.

## Смотрите также

- [Вход пользователей приложения](../app-login.md)
- [Подключение SDK входа](./install.md)
- [Секреты приложения](../app-secrets.md)
- [Galaxy-приложение](/docs/infra/galaxy)
