HTTP API закрыт за вход через OIDC у Authelia

- шаг схемы закрывает поверхность, которую хранилище приносит открытой:
  собственную регистрацию, вход по паролю и одноразовый код — без этого
  закрытие приёма обходилось двумя запросами
- продление сессии выключено, срок семь суток: иначе отзыв доступа у
  провайдера до сервиса не доходит никогда
- файл записи отдаётся вошедшему по токену файла — пересмотр
  ADR-2026-08-12-file-link-open-but-not-logged

openspec/changes/archive/2026-08-12-oidc-login/specs/access/spec.md

@@ -0,0 +1,298 @@
+## ADDED Requirements
+
+### Requirement: Вход через внешнего провайдера
+
+Сервис SHALL заводить сессию только по итогу входа у внешнего провайдера OIDC.
+Своей регистрации, своей формы пароля и своего восстановления доступа сервис
+MUST не заводить: учётные записи держит провайдер, и это граница домена из
+паспорта.
+
+Вход начинается собственным адресом сервиса: он уводит человека к провайдеру.
+Провайдер возвращает человека на адрес возврата, и сервис MUST обменять
+принесённый код на учётную запись **средствами хранилища**, а не разбором ответа
+провайдера своими руками — так решено 2026-08-11. Учётная запись, которой ещё
+нет, заводится сама; связь её с внешним провайдером ведёт хранилище.
+
+Возврат от провайдера MUST быть проверен на подмену: сервис сверяет пришедшее
+состояние с тем, что сам выдал, и отвергает возврат, чьё состояние он не
+выдавал. Без этой сверки вход принимает чужой код.
+
+Обмен кода MUST быть ограничен во времени: у обращения к провайдеру есть
+таймаут, и по его истечении вход кончается отказом. Молчащий провайдер иначе
+держит обработчик возврата открытым до упора, а «провайдер медленный»
+становится неотличим от «провайдер отказал».
+
+Ни код, принесённый от провайдера, ни секрет клиента MUST не попадать в журнал.
+
+Адреса нормативны: вход — `GET /auth/login`, возврат — `GET /auth/callback`,
+выход — `POST /auth/logout`. Они лежат вне `/api/`, потому что это пространство
+поделено с собственными адресами хранилища. Выход берёт `POST` намеренно: по
+`GET` его срабатывание уносится переходом по чужой ссылке.
+
+#### Scenario: Человек входит впервые
+
+- **GIVEN** провайдер настроен и учётной записи в сервисе ещё нет
+- **WHEN** человек проходит вход и возвращается с кодом провайдера
+- **THEN** учётная запись заводится, а сессия открывается
+- **AND** дальнейший запрос к API от этой сессии проходит
+
+Состояние и проверочный код PKCE сервис SHALL хранить у браузера — тем же
+носителем, что и сессию, и с теми же признаками защиты. Носитель MUST жить не
+дольше одного входа, MUST убираться на возврате — и на успешном, и на отказном,
+— а состояние MUST быть одноразовым: возврат, чьё состояние уже употреблено,
+отвергается наравне с невыданным. Проверочный код PKCE обязателен: обмен кода
+средствами хранилища его требует.
+
+Носитель без защиты соединения отменял бы то, ради чего заведён: перехваченный
+проверочный код обесценивает PKCE, а подставленное состояние — сверку подмены.
+
+#### Scenario: Признаки носителя состояния
+
+- **WHEN** сервис уводит человека к провайдеру
+- **THEN** носитель состояния и проверочного кода несёт те же признаки защиты,
+  что и кука сессии
+
+#### Scenario: Возврат нельзя переиграть
+
+- **GIVEN** человек уже вернулся от провайдера и сессия открылась
+- **WHEN** тот же возврат с тем же состоянием приходит второй раз
+- **THEN** сессия не открывается, а ответ несёт отказ
+
+#### Scenario: Возврат с чужим состоянием
+
+- **WHEN** на адрес возврата приходит код с состоянием, которого сервис не
+  выдавал
+- **THEN** сессия не открывается, а ответ несёт отказ
+- **AND** учётная запись не заводится
+
+#### Scenario: Провайдер отказал
+
+- **WHEN** провайдер возвращает человека с ошибкой вместо кода
+- **THEN** сессия не открывается, а ответ несёт отказ
+
+### Requirement: Иных способов открыть сессию нет
+
+Сервис SHALL оставить вход у провайдера единственным способом завести учётную
+запись и получить сессию. Собственное создание записи в коллекции пользователей,
+вход по паролю, вход по одноразовому коду и восстановление доступа MUST быть
+выключены настройкой коллекции.
+
+Требование отдельно от «Вход через внешнего провайдера» намеренно: то нормирует
+наш код, а это — **поверхность, которую приносит хранилище**. Умолчание
+хранилища заводит коллекцию пользователей с открытым созданием записи и
+включённым входом по паролю, и без этого требования закрытие приёма обходится
+двумя запросами: завести себе запись, войти по паролю, предъявить полученное.
+
+Отдельная цена у открытого создания записи — захват учётной записи. Обмен кода
+ищет запись сперва по неизменяемому признаку провайдера, а не найдя — по адресу
+почты; запись, заведённая посторонним на чужой адрес, достаётся первому же
+настоящему входу с этим адресом.
+
+#### Scenario: Завести учётную запись самому нельзя
+
+- **WHEN** анонимный запрос создаёт запись в коллекции пользователей
+- **THEN** ответ несёт отказ, а записи не появляется
+
+#### Scenario: Вход паролем недоступен
+
+- **WHEN** запрос идёт на вход по паролю к коллекции пользователей
+- **THEN** ответ несёт отказ, а сессия не открывается
+
+#### Scenario: Восстановление доступа недоступно
+
+- **WHEN** запрос просит восстановление пароля или одноразовый код
+- **THEN** ответ несёт отказ
+
+### Requirement: Сессия предъявляется кукой
+
+Сервис SHALL принимать сессию, предъявленную кукой, — браузер отдаёт её сам, и
+своей страницы со скриптом для этого не требуется. Кука сессии MUST быть
+недоступна скриптам страницы (`HttpOnly`), MUST не уходить по незашифрованному
+соединению (`Secure`) и MUST не отправляться при переходе с чужого сайта
+(`SameSite=Lax` или строже).
+
+Имя куки нормативно — `transcriber_session`: смена имени молча выкидывает всех
+вошедших, а тест, ставящий и читающий одно и то же имя, этого не замечает.
+
+Хранилище читает предъявленную сессию заголовком `Authorization`, и этот способ
+остаётся рабочим: его требуют собственные адреса аутентификации хранилища.
+Сервис MUST перекладывать значение куки в этот заголовок **только когда
+заголовка нет**: предъявленный заголовок побеждает, иначе браузер с сессионной
+кукой получал бы не то, что предъявил на собственных адресах хранилища.
+
+Область действия слоя MUST быть ограничена адресами приложения — приёмом записи
+и опросом готовности. Собственная поверхность хранилища под него не подпадает:
+часть её защищена сегодня ровно тем, что браузер заголовка сам не шлёт, и
+расширение слоя на всё сняло бы эту защиту молча.
+
+#### Scenario: Кука открывает доступ
+
+- **GIVEN** человек вошёл и получил куку сессии
+- **WHEN** он шлёт запрос к API с этой кукой и без заголовка
+- **THEN** запрос проходит
+
+#### Scenario: Кука защищена от чтения скриптом
+
+- **WHEN** сервис ставит куку сессии
+- **THEN** она несёт признаки `HttpOnly`, `Secure` и `SameSite`
+
+#### Scenario: Предъявленный заголовок побеждает куку
+
+- **WHEN** запрос несёт и куку сессии, и заголовок `Authorization`
+- **THEN** проверку проходит значение заголовка, а не куки
+
+### Requirement: Значение, дающее доступ, не печатается
+
+Сервис SHALL не писать в журнал, в ответ и в метку метрики ни значение сессии,
+ни код, принесённый от провайдера, ни секрет клиента, ни адрес почты
+пользователя. Записанное значение сессии MUST читаться как ключ к чужому
+доступу: оно годно до выхода или до истечения срока, и строка журнала уезжает в
+собранные логи, откуда её не убрать.
+
+Требование того же рода, что и запрет писать имя файла в хранилище: там строка
+журнала собирала бы ссылку на чужую запись, здесь — предъявление чужой сессии.
+Адрес почты приходит от провайдера и принадлежит человеку, а не сервису.
+
+#### Scenario: Значения сессии нет в журнале
+
+- **GIVEN** человек вошёл и получил куку сессии
+- **WHEN** он шлёт запрос к API с этой кукой
+- **THEN** значение сессии не встречается ни в одной журнальной записи
+
+#### Scenario: Адреса почты нет в журнале
+
+- **WHEN** человек проходит вход и учётная запись заводится
+- **THEN** адрес его почты не встречается ни в одной журнальной записи
+
+### Requirement: Сессия переживает перезапуск сервиса
+
+Сервис SHALL держать сессию годной после своего перезапуска: подпись сессии MUST
+опираться на секрет, лежащий в хранилище, а не на значение, заведённое в памяти
+при старте. Иначе всякая выкладка выкидывает всех вошедших молча.
+
+#### Scenario: Прежняя кука годна после перезапуска
+
+- **GIVEN** человек вошёл и получил куку сессии
+- **WHEN** сервис поднимается заново на том же хранилище
+- **THEN** запрос с прежней кукой проходит
+
+### Requirement: Срок жизни сессии назначен, а не достался умолчанию
+
+Сервис SHALL назначать срок жизни сессии сам — **семь суток**, числом в настройке
+коллекции и тем же числом в сроке жизни куки. Умолчание хранилища MUST не
+применяться: оно даёт пять суток, и это число никем не выбрано.
+
+Срок здесь — единственное, что доносит до сервиса **отзыв доступа у
+провайдера**. Сессия выдана однажды, и к провайдеру сервис больше не ходит:
+человек, которому Authelia закрыла доступ, работает до истечения своей сессии.
+Паспорт опирается на отзыв в Authelia как на способ остановить того, кто
+тратит слишком много, — значит срок сессии и есть цена этой остановки.
+
+**Отсюда запрет на продление.** Хранилище выдаёт сессию продлеваемой:
+предъявитель меняет своё значение на новое, с новым сроком, и делает это сколько
+угодно раз, никуда не входя. Сервис SHALL закрыть продление — иначе срок жизни
+сессии не значит ничего, а канал отзыва перестаёт существовать вовсе.
+
+Владелец MUST иметь способ закрыть чужие сессии немедленно, не дожидаясь срока.
+
+#### Scenario: Сессия не продлевает саму себя
+
+- **GIVEN** человек вошёл и получил сессию
+- **WHEN** этой же сессией он просит продлить её
+- **THEN** ответ несёт отказ, а нового значения в нём нет
+
+#### Scenario: Сессия истекает назначенным сроком
+
+- **GIVEN** человек вошёл и получил куку сессии
+- **WHEN** назначенный срок прошёл
+- **THEN** запрос с этой кукой получает отказ
+
+#### Scenario: Владелец закрывает чужую сессию
+
+- **GIVEN** человек вошёл и получил куку сессии
+- **WHEN** владелец обесценивает сессии этой учётной записи
+- **THEN** запрос с прежней кукой получает отказ
+
+### Requirement: Выход прекращает доступ
+
+Сервис SHALL закрывать доступ по выходу немедленно: выход MUST обесценивать
+выданные этой учётной записи сессии на стороне сервиса, а не только убирать куку
+у браузера. Куку сервис при этом MUST убрать тоже.
+
+Одной уборки куки мало: сессия предъявляется значением, и унесённое значение
+продолжало бы открывать доступ до самого своего истечения.
+
+Порядок обязателен: сперва обесценивание, потом уборка куки. При обратном
+порядке выход, разошедшийся с одновременным входом, оставляет годную сессию, а
+человек уверен, что вышел.
+
+#### Scenario: После выхода прежняя кука не работает
+
+- **GIVEN** человек вошёл и получил куку сессии
+- **WHEN** он выходит, а затем шлёт запрос к API с прежней кукой
+- **THEN** запрос получает отказ
+
+#### Scenario: Выход убирает куку
+
+- **WHEN** человек выходит
+- **THEN** ответ убирает куку сессии у браузера
+
+### Requirement: Кого пускать, решает провайдер
+
+Сервис SHALL пускать всякого, кого пропустил провайдер, и своей проверки допуска
+MUST не делать. Кто допущен, определяет правило провайдера на этого клиента —
+настройка выкладки, лежащая вне репозитория.
+
+Требование записано именно как решение с ценой, а не как умолчание: провайдер
+общий для контура, и клиент, настроенный слишком широко, открывает сервис
+всякому, у кого есть учётная запись у провайдера. Проверить это по коду нельзя,
+поэтому граница названа здесь и повторена в модели угроз.
+
+#### Scenario: Пропущенный провайдером получает доступ
+
+- **WHEN** человек проходит вход у провайдера и возвращается с кодом
+- **THEN** учётная запись заводится, а доступ открывается
+- **AND** сервис не спрашивает у ответа провайдера ничего сверх того, что нужно
+  для заведения записи
+
+### Requirement: Проба здоровья и метрики остаются открытыми
+
+Сервис SHALL отдавать `GET /health` и `GET /metrics` без сессии. Ни у пробы
+здоровья, ни у сборщика метрик сессии нет, и требование входа остановило бы
+наблюдение за сервисом.
+
+Наружу эти адреса закрывает правило обратного прокси — это работа выкладки, и
+сервис на неё не полагается: содержимого записей и текстов расшифровок оба
+адреса не несут.
+
+#### Scenario: Проба здоровья доступна анонимно
+
+- **WHEN** запрос приходит на `GET /health` без сессии
+- **THEN** ответ имеет код `200`
+
+#### Scenario: Метрики доступны анонимно
+
+- **WHEN** запрос приходит на `GET /metrics` без сессии
+- **THEN** ответ имеет код `200`
+
+### Requirement: Секрет провайдера живёт в конфиге
+
+Сервис SHALL брать адреса провайдера, идентификатор клиента и секрет клиента из
+конфига. Секрет MUST не попадать ни в журнал, ни в ответ, ни в git; настройки
+провайдера в хранилище MUST приводиться к значениям конфига при каждом запуске,
+а не заводиться однажды шагом схемы.
+
+Причина второго требования в необратимости шага схемы: применённый шаг не
+переписывается, и смена секрета в конфиге иначе не доехала бы до хранилища
+вовсе — вход сломался бы после ротации.
+
+#### Scenario: Секрета нет в журнале
+
+- **WHEN** сервис поднимается с настроенным провайдером
+- **THEN** значение секрета не встречается ни в одной журнальной записи
+
+#### Scenario: Смена секрета доезжает до хранилища
+
+- **GIVEN** сервис уже поднимался с прежним секретом
+- **WHEN** секрет в конфиге заменён и сервис поднят заново
+- **THEN** настройки провайдера в хранилище несут новое значение

openspec/changes/archive/2026-08-12-oidc-login/specs/intake/spec.md

@@ -0,0 +1,104 @@
+## MODIFIED Requirements
+
+### Requirement: Приём записи по HTTP
+
+Сервис SHALL принимать запись от внешней программы запросом `POST /api/audio` с
+телом `multipart/form-data` и полем `audio` **только от узнанного отправителя**.
+Запрос без сессии MUST получать код `401`, и по нему MUST не заводиться ни файл,
+ни задача расшифровки. Принятая запись от узнанного отправителя MUST быть
+сохранена и получить заведённую под неё задачу расшифровки в состоянии
+`created`; ответ MUST нести идентификатор задачи полем `job_id` и её состояние
+полем `status`.
+
+Отказ по отсутствию сессии наступает **раньше** чтения тела: запись, за которую
+не заплатит узнанный отправитель, не должна попасть даже в память.
+
+Имена полей ответа нормативны: контракт HTTP API объявлен проектом необратимым,
+и переименование поля ломает внешнюю программу молча. Появление отказа без
+сессии — намеренная ломка этого контракта: до неё приём стоял открытым наружу.
+
+Приём не судит о годности записи сам: расширение он берёт из имени файла, а
+пригодность содержимого узнаёт у источника метаданных.
+
+Куда именно ложится принятая запись, приёму не принадлежит: раскладку выбирает
+хранилище, и нормирует её capability `storage`.
+
+Владельца у принятой записи приём не заводит: после входа видно ровно то же, что
+видно было анонимно.
+
+#### Scenario: Запись принята
+
+- **GIVEN** источник метаданных читает запись и отдаёт её длительность
+- **AND** отправитель предъявил сессию
+- **WHEN** программа шлёт `POST /api/audio` с полем `audio`
+- **THEN** ответ имеет код `201`, а в теле лежат непустой `job_id` и `status`
+  со значением `created`
+- **AND** содержимое записи целиком лежит в хранилище одним файлом
+
+#### Scenario: Сессии нет
+
+- **WHEN** программа шлёт `POST /api/audio` с полем `audio` без сессии
+- **THEN** ответ имеет код `401`
+- **AND** ни файла, ни задачи не заводится
+- **AND** тело ответа не несёт данных задачи
+
+#### Scenario: Поля с записью нет
+
+- **GIVEN** отправитель предъявил сессию
+- **WHEN** программа шлёт `POST /api/audio` без поля `audio`
+- **THEN** ответ имеет код `400` и сообщение об отсутствии записи
+- **AND** ни файла, ни задачи не заводится
+
+#### Scenario: Размеру записи приём не судья
+
+- **GIVEN** источник метаданных читает запись и отдаёт её длительность
+- **AND** отправитель предъявил сессию
+- **WHEN** программа шлёт запись нулевой длины
+- **THEN** ответ имеет код `201`: собственного порога по размеру у приёма нет
+
+### Requirement: Опрос готовности задачи
+
+Сервис SHALL отдавать состояние задачи расшифровки по запросу
+`GET /api/status/:id` **только узнанному отправителю**. Запрос без сессии MUST
+получать код `401`, и тело такого ответа MUST не нести ни состояния задачи, ни
+текста расшифровки. Ответ узнанному отправителю MUST нести идентификатор полем
+`job_id`, состояние полем `status` и время заведения полем `created_at`, а текст
+расшифровки полем `transcription_text`, и это поле MUST отсутствовать в ответе,
+пока текста нет: пустая строка на месте отсутствующего текста читается как
+«расшифровка пуста».
+
+Отказ без сессии MUST не зависеть от того, есть такая задача или нет: иначе по
+кодам ответа перебирается список заведённых задач.
+
+Выборку по владельцу опрос не сужает: узнанный отправитель видит любую задачу по
+её идентификатору ровно как прежде. Сужение придёт отдельной задачей.
+
+#### Scenario: Задача найдена
+
+- **GIVEN** отправитель предъявил сессию
+- **WHEN** программа спрашивает состояние заведённой задачи
+- **THEN** ответ имеет код `200` и несёт `job_id`, `status` и `created_at`
+
+#### Scenario: Сессии нет
+
+- **WHEN** программа спрашивает состояние заведённой задачи без сессии
+- **THEN** ответ имеет код `401`
+- **AND** тело ответа не несёт ни состояния задачи, ни текста расшифровки
+
+#### Scenario: Без сессии неизвестная задача неотличима от заведённой
+
+- **WHEN** программа без сессии спрашивает состояние заведённой задачи, а затем
+  состояние по неизвестному идентификатору
+- **THEN** оба ответа имеют код `401`
+
+#### Scenario: Расшифровки ещё нет
+
+- **GIVEN** отправитель предъявил сессию
+- **WHEN** программа спрашивает состояние задачи, которая ещё не дошла до текста
+- **THEN** поля `transcription_text` в ответе нет вовсе
+
+#### Scenario: Задачи с таким идентификатором нет
+
+- **GIVEN** отправитель предъявил сессию
+- **WHEN** программа спрашивает состояние по неизвестному идентификатору
+- **THEN** ответ имеет код `404` и сообщение о ненайденной задаче

openspec/changes/archive/2026-08-12-oidc-login/specs/storage/spec.md

@@ -0,0 +1,77 @@
+## MODIFIED Requirements
+
+### Requirement: Файл отдаётся ссылкой
+
+Сервис SHALL отдавать файл записи ссылкой, которую строит хранилище по самой
+записи, **и только узнанному отправителю**. Поле файла MUST быть помечено
+защищённым: без этого ссылка открывает запись любому, кто её знает, и знание
+ссылки становится правом. Отданный файл MUST совпадать с принятым по длине.
+
+Одной пометки мало: защищённый файл судится **коротким токеном файла**, который
+узнанный отправитель берёт у хранилища, предъявив сессию, — и правилом просмотра
+коллекции. Правило MUST пускать всякого узнанного: незаданное означает «только
+владелец панели», и тогда файла не получит и вошедший. Сужения по владельцу
+здесь нет — его заводит отдельная задача.
+
+Отсюда порядок для потребителя: сессия → токен файла → ссылка с этим токеном.
+Браузер с одной лишь кукой файла не получит, и это свойство хранилища, а не
+недосмотр.
+
+Ссылка на несуществующую запись MUST отвечать отказом, а не пустым файлом.
+
+**Ссылка сама по себе и есть право пройти по ней**, и потому она MUST не попадать
+ни в журнал, ни в метку метрики, ни в ответ отправителю. Имя, под которым файл
+лёг в хранилище, из журнала выводимо быть не должно: журнал уезжает в собранные
+логи, откуда строку не убрать, и оттуда ссылка на чужую запись работала бы
+бессрочно.
+
+Защищённое поле сужает это право, но не отменяет запрета: право пройти теперь
+требует ещё и сессии, а строка журнала со ссылкой по-прежнему собирала бы
+половину ключа.
+
+Отсюда требование к отказам: сообщение об отказе хранилища MUST не выходить за
+пределы хранилища дословно. Отказ чтения и отказ укладки называют ключ файла
+целиком, а отказ выгрузки во внешнее хранилище — полный адрес объекта; и то и
+другое кончается в журнале и собирает ссылку не хуже успешного пути.
+
+Конвейер расшифровки этим не затронут: он читает файл из файловой системы
+хранилища, а не по ссылке.
+
+Что именно журнал приёма пишет ради прослеживаемости, нормирует capability
+`intake`.
+
+#### Scenario: Файл забирают по ссылке
+
+- **GIVEN** запись принята и её файл лежит в хранилище
+- **AND** забирающий предъявил сессию и взял по ней токен файла
+- **WHEN** ссылку на файл запрашивают с этим токеном
+- **THEN** приходит тот же файл, и его длина совпадает с длиной принятого
+
+#### Scenario: Без сессии файл не отдаётся
+
+- **GIVEN** запись принята и её файл лежит в хранилище
+- **WHEN** ссылку на файл запрашивают без сессии
+- **THEN** приходит отказ, а содержимого записи в ответе нет
+
+#### Scenario: Ссылка ведёт в никуда
+
+- **WHEN** запрашивают ссылку на запись, которой нет
+- **THEN** приходит отказ, а не пустой ответ
+
+#### Scenario: По журналу ссылку не собрать
+
+- **GIVEN** запись принята и прошла конвейер
+- **WHEN** читают журнал сервиса целиком
+- **THEN** имени, под которым файл лёг в хранилище, в нём нет
+
+#### Scenario: Отказ чтения файла не называет его ключ
+
+- **GIVEN** файл записи не читается из хранилища
+- **WHEN** шаг конвейера берётся за эту запись и отказывает
+- **THEN** отказ называет запись её идентификатором и не несёт имени файла
+
+#### Scenario: Конвейер читает файл без сессии
+
+- **GIVEN** запись принята и ждёт расшифровки
+- **WHEN** шаг конвейера берётся за неё
+- **THEN** файл читается из файловой системы хранилища и шаг проходит