Ochenstarik 4de849e3bf docs: add product horizons, approval policies and KAgent integration spec

Adopt the reviewed parts of the external vision document as repository
specifications, and record the work-order gates that keep unimplemented
subsystems from starting before their prerequisites are closed.

- product-horizons.md: four horizons with hard exit criteria; Horizon 0
  closes physical acceptance, signed delivery, the Monitor role and
  certificate rotation before anything new begins.
- approval-policies.md: nine approval modes over the existing binary
  confirmation, mapped onto ProvisioningJob, TTL and execution grants.
- integration-kagent.md: capability model split into read, request and
  never-grantable; untrusted-executor invariant for KAgent Worker;
  SO_PEERCRED on the discovery socket; API designed against entities
  that exist today.
- security-model.md: untrusted executors on a Node, the public web
  surface decision that must be recorded before that work starts, and
  never-grantable capabilities.
- roadmap.md: stages 14-18 for the adopted scope, pinned to horizons.

All three new documents state that nothing in them is implemented.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-08-06 18:31:09 +07:00

8.8 KiB

Raw Permalink Blame History

Горизонты продукта и гейты

Этот документ управляет очерёдностью работ. Roadmap отвечает на вопрос «что сделано», этот документ — на вопрос «что разрешено начинать».

Правило

Горизонт закрывается целиком. Переход к следующему запрещён, пока не выполнены все критерии выхода текущего. Критерий, сформулированный через фактическое поведение системы, закрывается только измерением на реальной топологии; зелёный CI его не заменяет.

Причина правила: безопасность всех последующих функций держится не на их собственном коде, а на том, что typed provisioning, approval, audit, execution grant, factual verification и emergency recovery работают в действительности. Сегодня мутирующий provisioning выполняет одно действие — смену таймзоны. Пока это так, любая функция, построенная поверх этой машинерии, проверяет её сразу на самом опасном для себя сценарии.

Горизонт 0 — закрыть начатое

Ничто новое не начинается.

фоновая реконсиляция Link-политик от фактического состояния (B-3/B-3R) доведена до merge с зелёным Linux CI;
физический acceptance tests/acceptance/three-server-mesh.sh выполнен с SMM_ACCEPT_RESTORE=1 SMM_ACCEPT_REBOOT=1 на реальной тройке Hub + source Node + два destination Node;
подписанный release manifest: хэши всех артефактов, версии Control/Agent/helper/Desktop, минимальные совместимые версии; публичный ключ проверки вшит в bootstrap и Desktop; update-* отвергает несовместимые версии; см. контракт bootstrap;
роль Monitor реализована в bootstrap: системный пользователь, root-owned forced command, установка публичного ключа из Desktop, идемпотентная переустановка и удаление;
срок жизни и ротация клиентских сертификатов: автопродление Agent до истечения, документированная процедура ротации Control CA;
GitHub Actions запиннены по commit SHA, включён dependabot.

Критерий выхода. Чистый поддерживаемый сервер устанавливается из подписанного релиза одной командой, регистрируется одноразовым кодом, попадает под мониторинг без ручной правки authorized_keys, и после перезагрузки Hub и Node фактическое состояние Links совпадает с желаемым — проверено связностью, а не состоянием в API.

Горизонт 1 — продукт, пригодный для одного владельца

Разрешён после закрытия Горизонта 0.

provisioning-модули поверх готового каркаса, по одному: system.locale, system.packages, system.swap, user.create, user.disable, ssh.key.add, ssh.key.remove;
редактор managed firewall rules и двухфазная миграция SSH-порта — см. ТЗ Provisioning и Xray VPN, раздел 10;
alert engine: пороги, warning/critical, duration, cooldown, дедупликация, подтверждение, история инцидентов, тихие часы;
Telegram — только чтение: /status, /servers, /alerts, /links, /jobs. Никаких мутаций, приватных ключей, управления CA и произвольных команд;
Docker и systemd — сначала наблюдение: контейнеры, образы, healthcheck, счётчики рестартов, failed units, journald. Действия только после наблюдения и только по allowlist;
Backup Manager: local и S3, расписания, шифрование, retention, контрольные суммы, проверка восстановлением.

Критерий выхода. Каждый мутирующий модуль имеет versioned schema, immutable plan, подтверждение, factual verification, rollback и audit, и прошёл физическую приёмку на VM-матрице. Закрытие действующего SSH-порта невозможно до успешной проверки нового подключения.

Горизонт 2 — платформа

Web UI и аутентификация. До начала работ принять и записать решение по разделу «Публичный интерфейс» в модели безопасности: отдельный listener, отношение веб-сессий к mTLS-идентичностям, перечень операций, недоступных веб-сессии в принципе;
Secret Vault: envelope encryption, версии, ротация, маскированный показ, scoped delivery, TTL, отзыв, redaction. Является предусловием для Telegram-токена, ключей S3 и VPN-подписок;
централизованные логи. До начала работ принять решение о хранилище: Control SQLite для этого не предназначен;
security posture: оценка, объяснения, план исправления, безопасное применение, история, принятые риски;
multi-Hub, фаза 1: резервные копии БД и CA, шифрованное хранилище, проверка восстановления, ручное переключение. Фазы репликации и кворума не входят;
один VPN-модуль (Xray VLESS Reality) до физической приёмки включительно. Второй модуль не начинается, пока первый не принят.

Горизонт 3 — интеграция с KAgent

Разрешён после закрытия Горизонта 1. Спецификация: интеграция с KAgent.

Порядок внутри горизонта: discovery и identity → чтение Nodes, метрик и событий → планы и запросы → жизненный цикл Worker. Обратный порядок недопустим.

Что принято из внешнего документа видения

Раздел	Решение
Approval policies	Принято, см. approval-policies.md
Capability model, разделение `.read` / `.request`	Принято с ужесточением, см. integration-kagent.md
Emergency controls для интеграции	Принято
Поведение при недоступном KAgent	Принято
Provisioning catalog, desired/factual, drift	Принято как расширение существующей модели
Формат alert rule	Принят
Web UI и полный стек аутентификации	Отложено в Горизонт 2 с обязательным решением по модели угроз
Централизованные логи	Отложено, требует решения по хранилищу
Шесть VPN-модулей	Сокращено до одного до физической приёмки
Multi-Hub, репликация и кворум	Отложено за пределы горизонтов
Установка KAgent Worker	Горизонт 3, с инвариантом недоверенного исполнителя
Расширенный мониторинг: SMART, RAID, GPU, UPS	Отложено, каждый пункт требует привилегированного сборщика

8.8 KiB Raw Permalink Blame History Unescape Escape