houseplan-card/docs/reviews/SPEC-REVIEW-43-r3.md

# SPEC-REVIEW-43-r3

- Issue: #43 «Диалог помощи и обратной связи с обезличенным support report»
- Этап: spec (PROCESS.md §2.4)
- Заход: r3 · блокирующих циклов израсходовано 2 из 4 (после этого раунда)
- Материал: `docs/specs/043-private-support-report.md` на HEAD `c43bf847`
  (ветка `issue/43-help-feedback`), плюс код `scripts/support-relay/**` как
  доказательство исполнимости заявленных в ТЗ §9 контрактов.
- Предыдущий раунд: r2, вердикт **зелёный**, SHA `e25aa302` (High 0, Medium 0);
  документ `docs/reviews/SPEC-REVIEW-43-r2.md`, опубликован коммитом `cf7f47db`.

## Почему разбор не сведён к «только дельта»

Между r2 и r3 в issue появилась реальная production-инфраструктура: relay
поднят на боевом узле, владелец лично проверил rate limiting и попытку подмены
источника через `X-Forwarded-For`, обнаружил, что прямой Telegram недоступен с
хостинга проекта, и по итогу сменил канал доставки «последней мили» на приватный
вебхук собственного Home Assistant. Это смена контракта в подсистеме, которую
r1/r2 уже проверяли (§9 relay), а не локальная правка формулировки — поэтому
разбор §9 и связанных разделов (§14.3/§14.4/§16/§17) сделан заново целиком, а не
только «что изменилось в тексте».

## Дельта r2→r3

`git diff e25aa302..HEAD`:

- `cf7f47db` — публикация `docs/reviews/SPEC-REVIEW-43-r2.md` (только review-артефакт, не часть ТЗ);
- `00102819 feat(relay): receive support reports on the project stand` — первая реализация `scripts/support-relay/**` (класс B), 1593 строки;
- `6b10cd52 docs: switch the support sink to a maintainer channel` — правка §5.1/§9.1/§9.3/§12/AC12/§14.3/§16/§17/§18/§19/§20 ТЗ: mailbox → приватный канал мейнтейнера;
- `c7efcf16 fix(relay): pin the rate-limit source to the proxy-supplied address` — код и тест против подмены источника лимита через `X-Forwarded-For`, найденной живым пентестом на стенде; **ТЗ этим коммитом не тронуто**;
- `c43bf847 feat(relay): deliver through the maintainer's Home Assistant webhook` — второй канал доставки `ha_webhook`, правка §9.1/§9.3 ТЗ.

Все четыре продуктовых коммита несут `Issue: #43` и `User-Visible: no` —
консистентно с тем, что видимое поведение карточки (`src/**`) ещё не начато,
только class-B relay.

## Закрытие раунда r2

r2 закрылся с 0 находок (High 0, Medium 0) — закрывать в r3 нечего, таблица
пустая. Единственное, что произошло после r2, — новая работа поверх зелёного
вердикта, а не исправление старых замечаний.

## Унаследовано из r2 (и из r1 через r2)

Без повторной проверки приняты — как есть в `docs/reviews/SPEC-REVIEW-43-r2.md`
на SHA `e25aa302` — потому что дельта r2→r3 не касается доказательной базы
этих пунктов:

- §1–§6 (сценарий, UX-контракт кнопки/диалога/формы/preview/submit) — текст не
  менялся в дельте;
- §7 (allowlist/pseudonymization/privacy invariant support package v1) — не
  менялся;
- §8 (backend API preview/discard/submit) — не менялся;
- §10 (state/compatibility), §11 (touch/a11y — включая каноническую фразу
  `Touch editor: supported`, закрытую в r1→r2), §13 AC1–AC11, AC13–AC17
  (кроме евиденс-колонки AC12, см. находку ниже);
- классификация `scripts/support-relay/**` как class B по `AGENTS.md`/
  `PROCESS.md` (закрытая в r1→r2 находка) — подтверждена и в r3 живым прогоном
  `process-gate.mjs` на новом HEAD (см. «Гейты»), т.к. дерево `scripts/`
  выросло, но regex-классификация в `process-gate.mjs` не менялась.

## Находки

### Medium (в скоупе #43, чинится этим же ТЗ, без нового цикла к владельцу — вопрос чисто технический)

**Требование к источнику rate-limit не зафиксировано в ТЗ, хотя код и тесты
уже реализуют его правильно.**

§9.2 ТЗ (не тронут дельтой) по-прежнему говорит только:

> 5 attempts/hour and 20/day per source address plus a global circuit breaker;
> source IP is used only through a daily-keyed rate-limit hash with ≤24 h TTL

Это не говорит, ОТКУДА берётся «source address», хотя корректность всей
анти-abuse истории публичного эндпоинта (§16, риск 3 «Public relay attracts
spam») зависит именно от этого. На реальном стенде это оказалось не
теоретическим риском: согласно комментарию владельца от 2026-09-01 21:25,
подмена `X-Forwarded-For` почти позволила обойти лимит одной строкой запроса —
спасло только совпадение с дефолтом чужого Caddy-конфига. Исправление внесено
кодом (`c7efcf16`) и покрыто тестом, но **в ТЗ это исправление не попало**:

- `docs/specs/043-private-support-report.md` §9.2 не требует, что источник
  берётся из доверенного hop-а прокси, а не из клиентского заголовка;
- AC12 (§13) по-прежнему говорит только «Relay enforces schema, size, hash,
  idempotency and rate limits» — не называет спуфинг-стойкость как часть
  контракта;
- §14.3 (test plan) и особенно §14.4 (mutation requirements) — единственный
  раздел ТЗ, который явно перечисляет КАЖДУЮ обязательную мутацию для security-
  инвариантов (checkbox default, redirect/SSRF, forbidden field leak и т.д.) —
  не содержит пункта «клиент подделывает X-Forwarded-For и выбирает себе новую
  корзину лимита → тест красный», хотя именно такой тест уже существует в коде
  (`test_client_cannot_pick_its_own_rate_bucket`,
  `scripts/support-relay/tests/test_relay.py:454-470`) и хотя именно этот
  сценарий уже был проверен на боевом трафике.

Реализация де-факто правильная (проверено чтением и исполнением, см. «Гейты»):
`hp_relay/app.py:147-158` берёт последний элемент `X-Forwarded-For` только при
`cfg.trusted_proxy` (default `HP_RELAY_TRUSTED_PROXY=1`,
`hp_relay/config.py:41,82`), а `deploy/Caddyfile.fragment:12-14` полностью
перезаписывает заголовок на обоих сайтах (`header_up X-Forwarded-For
{remote_host}`), а не дополняет его. Но эта перепись — рассыпанные по трём
файлам факты (`app.py`, `Caddyfile.fragment`, `env.example`), а не пункт
контракта ТЗ. Проблема не «оно не работает сейчас», а «ничто в ТЗ не обязывает
это работать после следующего рефакторинга»: спека — это то, с чем сверяется
будущий код-ревью и будущий переписчик `hp_relay/app.py`, а не README
деплоя.

**Чем закрыть, не открывая вопрос владельцу** (технический пункт, решается
автором ТЗ по §7.1, не владельцем):

1. в §9.2 добавить явное предложение: источник для rate-limit — последний
   элемент `X-Forwarded-For`, только если relay сконфигурирован работать за
   доверенным прокси (`trusted_proxy`), который обязан перезаписывать этот
   заголовок целиком, а не дополнять; без этой конфигурации — адрес
   TCP-соединения;
2. AC12 — добавить пункт: «источник для лимита не может быть выбран клиентом
   через заголовки»;
3. §14.4 — добавить строку: «клиент посылает поддельный `X-Forwarded-For` →
   получает собственную корзину лимита → тест красный».

### Low (не блокирует, можно снять с записью)

Продакшн-канал `ha_webhook` целиком зависит от одной автоматизации на личном
Home Assistant мейнтейнера («House Plan: приёмщик обратной связи → личка»,
`scripts/support-relay/README.md:151-152`). Ротация вебхука прямо требует
правки этой автоматизации, но её конфигурация не задокументирована и не
сохранена нигде в репозитории — только упоминание, что она существует. Отказ
этого узла не теряет данные и не обманывает пользователя (отчёт остаётся в
спуле, клиент честно получает `support_unavailable` — проверено чтением
`hp_relay/app.py:110-116`), поэтому это не приватность/безопасность и не
блокирует зелёный; но при потере доступа к личному HA мейнтейнера
восстановление доставки требует пересоздания автоматизации «с нуля» без
письменной инструкции. Стоит одной строкой в `scripts/support-relay/README.md`
зафиксировать минимальную конфигурацию вебхука (принимает POST, поле `text`,
пересылает в Telegram), не дожидаясь следующего цикла.

## Что проверено и признано корректным

- **Два канала доставки (`telegram`/`ha_webhook`) в §9.1** описаны в ТЗ
  консистентно с кодом: `hp_relay/delivery.py:141-203` (`TelegramDelivery`,
  `HaWebhookDelivery`, `build()`) реализует ровно то, что описано —
  вложение остаётся в спуле и не покидает узел на канале `ha_webhook`
  (`hp_relay/delivery.py:168-188`, тест
  `test_webhook_sends_text_and_keeps_the_package_on_the_node`).
- **«Запись до попытки доставки» (§9.1, «a failed delivery costs a promise, not
  the user's request»)** — подтверждено чтением: `app.py:107-116` вызывает
  `store.save()` до `delivery.send()`, а при неуспехе возвращает
  `support_unavailable`, не удаляя отчёт.
- **Privacy-текст §9.3** («exact geometry ... transit the project relay and the
  maintainer messenger») намеренно описывает худший случай для обоих каналов,
  а не конкретно активный канал: фронтенд не знает, какой канал выбран на
  деплое (это решение эксплуатации, §9.1 «chosen by deployment»), поэтому
  общая (не заниженная) формулировка — осознанный выбор, а не забытая правка.
  Проверено сопоставлением с `hp_relay/config.py:66-68` (канал — переменная
  окружения, недоступная фронтенду).
- **§17 DoR** обновлён согласованно с новым каналом (пункт 2 — путь к секрету
  вебхука как учётные данные), пункты 1/3/4/5 отражены в отдельных комментариях
  владельца как реально выполненные на стенде — вне объёма самого текста ТЗ,
  но не противоречат ему.
- **Лимиты §7.5/§9.5** (8 MiB / 8.5 MiB) совпадают с кодом:
  `hp_relay/config.py:15-16` (`MAX_REQUEST_BYTES`, `MAX_ATTACHMENT_BYTES`).
- **Классификация class B** (`scripts/support-relay/**`) остаётся верной после
  роста дерева — `process-gate.mjs` не меняла regex, живой прогон на HEAD это
  подтверждает.
- **SCOPE.md** проверен на предмет открытых вопросов дельты: раздел «Where
  users are» фиксирует уже существующий *публичный* support-чат
  `t.me/ha_houseplan` как канал общей обратной связи — пивот к *приватному*
  каналу мейнтейнера в r3 ему не противоречит и не подменяет его, они решают
  разные задачи (публичный сигнал vs. приватный geometry-репорт). Собственно
  вопрос «попадает ли фича в Core user jobs» дельтой r2→r3 не поднимается
  (§1–§6 не менялись) и наследуется как принятый в r1/r2.

## Чего не проверял и почему

- `npm test` / `npm run build` (сверка трёх копий бандла) / `node
  scripts/check-docs.mjs` — дельта не касается `src/**`, предмета проверки нет.
- `python -m pytest tests_backend -q` — дельта не касается
  `custom_components/**` (relay — отдельный сервис вне HA-интеграции).
- `npm run invariants` / инварианты модели — дельта не касается геометрии,
  `layout`, `marker.space`, `open_spans` или толщины стен.
- Браузерные смоки, `npm run golden:verify` — фронтенд-часть фичи (§1–§8) ещё
  не реализована, `src/**` не тронут.
- Полный аудит `scripts/support-relay/hp_relay/{multipart,validate}.py` — эти
  файлы не входят в дельту r2→r3 (не менялись коммитами `6b10cd52`/`c7efcf16`/
  `c43bf847` за пределами уже описанного), их корректность — предмет будущего
  code-review по §13 AC5–AC12, а не этого spec-раунда.

## Гейты, которые прогнал сам (зелёного Validate на `c43bf847` нет)

- `node scripts/process-gate.mjs` → «гейт пройден, предупреждений 0» (диапазон
  `origin/dev..HEAD`, 8 коммитов, офлайн).
- `npx tsc --noEmit` → 0 ошибок (дельта не трогает `src/**`, прогнан как
  дешёвая проверка базовой линии).
- `python3 -m unittest discover -s scripts/support-relay/tests` → **35
  проверок, все зелёные**, включая `test_client_cannot_pick_its_own_rate_bucket`
  и `test_webhook_sends_text_and_keeps_the_package_on_the_node`.
- Дисциплина «тест должен уметь падать» проверена для обоих названных выше
  тестов лично, мутациями (изменения отменены после проверки, `git status`
  чист):
  - `forwarded.split(",")[-1]` → `[0]` (доверие первому, клиентскому элементу
    XFF вместо последнего, проксёй-контролируемого) — тест
    `test_client_cannot_pick_its_own_rate_bucket` упал (3 корзины вместо 1);
  - `HaWebhookDelivery.send` начинает прикладывать байты вложения в JSON
    вебхука — тест `test_webhook_sends_text_and_keeps_the_package_on_the_node`
    упал (лишнее поле `attachment` в теле).