# ADR-0029. Роль БД для публичного трафика

- Статус: принято; этап 11 — 11.4-1
- Дата: 2026-11-11

## Контекст

Остаточный риск ADR-0002 и ADR-0013: у runtime-групп по умолчанию есть права на все таблицы, в том числе на глобальные
таблицы сотрудников. SQL-инъекция в публичном API теоретически могла бы прочитать или изменить учётную запись
сотрудника, его сессию или членство в команде, а через таблицу очереди — поставить задачу, которую выполнит воркер.
Отозвать права у той же роли нельзя: кабинетам они нужны (вход сам пишет в `users`). Нужна отдельная роль для
публичного трафика — пункт 11.4 roadmap.

Публичный трафик — это всё, что обслуживает не сотрудников:

- Runtime API (`/api/v1`), Management API (`/api/management/v1`) и member plane (`/api/member/v1`);
- кабинет покупателя (`/p/…`, `/u/…`, `/r/…`, `/m/…`, рамка капчи `/box`);
- веб-касса (`/till`) на собственном хосте (`TILL_DOMAIN`). Без него оболочка живёт на хосте кабинетов, где привязка
  браузера завершает сеанс кабинета в нём (ADR-0016), и обслуживается вместе с кабинетами;
- вебхуки MAX, ВКонтакте и Tilda (`/hooks/…`), решение и кассы МоегоСклада (`/moysklad/…`);
- проба здоровья `/up` и корневая страница — их отвечают поды обеих сторон.

Кабинеты — `/console`, `/merchant`, `/partner`, `/filament/…` и Livewire (`/livewire-…`). Список путей —
`Modules\Kernel\Traffic\PublicTraffic`; архитектурный тест `tests/Architecture/PublicTrafficTest.php` не пропускает
маршрут, который не отнесён ни к одной стороне.

## Решение

- Новая групповая роль `loyal_rls_staff` (`Rls::STAFF_ROLE`) получает таблицы и функции, нужные только сотрудникам, —
  ровно с теми правами, которые были у `loyal_rls_tenant` (`Rls::moveRights()`): право, которое миграция таблицы
  отняла у runtime-ролей (удаление истории доступа поддержки), не возвращается. У `loyal_rls_tenant` эти права
  отзываются. Политики RLS не меняются: они по-прежнему для `loyal_rls_tenant`.

  | Логин | Кто им работает | Группы |
  |---|---|---|
  | логин кабинетов и воркеров (`loyal_app`) | кабинеты, консоль, очереди, планировщик | `loyal_rls_tenant`, `loyal_rls_staff` |
  | логин публичного трафика | API, портал, веб-касса на своём хосте, вебхуки, МойСклад | только `loyal_rls_tenant` |
  | `loyal_system`, `loyal_owner` | системные процессы, миграции | `loyal_rls_system` |

- Только сотрудникам (`Rls::staffOnly()`, список с причинами — `tests/Architecture/StaffDataTest.php`):
  - учётные записи сотрудников и всё о них: `users`, `sessions`, `staff_sessions`, `platform_staff`,
    `tenant_memberships`, `partner_memberships`, `staff_invitations`, `tenant_invitations`, `user_security_events`,
    `support_access_grants`, подписки на отчёты `report_subscriptions`;
  - работа платформы: `health_reports`, `scheduled_runs`, `platform_heartbeats`;
  - таблицы фреймворка: `cache`, `cache_locks`, `jobs`, `job_batches`, `failed_jobs`, `migrations`. Задачу из `jobs`
    выполнил бы воркер с правами сотрудников, поэтому кэш, очередь и сессии публичного трафика — не в базе.
- Только читает публичный трафик (`Rls::staffWrites()`): выключатель всех сообщений `communication_switches`. Его
  ставит консоль, а правила сообщений мерчанта в Management API его показывают.
- Функции SECURITY DEFINER работают с правами владельца, кто бы их ни вызвал, поэтому функции членств и приглашений
  (`staff_tenant_memberships`, `staff_sole_owner_tenants`, `tenant_invitation_candidates`,
  `revoke_tenant_invitations_to`) — только для `loyal_rls_staff` (`Rls::staffFunction()`). Функции поиска до выбора
  тенанта (`api_key_candidates`, `portal_address`, `tilda_site_tenant` и другие) остаются у `loyal_rls_tenant`.
- Новая таблица по умолчанию достаётся `loyal_rls_tenant` (default privileges). Таблица сотрудников в своей миграции
  вызывает `Rls::staffOnly()` и попадает в список теста; тест сверяет права в базе со списком, а права роли сотрудников —
  с правами системной роли: новая таблица модуля identity без этого не пройдёт.
- У публичного трафика нет логинов системной роли и владельца схемы. Журнал аудита партнёра (записи без тенанта),
  который Management API отдаёт ключам партнёра, раньше читался системным соединением. Теперь — через представление
  `partner_audit_entries` владельца схемы (`security_barrier`): оно отдаёт записи партнёра без тенанта, пока транзакция
  называет партнёра в настройке `app.partner_id` (`AuditService::ofPartner`), а у записей операторов платформы — без
  `actor_id`, адреса и браузера, как их показывает журнал партнёра. Таблицу записей без тенанта роль тенанта
  по-прежнему не читает. Собственные записи платформы консоль читает системным соединением.
- Письма владельцам, которые вызывает публичный трафик (остановка кодов и их скорое окончание, «Не вы?» из
  уведомления о списании, подключение МоегоСклада), ставятся в очередь (`TellMerchantOwners`, зашифрованная задача).
  Владельцев находит воркер, логин публичного трафика членств и учётных записей не читает. Сбой поиска владельцев валит
  задачу, и очередь повторяет её (три попытки): это единственное предупреждение владельцев о чужом подключении. Такие
  уведомления больше не возвращают число получателей. Уведомления консоли отправляются сразу и это число возвращают.
- Под знает свою сторону — `LOYAL_TRAFFIC` (`TrafficSide`): `public`, `staff` или `all` (один логин на всё —
  машина разработчика, тесты). Неизвестное значение останавливает приложение. Неверное развёртывание падает сразу:
  - под публичного трафика отвечает 404 на пути кабинетов, под кабинетов — на пути публичного трафика, кроме корня и
    `/up` (`KeepTrafficToItsSide`): ошибка ingress не обслуживает запрос с правами другой стороны;
  - на поде публичного трафика у системного соединения, соединения владельца и суперпользователя нет пригодного
    логина, что бы ни дало окружение (`PublicTrafficLogin::keepOtherLoginsOff`);
  - каждый открытый им сеанс БД проверяет, что логин не член `loyal_rls_staff` и `loyal_rls_system`;
  - он не стартует с кэшем, очередью или сессиями в базе и с очередью, которая выполняет задачи сразу (`sync`); под
    кабинетов — с кэшем или очередью в базе (`PublicTrafficLogin::assertStores`).
- `php artisan db:bootstrap` (локально и в CI) создаёт `loyal_rls_staff` и выдаёт её логину приложения; миграция
  `2026_12_19_000100_keep_staff_data_from_public_traffic` без этой роли останавливается с подсказкой. В продакшене роль,
  её членство у логина кабинетов и воркеров и отдельный логин публичного трафика создаёт инфраструктурный код (этап
  11.2) до этой миграции.

## Развёртывание (этапы 11.1–11.2)

- Поды публичного трафика и поды кабинетов — один образ с разными переменными окружения. Ingress направляет пути
  публичного трафика и хосты `PORTAL_DOMAIN`, `PORTAL_CAPTCHA_DOMAIN`, `TILL_DOMAIN` в поды публичного трафика, а
  `CONSOLE_DOMAIN` и пути кабинетов — в поды кабинетов. Веб-касса в продакшене — на своём хосте (`TILL_DOMAIN`).
- Поды публичного трафика: `LOYAL_TRAFFIC=public`, `DB_USERNAME` — логин публичного трафика, без `DB_SYSTEM_*`,
  `DB_OWNER_*` и `DB_SUPERUSER_*`, `SESSION_DRIVER` — Redis. Поды кабинетов, воркеры и планировщик:
  `LOYAL_TRAFFIC=staff`, логин кабинетов.
- Кэш и очередь у всех подов — один и тот же Redis: то же соединение, номер базы и префикс (`REDIS_PREFIX`,
  `CACHE_PREFIX`, `APP_NAME`). Иначе задачи публичного трафика (письма владельцам) ждали бы в очереди, которую никто не
  читает, а лимиты запросов к провайдерам (`RequestLimits`) считались бы порознь.

## Проверка

- Тесты выполняют каждый запрос публичного трафика с правами его логина (`Tests\TestCase::call()`,
  `Tests\Support\PublicTrafficRole`): на время запроса соединения приложения делают `set role loyal_rls_tenant`, а
  запрос через системное соединение или соединение владельца валит тест. Задачи, поставленные в очередь во время
  запроса, ждут его конца и выполняются с правами приложения, как их выполнил бы воркер (`PublicTrafficQueue`), с
  тенантом, который несёт их полезная нагрузка. Задачи, которые запрос выполняет сам, в том числе после ответа,
  выполняются с правами публичного трафика. Мета-тесты обвязки — `tests/Feature/PublicTrafficRoleTest.php`.
- Архитектурные тесты: `StaffDataTest` (права ролей на таблицы, последовательности и функции),
  `PublicTrafficTest` (каждый маршрут отнесён к одной из сторон); тесты сторон — `TrafficSideTest` ядра.

## Последствия

- SQL-инъекция в публичном трафике не достаёт ни учётных записей сотрудников, ни их сессий и членств, ни задач
  воркеров, ни данных работы платформы. Данные тенантов защищает RLS, как и раньше.
- Новый код публичного трафика, которому понадобятся данные сотрудников, получает их через очередь или через
  контракт, который работает в кабинетах. Тест, который проходит через HTTP, сразу покажет такое обращение.
- Остаточные риски:
  - записи аудита о действиях операторов внутри мерчанта (доступ поддержки) роль тенанта читает в его тенанте, как
    и раньше, вместе с адресом и браузером оператора — их скрывает только приложение. Закрыть это можно таким же
    представлением для записей мерчанта;
  - настройки `app.tenant_id` и `app.partner_id` ставит сам логин, поэтому против SQL-инъекции RLS не граница между
    тенантами (так было и раньше; граница здесь — данные сотрудников);
  - учётные данные Redis у подов публичного трафика позволяют поставить задачу, которую воркер выполнит с логином
    кабинетов: это защита от SQL-инъекции, не от захвата пода; ACL Redis по префиксам сузили бы и это;
  - потоки, которые тесты проходят прямыми вызовами сервисов, а не HTTP, с правами публичного трафика не проверяются;
  - локально один логин обслуживает и кабинеты, и публичный трафик; разницу проверяют тесты и `LOYAL_TRAFFIC`.
