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

5.2 KiB

Raw Blame History

Политики подтверждения

Статус: спецификация. Реализовано частично — сегодня подтверждение бинарное: действие либо требует ConfirmationRequired, либо нет.

Задача

Разные операции несут разный риск, но сейчас различаются только наличием подтверждения. Смена таймзоны и ротация Control CA проходят через одну и ту же процедуру. Нужен явный, версионируемый набор режимов.

Режимы

Режим	Что требуется
`none`	Ничего. Допустим только для операций без побочных эффектов на хосте
`operator`	Подтверждение действующим Operator-сертификатом с `audit reason`
`operator_reauth`	То же плюс повторное доказательство владения identity непосредственно перед подтверждением
`owner`	Подтверждение identity с ролью владельца установки, отличной от обычного Operator
`two_person`	Два разных Operator; второй не может быть инициатором. Оба подтверждения в аудите
`time_window`	Подтверждение действительно ограниченное время; по истечении задание возвращается в `AwaitingConfirmation`
`maintenance_window`	Выполнение разрешено только внутри объявленного окна обслуживания
`emergency_only`	Доступно только при активном инциденте, с обязательным пост-фактум разбором в аудите
`read_only_automation`	Automation-идентичности разрешено чтение результата, но не инициирование

Формат

service.restart:
  approval: none
system.packages:
  approval: operator
firewall.rule.add:
  approval: operator_reauth
ssh.migrate:
  approval: operator_reauth
user.delete:
  approval: owner
ca.rotate:
  approval: two_person
node.delete:
  approval: two_person

Политика версионируется вместе с каталогом действий, хранится на Control и не может быть ослаблена запросом клиента. Отсутствие действия в политике означает owner, а не none.

Связь с существующими механизмами

Режимы не заменяют то, что уже работает, а надстраиваются над ним:

ConfirmationRequired и ConfirmedAt в ProvisioningJob остаются местом фиксации факта подтверждения;
time_window естественно ложится на существующий TTL задания;
execution grant, привязанный к node_id, job_id и SHA-256 подтверждённого plan, выдаётся только после того, как режим удовлетворён;
audit reason обязателен во всех режимах, кроме none;
idempotency key не позволяет повторному запросу обойти подтверждение.

Требования к реализации

решение о достаточности подтверждения принимает Control, а не клиент;
при two_person инициатор и подтверждающий сравниваются по identity, а не по отображаемому имени;
при operator_reauth повторное доказательство привязывается к конкретному job_id; повторное использование для другого задания отклоняется;
понижение режима для конкретного задания невозможно; изменение политики действует только на задания, созданные после изменения, и само является аудируемым событием;
недостижимость условий режима не приводит к выполнению: задание остаётся в AwaitingConfirmation до истечения TTL, затем отменяется.

Что нельзя ослаблять

Для операций, способных лишить доступа к серверу или к управлению, режим не может быть ниже operator_reauth:

закрытие действующего SSH-порта;
изменение правил firewall;
удаление или блокировка последнего административного пользователя;
включение системного VPN и kill switch;
удаление Node;
ротация Control CA — не ниже two_person.

5.2 KiB Raw Blame History Unescape Escape