feat: optional password encryption for backup and domain export (code-review.md § Phase 1.5)

Both secret-bearing downloads can now be sealed with a password. Unticked, the forms produce exactly the files they did before. - internal/secretfile: envelope format — magic/type/scrypt params/salt/nonce prefix header, then 64 KiB AES-256-GCM chunks each authenticated with the header, its counter and an end-of-stream flag, so truncation, reordering and tampering fail to open instead of restoring a plausible prefix. Streams both ways, so a full backup never sits in memory. - Panel: "Encrypt with a password" checkbox on the full-backup and domain-export forms (shared partial, toggled from panel.js — no inline script); domain import detects an encrypted export by magic bytes, not by extension, and asks for the password. - selfpost-backup: writes .spbk when given a password and converts one back with -decrypt, which a restore needs. The password comes from SELFPOST_BACKUP_PASSWORD or -password-file, never argv. - Docs: README, security.md (+ accepted risk: encryption stays opt-in), architecture.md, progress.md, CHANGELOG. Verified locally: panel-encrypted archive decrypts through the CLI and unpacks; wrong password and password mismatch are refused; UI checked in a browser. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-06 16:43:28 +03:00
parent 670982fb3e
commit 6a7d010868
20 changed files with 1402 additions and 36 deletions
@@ -176,6 +176,15 @@ Not in `/data`: TLS certificates (reverse-proxy mount), Postfix queue
 `/data` tree; version check on restore. Stopped-container `tar` of `./data` is
 safe (see README).

+**Optional encryption** of the two secret-bearing downloads
+([internal/secretfile](../internal/secretfile/secretfile.go)): password →
+scrypt → AES-256-GCM over 64 KiB chunks, each authenticated with the header,
+its counter and an end-of-stream flag (so truncation and reordering fail to
+open). Full backup `.tar.gz` → `.spbk`, domain export `.json` → `.spde`; the
+plain forms remain the default. Domain import detects the envelope by magic
+bytes; an encrypted full backup is converted back with `selfpost-backup
+-decrypt` before restore.
+
 ---

 ## Security (summary)
@@ -219,7 +219,7 @@ E2E покрывает: bootstrap, SMTP AUTH, DKIM, send-log lifecycle, negative
 | CSRF without tokens | POST без Origin/Sec-Fetch-Site пропускается | [security.md](security.md) |
 | Fail-open L2 rate limit | DB error → mail проходит | [`internal/milter/ratelimit.go`](../internal/milter/ratelimit.go) |
 | Shallow SPF check | Не следует `include:`/`redirect=` | README, `internal/dnscheck/spf.go` |
-| Plaintext backup/export at rest | DKIM-ключи, SASL, пароли приложений в cleartext `.tar.gz`/`.json` | **Mitigation:** R13 (optional encryption) |
+| Plaintext backup/export at rest | DKIM-ключи, SASL, пароли приложений в cleartext `.tar.gz`/`.json` | **Закрыто:** R13 — опциональное шифрование (`.spbk`/`.spde`); открытый вариант остаётся умолчанием, риск переформулирован в [security.md](security.md) |

 **Не риск (решение оператора):** «Session resurrection from backup» — снято из [security.md](security.md).

@@ -234,7 +234,7 @@ E2E покрывает: bootstrap, SMTP AUTH, DKIM, send-log lifecycle, negative
 | # | Действие | Приоритет | Модель |
 |---|----------|-----------|--------|
 | L1 | **Предрелизный security review** (§ D) — обязательный гейт | **P0** | **Fable** |
-| L2 | **Шифрование бэкапа и экспорта домена** (R13) — optional, checkbox + password | P1 | **Opus** + Sonnet |
+| L2 | **Шифрование бэкапа и экспорта домена** (R13) — optional, checkbox + password — **выполнено** | P1 | **Opus** + Sonnet |
 | L3 | Send-log gap mitigation — опционально | P2 | Opus |
 | L4 | Transaction wrap для rate limit count+insert — опционально | P3 | Opus |

@@ -352,7 +352,7 @@ Go `html/template` + HTMX polling + [`panel.css`](../internal/web/static/panel.c
 | R6 | GUI: visibility-aware HTMX polling | Sonnet |
 | R7 | CONTRIBUTING.md | Sonnet |
 | R8 | ADR для CSRF policy | Sonnet |
-| R13 | Шифрование бэкапа и экспорта домена (checkbox + password) | **Opus** + Sonnet |
+| R13 | Шифрование бэкапа и экспорта домена (checkbox + password) — **выполнено** | **Opus** + Sonnet |

 ### v2.x (roadmap, не начинать без согласования)

@@ -384,7 +384,16 @@ Go `html/template` + HTMX polling + [`panel.css`](../internal/web/static/panel.c
 5. Sonnet: bump compose image tag + Codeberg URLs (в том же release commit)
 6. Git tag vX.Y.Z

-### Фаза 1.5 — Шифрование резервных копий (P1, v1.x)
+### Фаза 1.5 — Шифрование резервных копий (P1, v1.x) — **выполнено 2026-08-06**
+
+Реализовано как спланировано: `internal/secretfile` (E1) → `selfpost-backup`
+ панель (E2) → экспорт/импорт домена (E3) → UI-чекбокс (E4) → docs (E5).
+Отличия от плана: конверт потоковый (64 KiB чанки AES-256-GCM с AAD
+`header+counter+last`), а не одноблочный, иначе полный бэкап пришлось бы
+держать в памяти целиком; манифест остался внутри tar, то есть внутри
+шифротекста, как и планировалось; в CLI добавлен режим `-decrypt` — без него
+зашифрованный бэкап нечем распаковать при restore. Детали —
+[progress.md](progress.md), CHANGELOG `[Unreleased]`.

 **Проблема:** полный бэкап и экспорт домена содержат DKIM-ключи, SASL-креды и plaintext-пароли приложений; сейчас `.tar.gz` / `.json` без шифрования.

@@ -51,7 +51,8 @@
 - **Рецензирование кодовой базы** (2026-08-05): [code-review.md](code-review.md) — 10 разделов (архитектура, качество, docs, GUI, legacy, риски), приоритизированный план реализации и маршрутизация моделей. Критичных багов не найдено; блокер релиза — § D ниже.
 - **§ D выполнен (2026-08-06):** предрелизная ревизия безопасности моделью Fable — диф от аудита v1.0 (Фаза 11, `bd64e80`) до HEAD + полный проход по чек-листу [security.md](security.md) (бывшее ТЗ 7.6). Эксплуатируемых находок нет; одна правка defence-in-depth (`--` перед логином в argv `saslpasswd2`, `internal/app/sasl.go` + тест). Принятые риски не пополнились. Детали — [implementation-plan.md](implementation-plan.md) § D и CHANGELOG `[Unreleased]/Security`. Локально `go vet`/`go test ./internal/app/...` чистые; падения `internal/domain` (`TestWriteLoadPrivateKeyRoundtrip`, `TestRenderTables`) и `internal/logtail` (`TestFollowTailsAndRotates`) — Windows-специфика (права файлов/`\` в путях/rename открытого файла), на Linux CI зелено.
 - **Фаза 1 выполнена (2026-08-06)** ([code-review.md](code-review.md) § Фаза 1 — doc/code hygiene, P1): cleanup ~30 stale «Phase N» комментариев в коде и shell-скриптах; исправлен stale-комментарий в `handlers_domains.go`; ADR CSRF (Origin vs токены) добавлен в [security.md](security.md); known-limitations по log-tailer уже был в [architecture.md](architecture.md) § Log tailer — отдельного действия не потребовалось; `docs/logo` в [roadmap.md](roadmap.md) закрыт (каталога нет, критерию соответствует); `gofmt -l` добавлен в CI (`.github/workflows/test.yml`). `gofmt`/`go vet`/`go test ./...` чистые в обоих модулях (dev-server).
- **Дальше:** релизный гейт (Фаза 0) закрыт по существу — e2e C.4 и ревизия § D пройдены; остаются только шаги, которые делаются в момент резки версии (бамп тега образа + Codeberg URL, git tag) по явной команде пользователя. Остальные пункты из [code-review.md](code-review.md) — polish (фазы 2–3, 1.5).
+- **Фаза 1.5 выполнена (2026-08-06)** ([code-review.md](code-review.md) § Фаза 1.5 — шифрование резервных копий, P1): новый пакет `internal/secretfile` — конверт `magic SELFPOST1 | type | scrypt-параметры | salt | nonce-prefix` + поток 64 KiB чанков AES-256-GCM, каждый с AAD `header+counter+last`, поэтому обрезка, перестановка и подмена не открываются (стриминг в обе стороны — полный бэкап не держится в памяти). Панель: чекбокс «Encrypt with a password» в форме полного бэкапа и экспорта домена (общий партиал `templates/encrypt_fields.html`, показ/очистка полей — `panel.js`, без inline-скриптов), импорт домена принимает `.spde` (шифрование определяется по magic, не по расширению) с полем пароля. CLI `selfpost-backup`: пишет `.spbk` при заданном пароле и умеет `-decrypt` (иначе зашифрованный бэкап нечем распаковать при restore); пароль — только `SELFPOST_BACKUP_PASSWORD` / `-password-file`, никогда argv. Умолчание не изменилось: галочка снята — прежние `.tar.gz` / `.json` байт в байт. Тесты: round-trip по размерам (0, границы чанка, несколько чанков), неверный пароль, обрезка, перестановка чанков, порча байта, чужие KDF-параметры; валидация формы пароля; round-trip CLI create→decrypt→tar. Docs: README § *Encrypting a backup or export*, [security.md](security.md) § «Резервная копия и экспорт домена» + принятый риск (шифрование опционально), [architecture.md](architecture.md) § Persistence. `gofmt`/`go vet`/`go test ./...` чистые (кроме известных Windows-падений `internal/domain`, `internal/logtail`). E2E-сценарий не добавлялся: в `test/e2e/` бэкапа не было и раньше, а прогнать новый тест локально нечем (нет Docker) — кандидат при следующем прогоне на dev-сервере.
+- **Дальше:** релизный гейт (Фаза 0) закрыт по существу — e2e C.4 и ревизия § D пройдены; остаются только шаги, которые делаются в момент резки версии (бамп тега образа + Codeberg URL, git tag) по явной команде пользователя. Остальные пункты из [code-review.md](code-review.md) — polish (фазы 2–3).
 - **Принятые риски** — [security.md](security.md). **Опционально v1.x / 2.x** — [roadmap.md](roadmap.md) (хвост документации, send-log gaps, Фаза O1+, роль администратора домена).
 - **Прод:** `selfpost.example.com`, реальный Let's Encrypt сертификат, живой e2e (DKIM/SPF pass). Контейнер там всё ещё на образе v1.0 — Фаза 14 в него не выкатывалась. При апгрейде: админа один раз разлогинит (сменилось имя cookie), а от reverse-proxy требуется передача исходного `Host` (Apache-фрагмент из `deploy/` это делает).

@@ -70,6 +70,25 @@ Hardening сверх обязательного (security-заголовки, п
 - `TRUSTED_PROXY_CIDR` — только явно доверенные прокси для `X-Forwarded-For`
  при rate-limit логина; пусто = XFF игнорируется.

+### Резервная копия и экспорт домена
+
+- Оба файла — секреты: полный бэкап несёт DKIM-ключи, `sasldb2` и хеш пароля
+  админа; экспорт домена — DKIM-ключ и **рабочие** пароли приложений открытым
+  текстом (иначе перенос без пересоздания кредов невозможен).
+- Оба скачивания можно зашифровать паролем (чекбокс в форме): scrypt
+  (N=2¹⁵, r=8, p=1) → AES-256-GCM, поток из 64 KiB чанков, каждый
+  аутентифицирован заголовком, номером и флагом конца потока — обрезанный или
+  подменённый файл не открывается вместо тихого восстановления «хвоста».
+  Формат и обёртка: [internal/secretfile](../internal/secretfile/secretfile.go).
+- Расширения: `.spbk` (полный бэкап), `.spde` (экспорт домена); незашифрованные
+  остаются `.tar.gz` / `.json`. Импорт домена определяет шифрование по magic
+  файла, а не по расширению.
+- Пароль нигде не сохраняется: восстановить файл без него нельзя. Пароль в CLI —
+  только через `SELFPOST_BACKUP_PASSWORD` или `-password-file`, никогда
+  аргументом (список процессов читается любым процессом контейнера).
+- Минимальная длина пароля — как у пароля администратора (12): файл лежит
+  offline и подбирается без ограничений по времени.
+
 ---

 ## Принятые риски
@@ -93,6 +112,12 @@ Hardening сверх обязательного (security-заголовки, п
  панели, отправит запрос сам — против этого работают автоэкранирование
  `html/template` и CSP, поэтому шаблоны не должны содержать
  inline-скриптов и inline-стилей.
+- **Шифрование бэкапа и экспорта — опция, а не умолчание.** Галочка снята —
+  файл скачивается открытым, как в 1.0. Иначе оператор, у которого нет места
+  для хранения пароля, потерял бы возможность сделать бэкап вообще, а
+  безвозвратно нерасшифровываемый архив хуже незашифрованного: пароль SelfPost
+  не хранит. Триггером сделать шифрование обязательным считать появление
+  второго администратора (тогда «кто скачал» перестаёт быть одним человеком).
 - **Send-log может навсегда остаться `queued` после рестарта панели или
  пересоздания контейнера.** Log-tailer стартует с конца `mail.log`; файл не в
  `/data` и теряется при recreate. Rename-ротация это не лечит. См. [architecture.md](architecture.md)