# ADR-0018. Плоскость участника и встраиваемые виджеты

- Статус: принято; реализовано на этапе 6 — ✅ 6j-1 (сеансы участника, их выпуск через Management API, API участника,
  CORS), ✅ 6j-2 (клиент участника в PHP и TypeScript SDK), ✅ 6j-3 (веб-компоненты, раздел «Виджеты» кабинета
  партнёра)
- Дата: 2026-10-13

## Контекст

Партнёр встраивает лояльность в свой продукт: на сайте или в личном кабинете мерчанта участник видит свои баллы,
уровень, историю и показывает на кассе код (п. 6.5 roadmap: «партнёр встраивает виджет участника»). Сейчас это может
только сервер сайта ключом кассы (Runtime API) — значит, каждый партнёр пишет свой прокси между страницей и
платформой. Ключ кассы на странице держать нельзя: он видит всех участников программы, а с `receipts` ещё и проводит
чеки. Нужен доступ, который страница может держать в браузере: одного участника, одного сайта, на короткое время и
только на чтение того, что участник и так видит.

## Решение

### Сеанс участника

- Сеанс `lms_<префикс>.<секрет>` (в песочнице `lms_test_…`, ADR-0012): 12 символов публичного префикса и 256 бит
  секрета, хранится только SHA-256 секрета с маркером окружения (`member_sessions`, RLS). Сеанс принадлежит одному
  участнику одной программы и одному сайту (`origin`), живёт 60–3600 секунд (по умолчанию 900) и не продлевается:
  страница просит у своего бэкенда новый.
- Сеанс помнит учётные данные, которые его открыли: ключ мерчанта или OAuth-клиента партнёра по публичному
  идентификатору (как ключи касс), ровно одно из двух. Сеанс работает, пока они действуют: отзыв клиента или ключа
  мерчанта, истечение ключа останавливают его сеансы, — утёкший ключ не оставляет после себя работающих сеансов.
- Сеанс находят до выбора тенанта узкой функцией SECURITY DEFINER `member_session_candidates` (ADR-0002): точное
  совпадение префикса, со статусом мерчанта и статусом учётных данных, открывших сеанс, без отозванных. Результат
  кэшируется на минуту простыми значениями; срок сеанса и ключа мерчанта сверяется с часами на каждом запросе. Закрытый
  мерчант и отозванные учётные данные останавливают сеансы в пределах минуты, приостановленный мерчант — нет: виджеты,
  как и кассы, работают (ADR-0015).
- Отзыв (`MemberSessions::revoke`, `revokeAllOf`) действует сразу: забывает кэш префикса и после коммита ставит метку,
  которая переживает ответ, прочитанный до отзыва (как у ключей касс). Неизменно всё, кроме `last_used_at` (пишется не
  чаще раза в пять минут) и `revoked_at`. Через сутки после истечения сеансы удаляет `member-sessions:prune` (системная
  роль, раз в сутки).
- Участника и его состояние сеанс не хранит: API участника проверяет его на каждом запросе. Заблокированный или
  анонимизированный участник, участник другой программы получает 401 `unauthenticated`, что бы ни говорил сеанс, — на
  всё, кроме закрытия сеанса: закрыть его можно всегда.

### Выпуск: Management API

- `POST /api/management/v1/member-sessions` — новый скоуп `widgets`, обычная цепочка middleware, нужен мерчант.
  Бэкенд сайта, где участник вошёл, называет программу (только активную), участника (`member_id` или `external_id`
  мерчанта), сайт и скоупы; ответ 201 `{id, token, expires_at, member_id, scopes}` — токен только в нём.
  Заблокированному участнику — 409 `member_blocked`, анонимизированный не найден.
- Скоупы сеанса: `profile` и `history` (по умолчанию) и `presentation_code`. Код участника касса принимает как
  сильный идентификатор и при настройке программы по умолчанию списывает баллы без кода подтверждения (ADR-0009),
  поэтому `presentation_code` дают только учётные данные, у которых есть и `members`; иначе 403 `scope_missing`.
- `widgets` — доступ к данным участников (сеанс читает профиль и историю), поэтому разработчик партнёра его не выдаёт,
  как не выдаёт `members` и `audit` (ADR-0013, потолок роли в «Ключах доступа»).
- `POST /api/management/v1/member-sessions:revoke` закрывает все действующие сеансы участника (вышел везде, потерял
  телефон); и сеансы заблокированного участника. Оба метода работают и у приостановленного мерчанта
  (`RequireMerchant::WRITES_WHILE_SUSPENDED`: открытие не защищает, но виджеты работают, как кассы). Оба пишутся в журнал
  аудита (`member-sessions.store`, `member-sessions.revoke`) как любое изменение: объект записи — участник
  (`RecordAudit::SUBJECT`, его не назвал бы скрытый в журнале `external_id`) и открытый сеанс; токен в журнал не
  попадает.

### API участника

- Третья плоскость: `/api/member/v1`, спецификация `docs/api/member-v1.yaml` (схема безопасности `memberSession`),
  маршруты — в модуле `processing` (`routes/member-routes.php`). `GET /me` — маскированный профиль, баланс, уровень с
  прогрессом, штампы, код «приведи друга» (`profile`); `GET /me/history` — история баллов с курсорами (`history`);
  `POST /me/presentation-codes` — код на две минуты и его QR-код (`loyal:<код>`, как читает касса, ADR-0016) SVG-картинкой
  в data-адресе для `<img src>`, не разметкой страницы (`presentation_code`); `DELETE /session` — страница закрывает
  свой сеанс (любые скоупы). Ответы участника — те же, что у Runtime API (`MemberJson`).
- Middleware `member.session:<скоупы>`: Bearer-токен, затем **обязательный** заголовок `Origin`, равный сайту сеанса
  (`origin_mismatch` 403, в том числе без заголовка), затем скоупы; делает тенант сеанса текущим. Сайт записывается так,
  как браузер шлёт `Origin` (`SiteOrigin`): схема и хост в нижнем регистре, порт — если не стандартный; только https,
  кроме `localhost`, `127.0.0.1` и `[::1]` для разработки; путь, запрос, учётные данные, не-ASCII-хост — отказ 422
  `invalid_member_session`; домен на кириллице записывается в punycode, как его шлёт браузер. Браузер ставит `Origin`
  сам на каждый запрос к другому сайту и не даёт странице его
  подменить: привязка не даёт страницам других сайтов пользоваться сеансом в браузере. От кражи токена (вне браузера
  `Origin` подделывается) защищают короткая жизнь сеанса и узкие скоупы.
- Лимит `throttle:member`: 60 запросов в минуту на участника — со всеми его сеансами, ведь сайт открывает их сколько
  попросит страница, — и 6000 на мерчанта (`access.member_rate_limits`).
- Идемпотентности в плоскости нет: новый код — просто новый код; закрытый сеанс на повторное закрытие получает 401,
  для страницы это «уже закрыт».

### CORS

- `config/cors.php`: Runtime API (`api/v1/*`) и API участника (`api/member/v1/*`) отвечают на запросы страниц любых сайтов
  (`*`) без cookie (`supports_credentials = false`), открывают `X-Request-Id`, `Retry-After`, `RateLimit-*`,
  `Idempotent-Replayed`, `Loyal-Environment`, preflight кэшируется 10 минут. До этого действовали значения фреймворка
  (`api/*`), и CORS получал и Management API.
- Management API — для серверов: браузерам других сайтов оно не отвечает CORS-заголовками, и страница не прочитает его
  ответ даже с чужим токеном. Тест закрепляет обе стороны.

### Веб-компоненты

- `<loyal-member-card>`, `<loyal-points-history>`, `<loyal-presentation-code>` (`frontend/widgets`, TypeScript без
  зависимостей и без неудаляемого синтаксиса, как у кассы, ADR-0016) поверх клиента участника TypeScript SDK, чьи
  исходники они берут по относительному пути. Руководство для партнёров — `docs/api/widgets.md`, код для страницы —
  раздел «Виджеты» кабинета партнёра.
- **Сборка — один модуль на версию:** `public/embed/v1/<версия>/loyal-widgets.js`, версия — 12 знаков SHA-256 файла;
  `public/embed/v1/build.json` называет сборку исходников и её integrity (SHA-384). Компилятор TypeScript из SDK
  проверяет типы и компилирует модули в памяти, `frontend/widgets/bundler.mjs` складывает их в один файл — каждый в
  своей функции, в порядке импортов, его импорты — константами в её начале, — чтобы одна integrity (SRI) покрывала весь
  код: страница партнёра закрепляет версию с ней. Исходники держатся того, что это позволяет (именованные относительные
  импорты, экспорт функций, классов, констант и имён неизменяемых привязок, без циклов, без `import()` и `await` на
  верхнем уровне, `import.meta` только в точке входа); остальное сборка отвергает.
- **Сборки хранятся в git:** опубликованная — закоммиченная — версия не меняется и не удаляется, иначе страницы,
  закрепившие её с integrity, перестанут работать. `composer widgets:build` добавляет сборку (и удаляет сборки, которых
  нет в git: их никто не закрепил), `composer widgets:test` и CI падают, пока `public/embed/v1` не хранит сборку
  исходников, а тест платформы (`tests/Architecture/WidgetBuildsTest.php`) читает историю git и рабочее дерево: ни один
  коммит не меняет, не переносит и не удаляет закоммиченную сборку. Изменения SDK, которые попадают в виджеты, дают
  новую версию.
- **Раздача — статикой веб-сервера** с `Access-Control-Allow-Origin: *` (модуль и SRI — запросы CORS),
  `Cross-Origin-Resource-Policy: cross-origin` и вечным кэшем папок версий; настройки nginx и Apache — в руководстве.
- **Сеанс — от сайта:** свойство `tokenProvider` — функция, которая даёт токен `lms_…` (или `null`, если сеанса для
  страницы нет), а сбой сообщает исключением; виджеты с одной функцией и одним API делят один клиент участника, то есть
  один сеанс, а клиент сам заменяет отвергнутый сеанс (ADR-0011). Сеанс живёт только в памяти. Когда сеанса нет и
  функция нового не дала (или API отверг только что данный), виджет пишет «Войдите на сайте» и шлёт всплывающее событие
  `loyal-session-expired` (`detail.reason`: `signed_out` или `rejected`). `endSession()` — участник вышел — сразу, без
  события, убирает его данные из всех виджетов сеанса (можно и с виджета, которого уже нет на странице) и закрывает
  сеанс в API; начинается новое поколение сеанса: ни клиент прежнего, ни его запрос профиля или вызов функции в пути,
  ни сеанс, который его клиент продлил бы, виджетам больше не служат, даже если закрытие в API не удалось. `refresh()`
  показывает данные заново с прежним сеансом: смену пользователя сайт делает через `endSession()`.
- **Адрес API** — сайт, с которого загружен скрипт (`import.meta.url`), или свойство `api` из скрипта страницы — не
  атрибут: виджет отдаёт этому адресу сеанс участника, а разметку на странице мерчанта может вставить и чужой.
- **Безопасность страницы:** открытый Shadow DOM, элементы создаются методами DOM — тексты, в том числе имя участника и
  тексты сайта, только текстовыми узлами; QR-код — `<img>` с data-адресом SVG, и виджет проверяет, что это именно он
  (странице нужен `img-src data:`). Стили — одна общая constructable stylesheet для всех теней: политике страницы не
  нужен `style-src 'unsafe-inline'` (браузеру без таких таблиц — `<style>`). Код живёт две минуты API с выдачи, а
  выдают его после отправки запроса: виджет считает две минуты от отправки по собственному времени устройства, не по
  `expires_at`, так что неверные часы телефона не показывают код дольше, чем он работает.
- **Оформление:** переменные `--loyal-*` и части `::part()`, тексты по-русски с заменой любого из них свойством
  `texts`; ключи, переменные и части перечисляет руководство, тест сверяет его таблицы с кодом. Карта говорит с
  участником, а не как кабинет: участнику с приостановленным списанием — «Баллы на счёте» (API считает его баллы
  доступными, тратить их не даёт касса), штампы — до следующей бесплатной единицы и сколько бесплатных уже можно
  получить (касса даёт одну за каждые `goal` штампов).
- **Демо на машине разработчика:** `LocalWidgetsSeeder` (ключ сайта демо-мерчанта) и страница `/widgets-demo`
  (только окружение `local`) — сайт на адресе петли `127.0.0.1` или `[::1]`, чьи виджеты говорят с API на `localhost`, со
  своей строгой политикой и сеансом от своего бэкенда.

## Поправка 7e-1 (ADR-0021)

- Сеанс участника открывает и сеанс кабинета покупателя (`issued_by_portal_session_id`, ровно один из трёх
  открывающих): кабинет — сайт, бэкенд которого — платформа. Выход из кабинета сразу закрывает выданные им сеансы.
- Запрос страницы того же хоста, что и API, без `Origin` (браузер не шлёт его в GET своего хоста) принимается, когда
  браузер сам называет его запросом того же источника (`Sec-Fetch-Site: same-origin`) и хост API — сайт сеанса;
  `Origin`, если он есть, по-прежнему должен совпадать с сайтом. Так приложение кабинета обращается к API на своём хосте.

## Поправка 7e-3 (ADR-0021)

- Участник меняет данные о себе сам: скоуп `details` — имя и фамилия, день рождения, пока он не известен
  (`GET`/`PATCH /me/details`); скоуп `consents` — согласия: список с действующими документами и что дано
  (`GET /me/consents`), дать согласие на рекламу к версии, которую участник видел, или отозвать его
  (`PUT /me/consents/{kind}`). Изменения задают состояние, повторы ничего не добавляют.
- Оба скоупа меняют данные участника, поэтому Management API даёт их, как `presentation_code`, только учётным данным со
  скоупом `members`; кабинет покупателя даёт их своей странице.
- Сеанс знает, кто его открыл (`MemberSessionOpener`: ключ мерчанта, клиент партнёра, кабинет покупателя) и какими
  учётными данными: согласие записывается с каналом `portal` или `website`, а в доказательствах — сеанс, открывший и его
  id (они переживают сеанс), сайт и адрес. Изменений участника — 30 в час.

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

- Партнёр встраивает виджет без своего прокси: бэкенд сайта один раз открывает сеанс, остальное страница делает сама.
- Украденный токен работает до конца сеанса (не больше часа) и только для одного участника: на чтение его данных, со
  скоупом `presentation_code` — на коды для кассы, со скоупами `consents` и `details` — на его согласия на рекламу, имя
  и день рождения, пока тот не известен (не больше 30 изменений в час); закрыть его можно сразу (`DELETE /session` или
  `member-sessions:revoke`).
- Страница того же хоста, что и API, не шлёт `Origin` на GET и сеансом не пользуется: виджеты обращаются к API на его
  собственном хосте.
- Каждый запрос плоскости читает участника и правила программы: нагрузка — как у запроса баланса ключом кассы.
- Запросы без действующего сеанса приложение не ограничивает, как и в Runtime API: поиск — один индексный запрос, его
  ответ кэшируется минуту. Лимит по адресу здесь вредил бы: за одним адресом мобильного оператора — тысячи участников.
  От потока таких запросов защищает входной шлюз (WAF, лимиты балансировщика).
- SDK (6j-2) получили клиент участника (`MemberClient`, ADR-0011): поставщик сеансов заменяет истёкший сеанс, сайт
  сеанса вне браузера уходит в `Origin`. Веб-компоненты (6j-3) — `<loyal-member-card>`, `<loyal-points-history>`,
  `<loyal-presentation-code>` поверх него.
- Партнёр встраивает виджеты кодом из кабинета и одним обработчиком на бэкенде сайта. Каждая версия виджетов остаётся в
  репозитории навсегда: файлы маленькие, но их число растёт с каждым изменением виджетов и попадающих в них частей SDK.
- История баллов знает знаки после запятой только из профиля, поэтому её виджету нужен и скоуп `profile` (у сеанса по
  умолчанию он есть): страница истории в API — `{data, next_cursor}`, как все страницы (ADR-0006).
- Раздачу `/embed/` с заголовками CORS настраивает развёртывание (этап 11); без них скрипт не загрузится на чужом сайте.
