mix
9c31649941
12-phase plan derived from the spec, plus a durable progress tracker (model-per-phase, resume-after-reset protocol, commit conventions). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
218 lines
21 KiB
Markdown
218 lines
21 KiB
Markdown
# План реализации: SelfPost
|
||
|
||
**Статус:** черновик для согласования (см. ТЗ, раздел 12, п. 7 — план утверждается до начала кодирования).
|
||
**Основа:** [specification.md](specification.md) v1.0.
|
||
|
||
Принцип движения (ТЗ 12.4): сначала минимальный работающий скелет (образ собирается, три процесса стартуют, пустая панель с логином), затем итеративное наращивание. Требования безопасности раздела 7.6 закладываются сразу в соответствующих эндпоинтах, а не «потом» (ТЗ 12.5). Коммиты — только по явной команде (ТЗ 12.1).
|
||
|
||
---
|
||
|
||
## Зафиксированные технические решения (до кодирования)
|
||
|
||
Эти выборы предлагается утвердить вместе с планом — они влияют на всю структуру.
|
||
|
||
| Решение | Выбор | Обоснование |
|
||
|---|---|---|
|
||
| Module path | `codeberg.org/mix/selfpost` | основной репозиторий — Codeberg (ТЗ 11.7) |
|
||
| Базовый образ | `debian:bookworm-slim` | зафиксировано ТЗ 4 |
|
||
| SQLite-драйвер | `modernc.org/sqlite` (чистый Go, BSD-3) | сохраняет статический бинарник без cgo; лицензия permissive (ТЗ 7.1, 12.8) |
|
||
| bcrypt | `golang.org/x/crypto/bcrypt` (BSD) | хэш пароля админа (ТЗ 7.6.1) |
|
||
| milter | `github.com/emersion/go-milter` (MIT) | единственный жизнеспособный вариант; **требует ранней проверки совместимости** (ТЗ 7.3, риск) |
|
||
| Front-end | `html/template` + вендоренный HTMX, без npm/SPA | зафиксировано ТЗ 7.1 |
|
||
| Версия в бинарнике | `-ldflags "-X main.version=..."` | для проверки совместимости бэкапа (ТЗ 7.5.А, 11.1) |
|
||
|
||
Каждая внешняя зависимость обоснована и permissive/GPL-совместима (ТЗ 12.8). Больше сторонних зависимостей без согласования не вводим.
|
||
|
||
**Предлагаемая структура репозитория:**
|
||
```
|
||
cmd/panel/ — main панели (HTTP + milter + log-tailer + rate-limit)
|
||
cmd/selfpost-backup/ — CLI-утилита бэкапа (ТЗ 11.6)
|
||
internal/store/ — SQLite: схема, миграции, запросы
|
||
internal/domain/ — доменная модель, DKIM, OpenDKIM KeyTable/SigningTable
|
||
internal/app/ — приложения, SASL (sasldb2), sender_login_maps
|
||
internal/postfix/ — генерация конфигов, reload, escaping
|
||
internal/milter/ — journal-milter + rate-limit level 2
|
||
internal/logtail/ — хвост mail.log, обновление статусов
|
||
internal/web/ — хендлеры, сессии, setup-link, middleware
|
||
internal/backup/ — полный бэкап/restore, экспорт/импорт домена
|
||
web/templates/ — html/template
|
||
web/static/ — вендоренный htmx.min.js
|
||
build/ — Dockerfile, supervisord.conf, стартовые скрипты, шаблоны конфигов, logrotate
|
||
deploy/ — docker-compose.yml (Apache) + фрагменты nginx/Caddy/Traefik
|
||
```
|
||
|
||
Тестовый стенд: `ssh root@selfpost.example.com` (PTR настроен, порт 25 предполагается открытым) — [dev/env.txt](../dev/env.txt). Секреты разработки — только в `dev/` (в `.gitignore`).
|
||
|
||
---
|
||
|
||
## Фаза 0 — Каркас проекта и де-риск milter'а
|
||
|
||
**Цель:** структура готова, критический риск проверен до того, как в него вложено много кода.
|
||
|
||
- `go mod init`, структура каталогов, пустые пакеты, `main.version`.
|
||
- `LICENSE` — полный текст AGPL-3.0 (ТЗ 11.9).
|
||
- Скелет `README.md`, Makefile/скрипты сборки с ldflags-версией.
|
||
- **Спайк по milter (де-риск, ТЗ 7.3):** на тестовом сервере поднять голый Postfix из Debian bookworm + минимальный go-milter, убедиться, что версия протокола совместима и что milter читает `From`/`To`/`Subject`/SASL-login на этапе EOH. Проверить поведение `milter_default_action` при падении/таймауте milter'а (fail-open). Результат спайка — краткая заметка в `dev/`.
|
||
|
||
**Готово, когда:** `go build`/`go vet` проходят на пустом каркасе; спайк подтвердил работоспособность go-milter с Postfix из образа (или зафиксировал альтернативу).
|
||
|
||
---
|
||
|
||
## Фаза 1 — Образ + supervisord + три процесса (минимальный скелет)
|
||
|
||
**Цель:** `docker build` собирает образ, контейнер стартует, три процесса живы, пустая панель отвечает на `:8080`.
|
||
|
||
- `Dockerfile` (bookworm-slim): postfix, opendkim, cyrus-sasl (`sasldb2`, `sasl2-bin`), supervisor, logrotate, ca-certificates; сборка Go-бинарников многостадийно.
|
||
- `supervisord.conf` с `priority=`: OpenDKIM → panel → (обёртка) Postfix; при неперезапускаемом падении любого процесса контейнер завершается (ТЗ 4).
|
||
- **Стартовая обёртка Postfix**: опрос готовности milter-сокетов OpenDKIM и journal-milter (`test -S`, интервал, таймаут ~30с), запуск `postfix start-fg` только после готовности обоих; при таймауте — выход с ошибкой (ТЗ 4).
|
||
- Панель: HTTP `:8080` с заглушкой, **stub-listener journal-milter** (создаёт сокет, чтобы обёртка проходила), stub log-tailer.
|
||
- Непривилегированный пользователь для панели (ТЗ 7.6.8).
|
||
|
||
**Готово, когда:** образ собирается, `docker run` даёт три живых процесса, панель отдаёт заглушку, обёртка корректно ждёт сокеты.
|
||
|
||
---
|
||
|
||
## Фаза 2 — Персистентность, инициализация админа, вход
|
||
|
||
**Цель:** безопасный вход в панель одного администратора.
|
||
|
||
- SQLite-схема + миграции: домены, приложения, админ, `send_log`, лимиты, настройки, флаг «настройка завершена»/setup-токен (ТЗ 9). Единый корень `/data` (ТЗ 7.5.А, 9).
|
||
- **Setup secret-link (ТЗ 7.6.1):** токен ≥128 бит из `crypto/rand`; вывод в stdout + `/data/setup-token`; TTL 10 мин с перегенерацией; rate-limit маршрута; `subtle.ConstantTimeCompare`; неудачи НЕ инвалидируют токен; одноразовая форма создания админа; инвалидация навсегда после успеха (маршрут → 404).
|
||
- bcrypt-хэш пароля админа; никакого plaintext.
|
||
- Логин, сессии (крипто-случайный токен, cookie `HttpOnly`/`Secure`/`SameSite`), rate-limit логина (ТЗ 7.6.5–6).
|
||
- Базовый layout `html/template`, вендоренный HTMX, middleware аутентификации.
|
||
|
||
**Готово, когда:** первый запуск печатает setup-ссылку, админ создаётся один раз, повторный `/setup` → 404, вход/выход работают, токены сессий безопасны.
|
||
|
||
---
|
||
|
||
## Фаза 3 — Домены + OpenDKIM
|
||
|
||
**Цель:** добавление/удаление домена с генерацией DKIM.
|
||
|
||
- Добавить/список/удалить домен; при удалении — предупреждение о каскадном удалении приложений (ТЗ 7.2.4).
|
||
- Генерация DKIM-ключа + селектор per-domain (дефолт из `DKIM_SELECTOR_DEFAULT`); ключи в `/data/...` переживают рестарт (ТЗ 6, 9).
|
||
- Поддержка `KeyTable`/`SigningTable`, reload OpenDKIM.
|
||
- Показ DKIM TXT-записи per-domain (ТЗ 7.2.10).
|
||
- **Безопасная запись конфигов** с санитизацией/экранированием (ТЗ 7.6.4); `os/exec` без shell и без интерполяции ввода (ТЗ 7.6.3); строгая валидация имени домена (whitelist символов, ТЗ 7.6.2).
|
||
|
||
**Готово, когда:** домен добавляется/удаляется, DKIM-ключ генерируется и переживает рестарт, TXT-запись показывается, OpenDKIM перечитывает таблицы.
|
||
|
||
---
|
||
|
||
## Фаза 4 — Приложения + SASL + привязка к домену
|
||
|
||
**Цель:** ядро доменной модели (ТЗ 4.1, 5.1).
|
||
|
||
- Создание учётки в `sasldb2` (эквивалент `saslpasswd2`), генерация сильного пароля, показ **один раз** (ТЗ 7.6.1).
|
||
- Режим адресов на уровне приложения: «любой адрес домена» (wildcard `@example.com`) либо «список» (запись на каждый адрес); серверная валидация принадлежности каждого адреса домену приложения (ТЗ 7.6.2).
|
||
- Поддержка `smtpd_sender_login_maps` соответственно режиму; many-to-one.
|
||
- Список приложений домена с текущим режимом; редактирование режима; удаление приложения (только его записи); перевыпуск пароля (режим сохраняется) — с `postfix reload` (ТЗ 7.2.5–9).
|
||
|
||
**Готово, когда:** приложения создаются/редактируются/удаляются, карта привязки корректно пересобирается, пароль показывается один раз.
|
||
|
||
---
|
||
|
||
## Фаза 5 — Полная конфигурация Postfix (исходящий релей)
|
||
|
||
**Цель:** реальная отправка почты с аутентификацией и DKIM.
|
||
|
||
- `master.cf`: `smtps` 465 (wrapper TLS, `smtpd_tls_wrappermode=yes`) как основной; `submission` 587 (STARTTLS, `smtpd_tls_auth_only=yes`) — опционально, тем же способом (ТЗ 5, 5.1).
|
||
- SASL (`smtpd_sasl_auth_enable`), TLS cert/key из `TLS_CERT_FILE`/`TLS_KEY_FILE` (read-only mount), периодический `postfix reload` для обновления сертификата (ТЗ 5.2).
|
||
- `smtpd_recipient_restrictions` (`permit_sasl_authenticated`, `reject_unauth_destination`), `smtpd_sender_restrictions` + `reject_sender_login_mismatch`; **никакого open relay** (ТЗ 5.4, 5.1.3).
|
||
- Исходящая доставка напрямую (MX-lookup, `smtp_tls_security_level=may`).
|
||
- Уровень 1 rate-limit (`anvil`: `smtpd_client_message_rate_limit`, `anvil_rate_time_unit`) из env (ТЗ 5.5, 7.4).
|
||
- Milter-цепочка `smtpd_milters`: OpenDKIM + journal-milter; `milter_default_action` для journal — **fail-open** (ТЗ 7.3).
|
||
|
||
**Готово, когда:** с тестового сервера письмо реально уходит получателю, подписано DKIM, аутентификация обязательна, привязка отправителя работает, неаутентифицированный релей отклоняется.
|
||
|
||
---
|
||
|
||
## Фаза 6 — Journal-milter и обновление статусов (Send Log, бэкенд)
|
||
|
||
**Цель:** структурированный журнал отправки. **Самый чувствительный узел (ТЗ 7.3) — повышенное внимание к тестам.**
|
||
|
||
- Реализация journal-milter на go-milter: на EOH читает домен, SASL-login, From, To, Subject; создаёт запись `send_log` со статусом «в очереди», привязка к queue-id.
|
||
- Отдельная запись на пару (queue-id, получатель) (ТЗ 7.3.3).
|
||
- Log-tailer: горутина хвостит `mail.log`, парсит `sent`/`bounced`/`deferred` по queue-id, обновляет записи.
|
||
- Retention: фоновая очистка старше `SEND_LOG_RETENTION_DAYS` (дефолт 90).
|
||
- **Тесты отказа:** поведение при падении/таймауте milter'а — приём почты не блокируется (fail-open проверяется явно).
|
||
|
||
**Готово, когда:** отправленное письмо порождает запись, статус доходит до финального, ретеншн чистит старое; убийство milter'а не роняет приём почты.
|
||
|
||
---
|
||
|
||
## Фаза 7 — UI мониторинга (журнал, очередь, лог)
|
||
|
||
**Цель:** экраны наблюдения с автообновлением.
|
||
|
||
- Журнал отправки: таблица (время, домен, приложение, From, To, Subject, статус), **серверные фильтры** по домену и приложению (`WHERE`), пагинация, HTMX-polling; экранирование вывода (ТЗ 7.3, 7.6.7).
|
||
- Просмотр очереди (`postqueue -p` в читаемом виде), HTMX-polling (ТЗ 7.2.11).
|
||
- Хвост `mail.log`, HTMX-polling (ТЗ 7.2.13).
|
||
- Кнопка ручного reload (ТЗ 7.2.12).
|
||
- Fragment-эндпоинты возвращают HTML-куски, не JSON (ТЗ 7.1).
|
||
|
||
**Готово, когда:** три экрана работают, фильтры серверные, автообновление через polling, вывод экранирован.
|
||
|
||
---
|
||
|
||
## Фаза 8 — Дифференцированные лимиты (rate limit уровень 2)
|
||
|
||
**Цель:** лимиты на домен/приложение поверх backstop уровня 1.
|
||
|
||
- Настройка в панели: ожидаемые IP + лимит (N писем за окно) на уровне домена и приложения; оба необязательны; пустая IP-привязка допустима (ТЗ 7.4).
|
||
- Проверка в milter: ключ — client IP; счётчик из SQLite (переиспользует данные журнала); превышение → отказ 4xx + опциональная запись «отклонено по лимиту»; **fail-open** при недоступности milter'а (ТЗ 7.4).
|
||
|
||
**Готово, когда:** лимит на домен/приложение срабатывает (4xx), пустая привязка не ломает отправку, при падении milter'а остаётся уровень 1.
|
||
|
||
---
|
||
|
||
## Фаза 9 — Бэкап/восстановление и экспорт/импорт домена
|
||
|
||
**Цель:** переезд «прост как архив» + перенос одного домена.
|
||
|
||
- **Полный бэкап (ТЗ 7.5.А):** архив всего `/data` (SQLite через `VACUUM INTO`/Backup API для консистентного снимка на живом контейнере, DKIM-ключи, `sasldb2`, `manifest.json` с версией). Без TLS-сертификатов и очереди Postfix.
|
||
- Кнопка в панели + **CLI `selfpost-backup`** через `docker exec` (ТЗ 11.6).
|
||
- **Restore:** сверка версии манифеста с версией бинарника; при несовпадении — отказ с понятным сообщением (какой тег образа нужен); состояние регенерируется из SQLite тем же путём, что при обычном старте, без отдельной ветки restore (ТЗ 7.5.А).
|
||
- **Экспорт/импорт домена (ТЗ 7.5.Б):** файл с именем домена, DKIM-ключом/селектором, приложениями и их записями `sasldb2` (рабочие пароли без перевыпуска); импорт восстанавливает домен без смены DNS. Файл помечается как секрет.
|
||
|
||
**Готово, когда:** бэкап скачивается (панель и CLI), restore на чистом контейнере той же версии поднимает всё без пере-настройки; несовпадение версии отклоняется; экспорт/импорт домена переносит рабочие креды.
|
||
|
||
---
|
||
|
||
## Фаза 10 — Деплой и документация
|
||
|
||
**Цель:** поставка и эксплуатационная документация.
|
||
|
||
- `docker-compose.yml`: **Apache** как основной reverse-proxy «из коробки», **фиксированный тег версии** (не `:latest`), bind mount `./data:/data` + read-only mount сертификатов, hardening (non-root, `cap_drop`, ограничение ФС) (ТЗ 10, 9).
|
||
- Альтернативные фрагменты: nginx, Caddy (проверить актуальный путь хранилища), Traefik (шаг извлечения PEM) (ТЗ 10.3).
|
||
- `logrotate` для `mail.log` в образе (ежедневно, 7–14 файлов, ТЗ 9).
|
||
- `README.md`: требования к площадке (чеклист), настройка DNS per-domain (SPF/DKIM/DMARC + PTR), прогрев IP, процедуры бэкапа/restore и экспорта/импорта (оба файла — секреты), фиксированный тег, требования к машине, лицензия AGPL-3.0 и её смысл, ссылки Codeberg (основной)/GitHub (зеркало) (ТЗ 10, 11.7).
|
||
|
||
**Готово, когда:** `docker compose up` за Apache поднимает рабочий стенд; README покрывает установку, DNS, бэкап/миграцию, лицензию.
|
||
|
||
---
|
||
|
||
## Фаза 11 — Финальный проход по безопасности и приёмка
|
||
|
||
**Цель:** соответствие разделу 7.6 и критериям ТЗ 12.
|
||
|
||
- Аудит: панель не под root и права ФС; серверная валидация ввода; `os/exec` без shell; экранирование всего вывода из логов/очереди; санитизация записи в конфиги; флаги cookie; rate-limits (setup, логин).
|
||
- `go build`, `go vet`, `go test`; `docker build`; проверка старта контейнера (ТЗ 12.2–3).
|
||
- Опционально: `/security-review` по диффу ветки.
|
||
|
||
**Готово, когда:** все пункты 7.6 подтверждены, сборка/вет/тесты/образ зелёные, контейнер стартует чисто.
|
||
|
||
---
|
||
|
||
## Ключевые риски и как их снимаем
|
||
|
||
1. **Go-milter (ТЗ 7.3)** — самый рискованный узел (баг ломает не только журнал, а сам релей). Снимается ранним спайком (Фаза 0) и явными тестами отказа (Фаза 6), fail-open через `milter_default_action`.
|
||
2. **Холодный старт milter-сокетов** — обёртка Postfix ждёт готовности сокетов (Фаза 1).
|
||
3. **Версионирование бэкапа** — фиксированный тег образа + проверка манифеста (Фазы 9–10).
|
||
4. **Открытый релей / утечка кред** — привязка `sender_login_maps` + `reject_sender_login_mismatch`, обязательный SASL, отсутствие `mynetworks`-авторизации (Фаза 5).
|
||
|
||
## Порядок и зависимости
|
||
|
||
Фазы линейны по зависимостям (0→1→2→3→4→5→6→7→8→9→10→11), кроме спайка milter (0), который де-рискует Фазу 6 заранее. После каждой фазы — работающий инкремент, пригодный для проверки на тестовом сервере.
|