# Подключение SDK входа

Как поставить SDK входа в приложение на Node.js, подключить его к коду и что SDK отвечает приложению и посетителю. Пакет `@bitrix24/vibecode-auth` раздаёт сама платформа, в публичном реестре npm его нет.

[Перед установкой](#перед-установкой) | [Установка](#установка) | [Хранилище входа](#хранилище-входа) | [Подключение](#подключение) | [Маршруты SDK](#маршруты-sdk) | [Переменные окружения](#переменные-окружения) | [Ошибки старта](#ошибки-старта) | [Режим разработки](#режим-разработки)

## Перед установкой

На сервере платформы SDK стартует только во включённом входе. Включение, вопрос «кто будет пользоваться приложением», первого администратора и статусы входа описывает [Вход пользователей приложения](../app-login.md). Эта страница — о том, что делают с SDK в коде.

Приложению нужны Node.js 24.15 или новее на Express или `node:http` и деплой с `runtime: node24`. На отдельной машине приложение запускает служба платформы: деплой с `systemd: true` и командой запуска самого приложения.

## Установка

1. Поставьте пакет без скриптов установки. Точную команду для сервера даёт поле `sdk.installCommand` [настройки входа](../app-login.md#get-v1-app-user-signin-servers-serverid-setup):

   ```bash
   npm install --ignore-scripts https://vibecode.bitrix24.tech/sdk/vibecode-auth-0.4.4.tgz
   ```

   Адрес отдаёт архив только выпущенной версии. Неизвестная или отозванная версия отвечает `404`.
2. Сверьте хеш пакета. В `package-lock.json` у записи `node_modules/@bitrix24/vibecode-auth` поле `integrity` должно совпасть с `sdk.integrity` из настройки входа. Для версии `0.4.4`:

   ```
   sha512-BW9fu+G3UphtF2LQksS85Mzgexy0FV8P6Fv70TlxvSXHQhQW2eu6ZIJorbg1Vb8UKninvgv8+LiyAlveuSNF+g==
   ```

   Хеш не совпал — остановитесь и не запускайте приложение с этим пакетом.
3. Поставьте драйвер хранилища, если оно не SQLite, — таблица ниже.

SDK проверяет среду до чтения окружения. Node.js ниже 24.15.0 или собранный без `crypto.argon2` получает отказ старта. Если на хосте остался старый образ, сделайте деплой на актуальный образ с `runtime: node24`.

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

Пользователи, сессии, настройки и согласия хранятся в хранилище приложения. Какое хранилище выбрать, зависит от размещения:

| Размещение | Хранилище | Драйвер |
|---|---|---|
| Galaxy-приложение | Файл SQLite `/data/.vauth/vauth.sqlite` на постоянном томе `/data` | Не нужен, проверка — `node -e "require('node:sqlite')"` |
| Виртуальная машина с PostgreSQL | PostgreSQL этой машины | `npm install pg@8` |
| Виртуальная машина с MySQL | MySQL этой машины | `npm install mysql2@^3.23.1` |
| Виртуальная машина без базы | Файл SQLite `/var/lib/vauth/vauth.sqlite` вне каталога приложения либо внешняя PostgreSQL или MySQL | Для SQLite не нужен, для базы — её драйвер |

- **SQLite.** SDK берёт встроенный модуль `node:sqlite`. Путь к файлу задаёт платформа, когда вход включён: `/data/.vauth/vauth.sqlite` в галактике и `/var/lib/vauth/vauth.sqlite` на отдельной машине. Каталог `/var/lib/vauth` деплой добавляет в `dataDirs` сам, поэтому файл переживает повторный деплой.
- **PostgreSQL и MySQL машины.** Рантайм не выдаёт строку подключения: создайте базу, пользователя и строку подключения сами и передайте пул в `createAuth` — см. [Своя база](#своя-база). Для MySQL нужен рантайм с Node.js 24, например `node24-mysql`: на `node20-*` SDK не стартует.

## Подключение

### Express

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

const app = express()
createAuth().then((auth) => {
  app.use(auth.express())
  app.get('/orders', auth.requireUser(), (req, res) => res.json({ user: req.authUser }))
  app.listen(process.env.PORT || 3000)
})
```

`auth.express()` обслуживает маршруты SDK под `/_auth` и передаёт остальные запросы приложению. Подключайте его до разбора тела запроса и до обработчика CORS: известный путь SDK, запрошенный другим методом, SDK отвечает сам `405`, и до обработчика, подключённого после, такой запрос не доходит. `auth.requireUser()` пропускает запрос с живой сессией и кладёт пользователя в `req.authUser`.

Ссылка «Войти» в интерфейсе приложения ведёт на `/_auth/login?returnTo=<путь>`, ссылка «Мой аккаунт» — на `/_auth/account`. Дайте её в меню приложения: там человек меняет имя, видит устройства и удаляет свои данные.

Вызывайте `createAuth()` один раз за процесс. Прочитав окружение, SDK удаляет секреты входа из `process.env`, и повторный вызов в том же процессе получает отказ старта. Если старт не удался, например база ещё не поднялась, перезапускайте процесс целиком, а не повторяйте `createAuth()` в цикле.

### Ответы requireUser

Ответ зависит от того, как пришёл запрос. Навигация — `GET` или `HEAD` с `Accept: text/html`, то есть переход в браузере. Остальные запросы, например `fetch`, получают JSON.

| Ситуация | Навигация | Остальные запросы |
|---|---|---|
| Нет сессии | `302` на `/_auth/login?returnTo=<путь>&h=1` | `401 {"error":"unauthenticated"}` |
| Мастер настроек не пройден | `200`, экран «Вход скоро откроется» | `503 {"error":"setup_pending"}` |
| Пользователь заблокирован | `403`, экран «Вы заблокированы» с причиной и сроком | `403 {"error":"blocked"}` |
| Роль не подходит | `403`, экран «Нет доступа» | `403 {"error":"forbidden"}` |
| Администратор вошёл больше 12 часов назад | `200`, экран «Подтвердите вход» со ссылкой на `/_auth/reauth` | `403 {"error":"reauth_required"}` |
| Запрос из фрейма чужого сайта, например портала Битрикс24 | `200`, экран «Приложение откроется в новой вкладке» | — |
| Хранилище недоступно | `503 {"error":"unavailable"}` | `503 {"error":"unavailable"}` |

Живые сессии продолжают работать и пока мастер не пройден: новые учётные записи в это время не создаются. Экран фрейма — единственная страница SDK, которую можно показать внутри чужого фрейма. По ссылке на нём приложение открывается в новой вкладке.

`auth.requireUser({ role: 'admin' })` пропускает только администраторов приложения, `auth.requireUser({ role: 'manager' })` — учётные записи с именованной ролью `manager` и администраторов. Роли описывает [Роли и владельцы](./operations.md#роли-и-владельцы).

### node:http

Первой строкой обработчика:

```javascript
if (await auth.handle(req, res)) return
```

`handle` возвращает `true`, если запрос был к маршруту SDK и SDK уже ответил.

### Пользователь в коде

`auth.getUser(req)` возвращает пользователя или `null`. Те же поля несёт `req.authUser`:

| Поле | Тип | Описание |
|---|---|---|
| `id` | string | Идентификатор пользователя приложения, 32 шестнадцатеричных символа |
| `name` | string | Имя, которое человек ввёл при регистрации или в «Моём аккаунте» |
| `role` | string | `admin` — администратор, который вошёл не больше 12 часов назад, иначе `user` |
| `needsReauth` | boolean | `true` — администратор, которому для прав администратора нужно войти заново |
| `roleName` | string \| null | Именованная роль учётной записи из `createAuth({ roles })` |
| `isOwner` | boolean | Владелец приложения. `true` только там же, где `role` равно `admin`: в несвежей сессии владельца — `false` |
| `ownerSince` | number \| null | Когда учётная запись стала владельцем, в unix-миллисекундах. `null` — не владелец |
| `email` | string \| null | Почта, если её запрашивает `AUTH_REQUEST_FIELDS` и сервис входа её отдал |
| `phone` | string \| null | Телефон, если его запрашивает `AUTH_REQUEST_FIELDS` и сервис входа его отдал |
| `blockedAt` | number \| null | Время блокировки в unix-миллисекундах |
| `createdAt` | number | Время создания в unix-миллисекундах |
| `lastLoginAt` | number | Время последнего входа в unix-миллисекундах |

Код, который сам сравнивает `role === 'admin'` или проверяет `isOwner`, учитывает и `needsReauth`: администратор с `needsReauth: true` получает права после повторного входа. Ведите его на `requireUser({ role: 'admin' })`, а не сравнивайте поля вручную.

При недоступном хранилище `getUser` бросает исключение, а не возвращает `null`. В `async`-обработчике без `try/catch` процесс упадёт:

```javascript
let user
try { user = await auth.getUser(req) } catch { res.statusCode = 503; return res.end() }
```

### Своя база

Пул PostgreSQL:

```javascript
createAuth({ db: { client: 'pg', pool } })
```

Пул MySQL — из `mysql2/promise`, с базой по умолчанию и кодировкой соединения `utf8mb4`. Это умолчание `mysql2`, его не меняйте:

```javascript
const mysql = require('mysql2/promise')
const pool = mysql.createPool({ uri: process.env.DATABASE_URL }) // mysql://user:password@host:3306/app
createAuth({ db: { client: 'mysql', pool } })
```

База MySQL на другой машине — включите TLS с проверкой имени сервера: без него `mysql2` передаёт данные открытым текстом. В адресе — `?ssl={"verifyIdentity":true}`, со своим центром сертификации — опцией пула `ssl: { ca, verifyIdentity: true }`. Без `verifyIdentity: true` посредник с любым доверенным сертификатом получит пароль базы. Хост в адресе — DNS-имя из сертификата, а не IP-адрес.

Отдайте SDK отдельную базу или схему и не давайте другим учётным записям прав на неё.

## Маршруты SDK

SDK обслуживает маршруты под префиксом `/_auth` и все пути админки `/_auth/admin`. Свои маршруты на этих путях не заводите: приложение их не получит. Путь под `/_auth/`, которого нет в таблице, передаётся приложению.

| Метод и путь | Назначение |
|---|---|
| `GET /_auth/login` | Вход: страница выбора способа или переход к единственному способу. Пока мастер не пройден — экран «Вход скоро откроется» |
| `GET /_auth/login/:provider` | Вход через указанный способ |
| `GET /_auth/callback/:provider` | Возврат от сервиса входа |
| `GET /_auth/register`, `POST /_auth/register` | Регистрация при первом входе: имя и согласие на обработку данных |
| `GET /_auth/consent`, `POST /_auth/consent` | Новое согласие после смены версии политики |
| `GET /_auth/invite`, `POST /_auth/invite` | Вход по приглашению из админки |
| `GET /_auth/setup-admin`, `POST /_auth/setup-admin` | Вход по ссылке установки администратора |
| `GET /_auth/reauth`, `POST /_auth/reauth` | Повторный вход той же учётной записью для прав администратора и действий в «Моём аккаунте» |
| `GET /_auth/account` | «Мой аккаунт»: имя, способы входа, устройства, согласие, выгрузка и удаление данных. Без сессии — переход на вход |
| `POST /_auth/account/*` | Действия «Моего аккаунта»: `name`, `link/:provider`, `unlink/:provider`, `devices/:id/end`, `export`, `delete` |
| `POST /_auth/logout` | Выход на этом устройстве, затем переход на `APP_URL/` |
| `POST /_auth/logout-all` | Выход на всех устройствах |
| `GET /_auth/me` | Текущий пользователь: `{"user": {...}}` или `{"user": null}` |
| `GET /_auth/status`, `HEAD /_auth/status` | Состояние входа: `{"providers": [...], "setup": true, "admin": true}` |
| `GET /_auth/icon`, `HEAD /_auth/icon` | Иконка приложения из карточки. Иконки нет — `404` |
| `/_auth/admin` и пути под ним | Админка: люди, журнал, приглашения, мастер настроек. Открывается администратору приложения |
| `GET /_auth/dev`, `POST /_auth/dev` | Вход администратором по токену из консоли. Только в режиме разработки, см. [Режим разработки](#режим-разработки) |

В ответе `/_auth/status` поле `providers` — включённые способы входа, `setup` — есть разрешённый способ входа и политика, то есть мастер пройден, `admin` — у приложения есть хотя бы один незаблокированный администратор. По этому маршруту платформа определяет [статус входа](../app-login.md#мастер-и-статусы).

`POST`-маршруты принимают запрос только со страниц самого приложения: запрос с чужим `Origin` получает `403`. `GET /_auth/me` и `GET /_auth/status` отвечают с `Cache-Control: no-store` и без заголовков CORS.

## Переменные окружения

На сервере платформы способы входа, политику обработки персональных данных и название приложения задаёт владелец в мастере настроек админки, а не переменные. Не передавайте их в `env` деплоя: переменная запирает поле мастера, оно становится «только для чтения». Исключение — идентификатор клиента `AUTH_VK_CLIENT_ID` или `AUTH_YANDEX_CLIENT_ID`, который называет блок `env` настройки входа, пока вход через Битрикс24 приложению недоступен. Его не убирайте: по нему ссылка установки администратора предлагает способ входа. Подробнее — [Админ по ссылке установки](../app-login.md#админ-по-ссылке-установки).

Автор передаёт в `env` деплоя только эти настройки:

| Переменная | Обяз. | По умолч. | Описание |
|---|---|---|---|
| `AUTH_REQUEST_FIELDS` | нет | пусто | Какие поля запрашивать у сервиса входа сверх имени: `email`, `phone` через запятую |
| `AUTH_MIGRATIONS` | нет | `auto` | `off` — не менять схему при старте, миграции запускаются командой — см. [Хранилище](./operations.md#хранилище-входа) |
| `AUTH_EVENTS_RETENTION_DAYS` | нет | `365` | Срок хранения журнала событий, от 30 до 3650 дней |

Лимиты обмена кода входа на сессию задают `AUTH_EXCHANGE_PER_CLIENT_PER_MIN` — от 1 до 600, по умолчанию `5`, `AUTH_EXCHANGE_PER_DAY` — от 10 до 100 000, по умолчанию `2000`, `AUTH_EXCHANGE_FAIL_PER_DAY` — от 10 до 100 000, по умолчанию `300`, и `AUTH_EXCHANGE_TRICKLE_SEC` — от 1 до 600, по умолчанию `10`.

Остальное задаёт платформа, пока вход включён: `APP_URL`, `AUTH_SQLITE_PATH`, `AUTH_TRUST_PROXY`, `AUTH_DB_ADMINS`, системные секреты и переменные `VIBE_*`. Деплой убирает эти имена из `env`, кроме `AUTH_SQLITE_PATH`, и сообщает о каждом в `warnings`. `AUTH_SECRET` и `AUTH_SECRET_PREVIOUS` SDK на сервере платформы не читает.

При деплое платформа заменяет все переменные приложения разом. Храните полный набор своих переменных вне каталога проекта и передавайте его целиком.

Вне платформы, например на своём сервере или локально, способы входа и политику задают и переменными: `APP_URL`, `AUTH_SECRET` — создайте его командой `openssl rand -base64 32` и храните вне каталога проекта, `AUTH_VK_CLIENT_ID`, `AUTH_YANDEX_CLIENT_ID`, `AUTH_PRIVACY_URL` — ссылка `https` на политику, `AUTH_PRIVACY_VERSION` — её версия, `AUTH_APP_NAME` — название на экранах SDK.

## Ошибки старта

Ошибка конфигурации останавливает старт и перечисляет все проблемы сразу, по именам переменных и без значений:

```
AuthConfigError: vibecode-auth: configuration is invalid:
- VIBE_AUTH_SECRET is missing: turn sign-in on in the dashboard
```

| Строка ошибки | Причина |
|---|---|
| `VIBE_AUTH_SECRET is missing: turn sign-in on in the dashboard` | Приложение на сервере платформы, а вход не включён. Включите вход и повторите деплой |
| `APP_URL points to this machine while VIBE_RUNTIME is set` | На сервере платформы в `APP_URL` адрес этой машины, например `localhost` |
| `APP_URL is required: the public origin of the app, like https://host` | Не задан `APP_URL`. Вне платформы |
| `APP_URL must use https (http is allowed only for localhost, 127.0.0.1 and [::1])` | `APP_URL` начинается с `http://`, а хост не локальный |
| `APP_URL uses http while NODE_ENV=production: development mode is not allowed in production` | Адрес `http://localhost` при `NODE_ENV=production` |
| `AUTH_SECRET is required (create it with: openssl rand -base64 32)` | Вне платформы и вне режима разработки не задан `AUTH_SECRET` |
| `AUTH_SECRET must be at least 43 characters (create it with: openssl rand -base64 32)` | Секрет короче 43 символов |
| `AUTH_SECRET has too little variety of characters (create it with: openssl rand -base64 32)` | Секрет нужной длины, но из повторяющихся символов |
| `AUTH_PRIVACY_VERSION must not contain control characters` | В версии политики табуляция или перевод строки |
| `AUTH_ADMINS must list <provider>:<id> keys of this build's providers, comma-separated` | В `AUTH_ADMINS` неизвестный сервис входа или неверный формат |
| `AUTH_SQLITE_PATH needs AUTH_SECRET: without a secret development mode keeps the store in memory` | В режиме разработки задан путь к файлу SQLite без `AUTH_SECRET` |
| `createAuth() already read the secrets and removed them from process.env: call it once per process, or pass env` | `createAuth()` вызван второй раз в том же процессе |
| `the store mark does not match VIBE_AUTH_SECRET (store_id …)` | Хранилище создано не под секретом этого приложения — см. [Хранилище](./operations.md#хранилище-входа) |

Пока мастер не пройден, приложение стартует без ошибки. Вне платформы SDK печатает в консоль строку `vibecode-auth: sign-in is not open yet (no sign-in method or no privacy policy)` и имена переменных, которые открывают вход.

## Режим разработки

Локально `APP_URL` может быть `http://localhost:<порт>`, `http://127.0.0.1:<порт>` или `http://[::1]:<порт>`. Режим включается, когда `NODE_ENV` не равен `production` и в окружении нет `VIBE_RUNTIME` и переменных платформы `VIBE_*`. Свои переменные с префиксом `VIBE_`, например `VIBE_API_KEY`, режим не выключают. В этом режиме:

- без `AUTH_SECRET` SDK берёт временный секрет и хранит всё в памяти: после перезапуска данных нет,
- с `AUTH_SECRET` и без `AUTH_SQLITE_PATH` файл SQLite создаётся в `~/.vauth/` под именем из первых 12 шестнадцатеричных символов SHA-256 от пути проекта, поэтому у каждого проекта на машине своё хранилище,
- куки ставятся без префикса `__Host-` и без `Secure`,
- работает вход администратором без сервиса входа.

Для входа администратором SDK печатает в консоль одноразовый токен:

```
vibecode-auth dev sign-in token: <токен>
```

Откройте `<APP_URL>/_auth/dev` и вставьте токен в форму — SDK создаст учётную запись «Разработчик» со способом входа `dev:local` и правами администратора. Пока мастер не пройден, SDK ведёт её в мастер настроек `/_auth/admin/settings`, после — на `APP_URL/`. Каждый токен работает один раз, после входа SDK печатает новый. Неверный токен получает `404`.

Открывайте `APP_URL` напрямую: запрос через туннель или прокси, с другой машины или с другим `Host` получает `404`. Прокси фронтенда в режиме разработки, который добавляет заголовки `X-Forwarded-*`, тоже получает `404`. Вне режима разработки маршрута `/_auth/dev` нет.

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

- [Вход пользователей приложения](../app-login.md)
- [Обслуживание входа](./operations.md)
- [Секреты приложения](../app-secrets.md)
- [Galaxy-приложение](/docs/infra/galaxy)
- [Полный деплой приложения](/docs/infra/deploy/deploy)
