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

Why

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

Владелец назвал желаемое прямо: один бинарник, а различия между запусками задаются конфигом. Тестовый прогон должен подниматься тем же go run ./cmd/transcriber -c config.toml, что и всякий другой, и отличаться от боевого только содержимым файла настроек.

What Changes

• В секцию [auth] добавляется подсекция test_headers — имитация заголовков, которые сервису на сервере ставит обратный прокси. Ключи подсекции задают значения, которыми сервис назовёт пришедшего сам, когда тот пришёл ни с чем.
• В секцию [server] добавляется предохранитель debug — признак отладочного запуска со значением по умолчанию «выключено». Подстановка заголовков работает только при включённом признаке.
• Старт получает новые правила отказа. Заполненная имитация при выключенном предохранителе роняет сервис, а не игнорируется молча; имитация, при которой узнавание не состоится ни при каком запросе — неизвестное имя заголовка, отсутствующий или негодный Remote-User, — роняет его тоже.
• Владелец обязан видеть отладочный запуск в журнале сервиса — предупреждением при старте и на каждом подставленном запросе.
• Подставной обратный прокси go run ./cmd/devtools proxy убирается целиком: всё, ради чего его поднимали, делает сам сервис, и второго способа входить локально не остаётся. Решение владельца на чекпоинте; цена — поломки контура местным инструментом больше не воспроизводятся.
• Образец конфига и памятка описывают локальный вход через настройки вместо запуска второго процесса.

Capabilities

New Capabilities

Новых capability изменение не заводит: предмет прежний — кто пришёл в сервис и пускают ли его дальше.

Modified Capabilities

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

Impact

• Настройки: internal/config — структуры секций [server] и [auth], умолчания, проверки старта. Имя нового ключа конфига необратимо и решается человеком.
• Вход: internal/controller/http — цепочка слоёв корня приложения и узнавание по заголовку.
• Точка входа: cmd/transcriber — порядок проверок при старте и сборка цепочки.
• Оснастка: cmd/devtools — подкоманда proxy удаляется вместе с флагами, шапкой пакета и строкой usage().
• Документы: config.example.toml, CLAUDE.md, README.md, docs/security.md, docs/conventions/config.md, docs/architecture.md — везде, где локальный вход описан через второй процесс.
• Граница домена: docs/passport.md, «Управление учётными записями». Сегодня он утверждает, что кто пришёл, сервис не решает никогда, и что исключений у этого больше нет. Изменение заводит исключение, и паспорт обязан назвать его одной строкой с границей — предохранитель [server] debug, выключенный по умолчанию, — и ссылкой на спеку access.
• Периметр: изменение заводит настройку, которой сервис пускает кого угодно. Машиной боевая поломка не исключена: сервис с включённым предохранителем и заполненной имитацией поднимется на любом перечне доверенных адресов. Что стоит между боевой выкладкой и открытым входом — в design.md, решение 4.