transcriber/openspec/changes/archive/2026-08-23-config-test-headers-login/design.md

Context

Сервис не ведёт входа сам: кто пришёл, называет обратный прокси заголовками Remote-User, Remote-Name и Remote-Email, а сервис верит им, когда соединение открыто с адреса из перечня [auth] trusted_proxies. Имена заголовков объявлены константами транспорта в internal/controller/http/identity.go, и там же записано, что настройкой их не делают. Барьер описан в docs/security.md, «Периметр», и нормирован спекой access.

На машине разработчика прокси нет, браузер заголовков не ставит, и приложение локально не открылось бы вовсе. На это место сегодня встаёт подставной прокси go run ./cmd/devtools proxy: отдельный процесс, слушающий свой порт, ставящий три заголовка и переправляющий запрос сервису. Локальный запуск поэтому идёт в два процесса, приложение открывают по адресу прокси, а перечень доверенных адресов в конфиге приходится переставлять на петлевой.

Владелец назвал желаемое: один бинарник, различия между запусками — в конфиге. Изменение переносит подстановку заголовков в сам сервис и закрывает её предохранителем.

Ограничение, из которого читается всё остальное: подстановка заголовков — это настройка, которой сервис называет пришедшего сам, никого не спросив. Всякий, до кого она дотянется, получит чужой архив. Дизайн поэтому наполовину состоит из того, что подстановке запрещено.

Goals / Non-Goals

Goals:

• Локальный запуск идёт одним процессом и одной командой; вход — то, кем назвался пришедший, — отличает тестовый прогон от боевого содержимым файла настроек, и ничем больше.
• Отлаживается та же ветка кода, что работает в бою: подставленный заголовок неотличим от пришедшего от Caddy к моменту, когда его читает узнавание.
• Настройка, при которой отладочный вход становится открытым входом, роняет старт, а не работает молча.
• Отладочный запуск виден владельцу в журнале.

Non-Goals:

• Уровень журнала, тексты внутренних отказов в ответах, подмена распознавателя, снятие ограничителя частоты, послабления проверок конфига — ничего этого новый признак не включает (см. решение 7).
• Своего входа, ролей и проверки допуска сервис по-прежнему не заводит: подстановка называет пришедшего, а не судит его.
• Автотесты и разработческие сценарии, которым нужна учётная запись, продолжают ставить заголовок сами и в подстановке не нуждаются.
• Граница работы — заголовки входа. Подмена распознавания в конфиг не переезжает: internal/adapter/recognizer/memory.go подставляется правкой кода, и решением владельца так и остаётся.

Decisions

1. Где подставляются заголовки: отдельный слой перед узнаванием

Решено: отдельный слой цепочки корня приложения, стоящий перед TrustedHeaderIdentity и после ограничителя частоты. Он правит заголовки запроса и ничего больше не делает: учётной записи не заводит, отказов не выдаёт, в контекст не пишет. Узнавание получает запрос, неотличимый от пришедшего с сервера.

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

Рассмотрено и отвергнуто:

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

Что человек увидит иначе: приложение открывается по адресу сервиса, второго порта нет, и в журнале запроса стоят те же строки узнавания, что на сервере.

2. Область слоя: только корень приложения

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

3. debug = false при непустой имитации: отказ старта

Решено: старт роняется с именем ключа. Не предупреждение и не молчаливое игнорирование.

Причина: состояние «имитация заполнена, предохранитель выключен» не читается никак, и обе его прочтения — поломка.

• Человек забыл включить предохранитель. Сервис поднимется, никого не узнает, и человек будет искать поломку во входе, в прокси и в перечне адресов — везде, кроме одного булева ключа. Предупреждение в журнале его не спасёт: журнал локального запуска читают тогда, когда уже что-то сломалось.
• Человек забыл убрать имитацию из боевого файла. Тогда в выкладке лежит конфиг, которому недостаёт одного слова, чтобы открыть архив всем. Отказ старта — тот случай, когда поломку ловят на порядок раньше, чем она стоит денег.

Рассмотрено и отвергнуто:

• Молчаливое игнорирование — прямо против тона проекта: инвариант «Принятая запись не теряется молча» описывает ту же болезнь на соседнем предмете.
• Предупреждение в журнале — оставляет заполненную имитацию в боевом файле жить сколько угодно.

Обратная сторона: debug = true при пустой имитации отказом не считается. Это законный запуск — признак сам по себе ничего не включает.

4. debug = true в бою: чем опасно и что ограничивает подстановку

Опасность названа моделью угроз прямо: всякий, кто дотянулся до сервиса, называет себя кем угодно и получает чужой архив. Подстановка делает это хуже барьера trusted_proxies по двум причинам. Первая: подставляется по отсутствию заголовка, то есть запрос, пришедший мимо прокси, — именно тот, который сегодня остаётся неузнанным, — получит имя. Вторая: требование к Caddy «заголовки Remote-* перезаписывать, а не пропускать» здесь не помогает вовсе, потому что перезаписывать нечего.

Решено — одно ограничение: подставленный заголовок проходит тот же барьер, что и настоящий. Слой подставляет значения только тогда, когда адрес соединения попадает в trusted_proxies. Судит он его той же функцией, какой судит узнавание: разбор адреса пира и сверка с перечнем берутся из одного дома (internal/controller/http/identity.go), а не пишутся вторым списком, — так же, как решение 6 поступает с именами заголовков. Второй сверщик разошёлся бы с первым молча: узнавание разворачивает IPv4 в оболочке IPv6, и слой, написавший свою сверку, отличался бы от него ровно на тех адресах, ради которых заводится.

Это не предохранитель, а согласованность с барьером узнавания: от конфига она не требует ничего и круга тех, кто мог назваться кем угодно, не расширяет — он и так очерчен перечнем.

Адресного предохранителя не делаем. Решение владельца на чекпоинте, дословно: «предохранитель по адресам не делаем, полагаемся только на параметр debug». Рассматривалось требование, чтобы при включённом предохранителе перечень доверенных адресов состоял только из петлевых записей; оно снято вместе с предикатом «петлевая запись», который заводился ровно ради него.

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

Что этим потеряно, и это надо назвать прямо: боевую поломку больше не ловит машина. Сервис, поднятый в бою с включённым предохранителем и заполненной имитацией, отдаст архив всякому, кто дотянулся до него с доверенного адреса, — а доверенный адрес в бою это адрес обратного прокси, то есть любой запрос, пришедший обычным путём. Между боевой выкладкой и открытым входом остаётся три вещи, и других нет: умолчание предохранителя «выключено»; отказ старта при заполненной имитации без предохранителя (решение 3); боевой конфиг, который рендерится шаблоном Ansible, а не копируется с машины разработчика.

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

Рассмотрено и отвергнуто:

• Требовать петлевой перечень при включённом предохранителе — снято решением владельца, причина выше. Держалось предикатом «петлевая запись», который заводился ради этой одной проверки.
• Принудительно слушать петлевой адрес при включённом предохранителе — меняет поведение молча (адрес прослушивания задан числом порта, и человек увидел бы «порт занят никем»), и закрывает ровно то, что решение покупает: внутри контейнера сервис слушает не петлю.
• Новый ключ [server] listen — публичная поверхность настроек ради предохранителя, которого решением владельца нет.
• Вырезать подстановку из боевой сборки тегом сборки — сборка образа в гейте не проверяется вовсе (CLAUDE.md, «Гейт»), и тег, забытый в одной ступени, дал бы ровно ту тишину, которой избегает пункт 3.

5. Уже пришедший заголовок: подставляем только при отсутствии Remote-User

Решено: решение принимает наличие Remote-User, а не его значение. Заголовок есть в любом числе значений — слой не трогает запрос вовсе и передаёт его дальше как есть. Заголовка нет ни одного — слой ставит всю тройку Remote-*, которой распоряжается: названные имитацией — значением из конфига, не названные — удаляет.

Почему по наличию, а не по значению: узнавание отвергает запрос с более чем одним Remote-User, и это его главная защита от прокси, который заголовок добавляет вместо замены. Слой, который «дополнил бы пустое место», сам создал бы второе значение и превратил бы законный отказ в отладочный проход.

Почему удаляем не названные имитацией: запрос без Remote-User, но с Remote-Email, иначе собрал бы личность из конфига и из присланного — логин свой, почта чужая. Слой владеет тройкой целиком или не трогает её вовсе.

Рассмотрено и отвергнуто:

• Заменять всегда — сервис, стирающий сказанное прокси, перестаёт быть похожим на боевой, и ветки «пришло два значения» и «заголовок с недоверенного адреса» становятся локально невоспроизводимыми.
• Подставлять по пустому значению Remote-User — пустое значение штатно шлёт прокси там, где никого не назвал; подстановка на этом месте назвала бы человеком того, кому провайдер отказал.

6. Имена заголовков: ключами конфига, но перечень порождается константами

Цена названа прямо: сегодня имена — константы транспорта, и у них один дом. Секция, где имя заголовка служит именем ключа, даёт этим именам второе упоминание, а второе упоминание расходится с первым молча.

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

Так второго дома не появляется: дом остаётся один, а конфиг лишь называет его содержимое, и совпадение сверяет машина, а не внимательность.

Рассмотрено и отвергнуто:

• Произвольная карта имён — опечатка Remote-Usr даёт «сервис меня не узнаёт» без единого следа, а выгоды нет: сервис читает ровно три имени и четвёртое читать не умеет.
• Свои имена ключей вместо имён заголовков (login, name, email) — самое дешёвое для инварианта, но теряет то, ради чего секция заводится: конфиг перестаёт выглядеть как то, что ставит Caddy, и владелец назвал форму прямо. Оставлено вариантом на случай, если человек решит платить иначе.

Замечание по форме: в TOML пара пишется через =, а не через :. Пример владельца записывается так:

[auth.test_headers]
Remote-User = "foobar"
Remote-Email = "foobar@example.com"

7. Что означает [server] debug и чего он не включает

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

Чего признак не включает и включать не должен без отдельного решения человека:

• уровень журнала (он зашит и настройкой не является);
• тексты внутренних отказов и следы стека в ответах;
• вывод тел запросов и ответов внешних сервисов;
• снятие или послабление ограничителя частоты;
• подмену распознавателя памятью — это подстановка в коде, internal/adapter/recognizer/memory.go, и настройкой она не делается;
• послабление любой проверки старта;
• открытие любого адреса неузнанному.

Правило для следующей задачи: новое поведение вешается на этот ключ только решением владельца и получает свою строку в спеке access или в спеке своей capability. Ключ — предохранитель с закрытым перечнем следствий, а не режим с открытым.

8. Где живёт проверка

Проверка охватывает две секции разом — [server] debug против [auth] test_headers и [auth] trusted_proxies, — и потому не помещается ни в AuthConfig.Validate(), ни в проверку секции сервера. Решено: метод на корневой Config, названный своим предметом, зовётся из cmd/transcriber рядом с тремя имеющимися проверками. Закрыть расхождение «единого места проверки нет», названное в docs/conventions/config.md, он не пытается: это отдельная работа.

Рассмотрено и отвергнуто: передавать признак отладки внутрь AuthConfig.Validate() — секция начала бы знать о чужой секции ради одного булева значения.

9. Журнал

• Старт с включённой подстановкой — уровень WARN, один раз. Адресат — владелец, и сообщение ровно того рода, который конвенция называет «может стать проблемой»: сервис называет пришедшего сам. Поля: capability access, перечень имён подставляемых заголовков. Значений в строке нет: логин — это ключ к чужому архиву, и спека access запрещает его печатать наравне с адресом почты.

• Запрос, которому заголовки подставлены — уровень DEBUG. Случай штатный и частый: так выглядит каждый запрос локального прогона, и INFO затопил бы журнал. Поля те же, что у узнавания: http.peer_addr, capability, transport.

• Запрос, которому подставить нельзя (предохранитель включён, но адрес пира не доверенный) — уровень WARN, своей строкой. Поля: http.peer_addr, capability, transport; подставляемых значений в ней нет.

  Прежняя посылка «узнавание уже пишет здесь предупреждение» неверна, и это проверено по коду. Ветка узнавания выбирается по числу значений Remote-User до сверки адреса пира: заголовка нет — пишется Debug("Request carries no login header"), и запрос уходит дальше. Предупреждение Login header came from an untrusted peer достижимо только тогда, когда заголовок есть, а подстановка работает ровно при его отсутствии. На отказном пути подстановки предупреждения не бывает никогда.

  Без своей строки самый частый локальный отказ остаётся без следа: браузер идёт на localhost, тот разрешается в ::1, а в trusted_proxies по образцу стоит 127.0.0.1. Человек видит 401 на всём приложении, заполненную секцию имитации, включённый предохранитель — и ни одной строки о том, что подстановка не сработала. Отсюда же требование к образцу конфига: рядом с 127.0.0.1 в перечне обязан стоять ::1.

• Строка Account created from login header работает как работала: первый запрос локального прогона заводит учётную запись и виден на INFO.

10. Подкоманда cmd/devtools proxy убирается целиком

Решено владельцем на чекпоинте: подкоманда удаляется. Назначения у неё не остаётся — всё, ради чего её поднимали, делает сам сервис, — и второго способа входить локально не остаётся тоже.

Цена названа и принята: поломки контура — два значения Remote-User, заголовок с недоверенного адреса, цепочка X-Forwarded-For — местным инструментом больше не воспроизводятся. Воспроизводит их теперь только автотест, ставящий заголовок сам.

Уходит вместе с подкомандой: её флаги, шапка пакета cmd/devtools/main.go — она сегодня говорит «подкоманд две» и описывает прокси, — строка подкоманды в usage() и упоминания прокси в документах. Адреса перечислены шагом 4.4 tasks.md.

Рассмотрено и отвергнуто владельцем:

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

Risks / Trade-offs

• Отладочный вход уезжает в боевой конфиг → умолчание предохранителя «выключено» и отказ старта при заполненной имитации без предохранителя (решение 3). Проверка идёт на старте, до приёма трафика, и ловит она ровно этот случай — заполненную имитацию при выключенном предохранителе.
• Разработчик оставил debug = true и выложился → выкладка рендерит конфиг из шаблона Ansible, а не копирует локальный файл. Другой защиты нет, и это принято решением владельца (решение 4): боевой сервис с включённым предохранителем и заполненной имитацией отдаст архив всякому, чей запрос пришёл через обратный прокси, то есть всякому, кто пришёл обычным путём.
• Имя заголовка в конфиге разошлось с константой транспорта → перечень принимаемых имён порождается константами, неизвестный ключ роняет старт (решение 6).
• Поломки контура перестали воспроизводиться локально → подкоманда proxy убрана (решение 10); остаются автотесты, которые ставят заголовок сами.
• Ключ debug обрастёт чужими следствиями → закрытый перечень в решении 7 и правило «новое следствие — своя строка в спеке».
• Тестовый пользователь копится в базе. Каждый новый логин в имитации заводит учётную запись, а удалять учётные записи сервис не умеет. Локальная база ронется и пересоздаётся свободно; в бою подстановка выключена, а включённая была бы поломкой много хуже лишней учётной записи.

Migration Plan

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

Open Questions

Развилок не осталось: все закрыты владельцем на чекпоинте.