transcriber/openspec/changes/archive/2026-08-12-oidc-login/design.md

## Context

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

Решение от 2026-08-11 (`ADR-2026-08-11-pocketbase-storage-with-admin-panel`)
назвало способ: **ответ провайдера разбирает хранилище, а не наш код**. У
коллекции пользователей включается провайдер `oidc` с адресами Authelia, учётные
записи заводятся сами, и панель их видит. Проверено на версии 0.39.10 —
`docs/research/pocketbase.md`, раздел «Пользователи — только те, кого туда
положат».

**Способ остаётся верным, но его механика уже проверена по исходникам
библиотеки, и три ожидания постановки она не подтверждает.** Проверено чтением
`pocketbase@v0.39.10`:

1. **Куки библиотека не читает вовсе.** Сессию она берёт единственным способом —
   заголовком `Authorization` (`apis/middlewares.go`, `getAuthTokenFromRequest`).
   Критерий приёмки задачи написан про куку.
2. **Эндпоинта выхода библиотека не приносит.** Список её адресов
   аутентификации — `auth-methods`, `auth-refresh`, `auth-with-password`,
   `auth-with-oauth2`, `request-otp`, `auth-with-otp`, восстановление пароля,
   подтверждение почты и смена почты (`apis/record_auth.go`). Выхода среди них
   нет.
3. **Браузерный вход по редиректу библиотека своим не приносит.** Она приносит
   обмен уже полученного кода: `POST /api/collections/{c}/auth-with-oauth2`
   требует `provider`, `code`, `codeVerifier` и `redirectURL`. Её собственный
   `/api/oauth2-redirect` служит другому: он ищет клиента realtime-подписки по
   параметру `state` и отдаёт код туда (`apis/record_auth_with_oauth2_redirect.go`)
   — это механика её JS-клиента с всплывающим окном, а не серверный вход.

Отсюда объём: инициировать вход, принять возврат и завести куку — наш код.
Разбор ответа провайдера, заведение учётной записи и связь с внешним провайдером
остаются за хранилищем, как и решено. Решение 2026-08-11 не пересматривается.

## Goals / Non-Goals

**Goals:**

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

**Non-Goals:**

- владелец у записи и сужение выборки по нему — задача `record-ownership`;
- вход для программ по личным токенам — отдельная цель роадмапа. Внешняя
  программа, ходившая в API анонимно, этим изменением ломается намеренно, и
  замены ей здесь не появляется;
- белый список Telegram — живёт до `telegram-account-link`;
- панель администратора — в неё провайдер не пускает, наружу её закрывает
  обратный прокси;
- своя страница входа со скриптом: у сервиса нет фронтенда, и заводить его ради
  входа незачем.

## Decisions

### Сессия предъявляется кукой, а заголовок остаётся внутренним

**Выбрано:** наш обработчик возврата ставит куку `HttpOnly`, `Secure`,
`SameSite=Lax` со значением, выданным хранилищем. Промежуточный слой перед
проверкой перекладывает значение куки в заголовок `Authorization`, если заголовка
нет. Дальше работает штатная проверка библиотеки.

Человек увидит обычный вход: перешёл, авторизовался у Authelia, вернулся —
работает. Ни строки скрипта на его стороне.

Отвергнуто:

- **заголовок `Authorization` как единственный способ.** Это механика библиотеки
  и путь наименьшего кода, но браузер такой заголовок сам не шлёт: понадобился
  бы свой фронтенд, который держит значение и подставляет его. Фронтенда у
  сервиса нет, а заводить его ради входа — работа шире задачи. Критерий приёмки
  задачи вдобавок написан про куку;
- **своя таблица сессий.** Даёт полный контроль над выходом и сроком, но заводит
  второй способ делать то, что хранилище уже делает, — и второй дом для факта
  «кто вошёл». Отвергнуто по концептуальной целостности.

Заголовок при этом остаётся рабочим: его требуют собственные адреса
аутентификации хранилища, и глушить их значит ломать библиотеку изнутри. Это
осознанно оставленная вторая дверь, и она названа в спеке.

### Форма решения выбрана из трёх, а не из одной

Прежде трёх решений ниже — выбор самой формы. Рассматривались три.

**A — свой тонкий слой входа поверх хранилища.** Выбрана. Наш код ведёт флоу и
ставит куку, обмен кода и заведение учётной записи остаются за хранилищем.
Цена: сверка состояния и установка куки — наша ответственность, то есть ошибки
в чувствительном месте наши.

**B — вход целиком на обратном прокси.** Authelia стоит перед сервисом и не
пускает неузнанные запросы, приложение доверяет заголовку от прокси. Нашего кода
почти ноль. Отвергнуто по трём причинам сразу: при прямом обращении к порту
заголовок подделывает кто угодно в той же сети, а сервис не имеет способа
отличить прокси от постороннего; учётные записи в панели не появляются вовсе, а
решение 2026-08-11 требует обратного; вход для программ по личным токенам из
этой формы не вырастает — его пришлось бы делать заново и мимо.

**C — фронтенд и штатный клиент хранилища.** Своя страница, всплывающее окно,
подписка, значение сессии в хранилище браузера. Всё штатно для библиотеки.
Отвергнуто: у сервиса нет фронтенда, и заводить его ради входа — работа шире
задачи; значение сессии становится доступно скриптам страницы, то есть XSS
уносит сессию целиком, тогда как кука с запретом чтения скриптом этого не даёт.

### Вход и возврат ведёт наш код, разбор ответа — хранилище

**Выбрано:** три своих адреса — начало входа, возврат от провайдера, выход.
Начало входа заводит `state` и PKCE-verifier, кладёт их во временную куку и
уводит человека на `authURL` провайдера. Возврат сверяет `state`, а код отдаёт
хранилищу вызовом его же обмена — тем, что стоит за `auth-with-oauth2`.

**Обмен кода библиотека наружу не отдаёт** — он живёт неэкспортированной
функцией за собственным адресом хранилища. Решением владельца от 2026-08-12
обработчик возврата зовёт **этот адрес внутри процесса**, через роутер
хранилища, а не по сети.

Цена названа и принята: получается петля «наш обработчик → наш роутер → наш
обработчик», ответ разбирается текстом, а типизированная ошибка теряется.
Взамен решение 2026-08-11 соблюдается дословно — разбор ответа провайдера
остаётся за хранилищем, и учётные записи видны в панели.

Отвергнуто:

- **собрать обмен своими руками** из кусков, которые библиотека всё же отдаёт.
  Прямой код без петли, но разбор ответа провайдера переезжает к нам — это
  пересмотр решения 2026-08-11 отдельным ADR, и владелец его не выбрал;
- **всплывающее окно и realtime-подписка**, как делает JS-клиент библиотеки.
  Работает без нашего кода вовсе, но требует того самого фронтенда и держит
  открытым realtime-соединение ради одного входа.

### Кого пускать, решает провайдер, а не сервис

Решением владельца от 2026-08-12 сервис своей проверки допуска **не делает**:
кто допущен, определяет правило Authelia на этого клиента. Всякий, кого
провайдер пропустил, получает учётную запись и доступ.

Цена принята и обязана быть записанной: правило живёт вне репозитория, в
настройках выкладки, и сервис на него полагается так же, как полагается на
обратный прокси в части панели администратора. Настроенный слишком широко
клиент открывает сервис всем, у кого есть учётная запись в общей Authelia, — и
проверить это по коду нельзя. Строка об этом идёт в `docs/security.md`, раздел
«Что разграничивает доступ».

Отвергнуто: **проверка группы своим кодом** — защита стояла бы в сервисе и не
зависела от настройки контура, но владелец выбрал не заводить второе место, где
решается допуск.

### Выход обесценивает выданные сессии, а не только убирает куку

**Выбрано:** выход обновляет ключ токенов учётной записи
(`Record.RefreshTokenKey()` плюс сохранение) и убирает куку. Подпись сессии
считается от этого ключа, поэтому все прежние значения перестают проходить
разом.

Отвергнуто:

- **только уборка куки.** Унесённое значение продолжало бы открывать доступ до
  истечения срока — то есть выход не закрывал бы доступ, а делал вид;
- **чёрный список выданных значений.** Даёт точечный выход одной сессии, но
  требует своей таблицы и её чистки; при одном человеке и одном браузере это
  цена без покупателя.

Цена выбранного названа прямо: выход закрывает **все** сессии учётной записи, а
не только текущую. При сегодняшнем числе пользователей это незаметно, и
переделка, когда станет заметно, — чёрный список из отвергнутого варианта.

### Сессия переживает перезапуск сама

Проверено по исходникам: подпись считается от секрета коллекции
(`Collection().AuthToken.Secret`) и ключа записи, оба лежат в базе
(`core/record_query.go`, `FindAuthRecordByToken`). Значит требование выполняется
устройством хранилища, и нашей работы здесь нет — есть проверка тестом.

### Настройки провайдера приводятся к конфигу при каждом запуске

**Выбрано:** шаг схемы включает провайдера с пустыми значениями, а адреса,
идентификатор клиента и секрет проставляются при подъёме сервиса из конфига.

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

Отвергнуто:

- **секрет в шаге схемы.** Разбито инвариантом выше;
- **настройка руками в панели.** Работает, но не воспроизводится: поднятый с
  нуля сервис оказывается без входа, и знание живёт в голове владельца.

### Что изменило ревью кода

Три решения приняты владельцем 2026-08-12 уже после того, как код был написан:
ревью нашло, что заявленное поведение не работает.

**Продление сессии выключено.** Хранилище выдаёт сессию продлеваемой, и
предъявитель менял своё значение на новое бессрочно, никуда не входя. При живом
продлении семисуточный срок не значил ничего — а он объявлен единственным
каналом, которым отзыв доступа у провайдера доходит до сервиса. Цена: вход раз в
семь суток. Отвергнуто: сверяться с провайдером по расписанию (новая связь с
Authelia и обработка её недоступности — работа шире задачи) и принять как есть
(тогда паспорт теряет способ остановить того, кто тратит слишком много).

**Файл записи открыт вошедшим.** Пометка поля защищённым сама по себе закрыла
файл вообще для всех, кроме владельца панели: защищённый файл судится ещё и
правилом просмотра коллекции, а незаданное правило означает «только
суперпользователь». Назначено правило для всякого узнанного. Отвергнуто:
оставить файл только панели — тогда задача про прослушивание записи начинается с
того же вопроса.

**Форма адреса провайдера проверяется на старте.** Непустая, но негодная строка
проходила проверку конфига и отвергалась хранилищем позже — из хука подъёма, до
регистрации пробы здоровья. Сервис падал целиком, вместе с ботом и воркерами, а
у владельца не было даже кода состояния. Отвергнуто: поднимать пробу здоровья
раньше настройки провайдера — это завело бы состояние «сервис жив, вход сломан»,
которого спека не описывает.

## Risks / Trade-offs

- **Секрет клиента появляется в новом месте — в базе.** → Инвариант проекта
  запрещает секрету попадать в git, в лог, в ответ и в `error_text`; база в этом
  перечне не значится, и запрета не нарушает. Но место новое, и модель угроз
  обязана его назвать: чтение файла базы теперь равносильно чтению секрета
  клиента. Пишется в `docs/security.md` этой же задачей.
- **Ломается внешняя программа, ходившая в API анонимно.** → Ломка намеренная и
  объявлена в предложении: это и есть предмет задачи. Замены для программ
  (личные токены) в этом изменении нет — она отдельной целью.
- **Вторая дверь: заголовок `Authorization` остаётся принимаемым.** → Он
  предъявляет ту же сессию и той же проверке, поэтому обхода не даёт. Но это
  второй способ войти, и в спеке он назван, чтобы не был обнаружен ревью как
  находка.
- **Выход закрывает все сессии учётной записи.** → Названо решением выше, цена
  принята.
- **PKCE-verifier и `state` живут во временной куке.** → Кука ставится на время
  входа, `HttpOnly` и `SameSite=Lax`, и убирается на возврате. Хранить их в
  памяти процесса нельзя: выкладка посреди входа роняла бы вход.
- **Признак `Secure` закрывает локальный запуск.** → Браузер не сохранит такую
  куку по `http://localhost`, и вход перестанет работать у того, кто поднимает
  сервис командой из раздела команд. Признак берётся из конфига с умолчанием
  «включено», и расхождение образца называется строкой в
  `docs/conventions/config.md`.
- **Коллекция пользователей остаётся умолчательной `users`.** → Своя коллекция
  означала бы задание правил и способов входа с нуля вместо подчистки
  умолчаний, а переезд позже — перевязку связей с провайдером и обесценивание
  всех выданных сессий. Цена умолчательной: её заводит системный шаг библиотеки
  с открытым созданием записи, и закрывать это приходится нам.
- **Проверить вход целиком без живой Authelia нельзя.** → Тесты закрывают
  сверку `state`, отказ без сессии, выход и сохранность сессии; живой вход у
  провайдера остаётся ручной проверкой владельца на выкладке. Это граница
  покрытия, и она называется в докладе.

## Migration Plan

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

Откат — прежний образ: шаг схемы обратим своим `down`, а до первого входа в
коллекции пользователей пусто.

Порядок выкладки: сперва завести клиента в Authelia и получить секрет, потом
положить его в конфиг на сервере, потом выкладывать. Обратный порядок поднимает
сервис с провайдером без секрета — вход не работает, а API уже закрыт.

## Open Questions

- Адрес возврата должен совпадать с тем, что записан клиенту в Authelia. Значение
  выбирается при заведении клиента и попадает в конфиг; здесь оно не
  фиксируется.