# Подготовка ключей установки MCP `backend/scripts/database-writer-bootstrap-operator.mjs` — отдельная операторская команда подготовки ключей. Приложение её автоматически не запускает. Она не подключается к БД, не создаёт роли, не выдаёт права, не публикует политику и не переводит установку в READY. Состояние проверки: настоящая генерация Ed25519, подпись, проверка подписи и отказ при подмене проверены. В Windows проверен отказ до создания ключей. Успешная защищённая запись в POSIX ещё требует отдельной Linux-приёмки; до неё этот путь не считается принятым для эксплуатации. ## Явный вход оператора Команда принимает три обязательных параметра: ```text node backend/scripts/database-writer-bootstrap-operator.mjs init --output /protected/operator/new-installation --deployment /protected/operator/approved-request.json --deployment-sha256 <утверждённый SHA256 файла> ``` SHA256 должен поступать из независимо утверждённого запроса. Самостоятельное вычисление хеша найденной конфигурации не подтверждает её происхождение. Все сведения запроса — ожидаемые значения оператора; команда не подтверждает их соответствие действующей БД. Запрос содержит только следующие поля: | Поле | Содержание | | --- | --- | | `format` | `application-writer-bootstrap-request-v1` | | `installationId` | UUID установки | | `sourceHeadSha256` | Утверждённый SHA256 исходного head | | `source` | `systemIdentifier`, `databaseOid`, `databaseName`, `serverVersionNum`, `inRecovery` | | `roles` | Все пять разных ролей: `runtime`, `operator`, `capture`, `publisher`, `control`; каждая содержит `name` и десятичную строку `signedOid` | | `tls` | `serverName`, `caSha256`, `spkiSha256` | Идентификаторы PostgreSQL передаются десятичными строками. Поддерживается заявленная версия PostgreSQL 18 и `inRecovery=false`. Лишние поля, недостающие роли, совпадающие роли и отсутствующие transport/head pins приводят к отказу. ## Файлы и повторный запуск Родительский каталог должен уже существовать: канонический POSIX-путь, владелец — текущий uid, без доступа группы и остальных пользователей. Запрос — обычный файл того же владельца без доступа группы и остальных, размером не более 16 КиБ. Права и предки проверяются; Windows ACL сейчас не поддерживается. Новый каталог создаётся исключительно для этого запуска. Существующий каталог не принимается и не перезаписывается. Команда создаёт `signing-private.pem`, `operator-public.pem` и последним `bootstrap.json`. Файлы публикуются без замены существующих, с правами 0600 и синхронизацией записи. Незавершённый каталог сохраняется для проверки оператором; автоматического удаления или повторной попытки нет. Само наличие `bootstrap.json` не подтверждает успешный запуск: при поздней ошибке синхронизации или удаления временного имени файл уже может существовать. Незавершённый запуск требует проверки оператором; устойчивость к сбою питания этой проверкой не доказана. В stdout выводится только квитанция с публичным отпечатком, идентификатором установки и хешем запроса. Приватный ключ туда не попадает. Публичный отпечаток требуется независимо закрепить как доверенный: генерация ключа сама по себе не даёт ему полномочий. `databaseObserved`, `rolesAuthenticated`, `sourceAuthenticated`, `publicationAuthorized`, `generationAuthenticated` и `readyAuthorized` остаются `false`; утверждённое определение отсутствует. Следующий этап — подключённая проверка реальной БД, пяти ролей и исходного head с закреплёнными CA/SPKI. Он этой командой не реализуется. Целевая проверка без БД и сети: ```text node --test backend/scripts/database-writer-bootstrap-operator.test.mjs ``` ## Проверка источника при открытии соединений приложения Для включения задайте все три переменные. Приложение читает утверждённый публичный запрос, который оператор использовал для `init`, и проверяет его по независимо переданному хешу. - `DATABASE_RUNTIME_REQUEST_FILE` — абсолютный путь к `approved-request.json` формата `application-writer-bootstrap-request-v1`. - `DATABASE_RUNTIME_REQUEST_SHA256` — утверждённый SHA-256 точных байтов запроса. - `DATABASE_RUNTIME_CA_FILE` — абсолютный путь к PEM-файлу CA с хешем из `tls.caSha256` запроса. Параметры `DATABASE_URL` должны содержать прямой PostgreSQL endpoint, логин runtime, пароль и имя БД. Имя сервера, логин и база сверяются с запросом. Параметры query string не принимаются. При открытии соединения пул проверяет цепочку TLS, имя сервера и ключ сертификата. Перед каждой выдачей закреплённого соединения он сверяет `SESSION_USER`, `CURRENT_USER`, OID роли, имя и OID БД, системный идентификатор, точную версию PostgreSQL и работу на primary. Отказ закрывает соединение. TLS-ключ выделяется этому endpoint. Клон с теми же SQL-идентификаторами и тем же ключом пройдёт такую проверку. Runtime получает прямые прикладные права `SELECT` и DML. Проверка PostgreSQL отклоняет членство в ролях в обе стороны, владение текущей БД и её объектами, `CREATE`/`TEMP` и доступ к отключению триггеров. Один SQL-запрос на выдачу проверяет в том числе изменения прав, сделанные, пока соединение простаивало. Уже выданное соединение проверяется при следующей выдаче из пула. Если для runtime закрыта функция `pg_catalog.pg_control_system()`, оператор заранее выдаёт этой роли право `EXECUTE` только на указанную функцию и учитывает его при утверждении каталога. В приложение передаются публичный запрос и CA. Ключ подписи и операторские настройки остаются у оператора. Изменение версии PostgreSQL или ключа TLS требует нового утверждённого запроса и перезапуска пулов. Эта проверка охватывает основные пулы приложения, worker и пулы допуска REST/MCP. Отдельные подключения резервного копирования, восстановления и операторских команд используют свои проверки. Подтверждение поколения БД и допуск `READY` остаются отдельными этапами. ### Сверка с операторским реестром активации После подтверждённого `source-activate` передайте приложению `DATABASE_RUNTIME_ACTIVATION_SHA256` из квитанции и `DATABASE_RUNTIME_ACTIVATION_DIRECTORY` с каталогом реестра. Монтируйте целый каталог только для чтения, чтобы приложение видело замену файла и переходный `.pending`. У приложения должно быть право чтения записи. Операторский ключ остаётся за пределами этого монтирования. Хеш передаётся независимо через параметры развёртывания. Каталог реестра и параметры развёртывания хранятся вне контура восстановления БД. При выдаче соединения из пула и при допуске через общие SQL-блокировки приложение проверяет статус `active`, хеш и совпадение установки, текущего head и TLS-ключа. Появление `.pending`, отзыв, смена поколения и пропажа записи закрывают новые допуски с прежним пином. Уже допущенная работа может завершиться. При смене поколения оператор останавливает и дожидается завершения работы старых потребителей перед переключением, затем развёртывает новый набор пинов. Совместный откат каталога и параметров развёртывания может восстановить прежнюю принятую пару. ## Подготовка схемы отдельной ролью До запуска приложения с проверкой источника оператор выполняет из отдельного процесса `npm --prefix backend run db:prepare`. В собранном backend используется `node dist/scripts/prepare-database.js`. В этом процессе `DATABASE_URL` явно указывает на подготовленную оператором целевую БД и роль с правом владения схемой. Переменные `DATABASE_RUNTIME_*` задаются приложению и команде сверки схемы. Для подготовки схемы сохраняются те же `MCP_STATE_DIR` и настройки карантина. Операторская команда применяет штатные миграции, завершает требуемый импорт SQLite и обслуживает партиции под общей блокировкой обслуживания. При старте с ролью приложения проверяются список применённых миграций и наличие требуемых партиций. Роли приложения требуется `SELECT` на `public.schema_migrations` и чтение таблиц, из которых берутся настройки хранения и отметка импорта. Если нужен импорт SQLite, старт останавливается до его завершения оператором. Приложение продолжает писать прикладные данные с правами runtime. Оператор повторяет подготовку партиций до исчерпания запаса по датам, который создаёт штатная процедура. Обслуживание старых партиций выполняет та же операторская команда. Для планового обслуживания используйте `npm --prefix backend run db:prepare -- --partitions-only` или `node dist/scripts/prepare-database.js --partitions-only`. Команда под общей блокировкой сверяет версию схемы, удаляет истёкшие партиции по действующим настройкам хранения и создаёт требуемые партиции. Она применяет те же проверки карантина и журнала восстановления. Применение миграций и импорт SQLite доступны при запуске `db:prepare` без параметра. ### Установка таблиц реестра профиля записи После подготовки схемы и SQL-защиты оператор может однократно создать пустой реестр профиля в отдельном процессе на POSIX: ```sh node backend/dist-operator/database-writer-profile-operator.mjs registry-enroll \ --approval /protected/operator/registry-approval.json --approval-sha256 \ --transport /protected/operator/control-transport.json --transport-sha256 \ --ca /protected/operator/postgres-ca.pem ``` В `registry-approval.json` укажите `format` со значением `application-writer-registry-enrollment-v1`, `manifestSha256` текущей сборки и `deploymentRequest` формата `application-writer-bootstrap-request-v1` из раздела выше. Файл подключения содержит `host`, `port`, `user`, `password`, `database`. Пользователь подключения должен совпадать с закреплённой ролью `control` и владеть схемой `mmapp_control`. Пины для файлов утверждаются отдельно от передаваемых файлов. Каталог и файлы принадлежат пользователю оператора и закрыты от других пользователей. До установки создайте пять ролей из запроса и подготовьте штатную схему с проверенными отметками миграций. Роли `control`, `operator` и `publisher` нужны существующие права чтения метаданных источника, а роли `control` нужен доступ к `public.schema_migrations`. Требуемые права схем и функций и проверенный SQL-профиль устанавливаются владельцами соответствующих объектов. Команда сверяет TLS, идентичность БД и ролей, берёт эксклюзивную блокировку профиля и фиксирует пустые таблицы с точными правами только после проверки их структуры. Существование любой из двух таблиц приводит к отказу. Если ответ о `COMMIT` потерян, сначала вручную сверьте обе таблицы и их права. После подтверждения установки публикация профиля выполняется отдельной операторской командой. Для этой сверки запустите `registry-inspect` с теми же параметрами. Результат `absent` означает отсутствие обеих таблиц. `installed` содержит SHA-256 подтверждённой структуры реестра и его прав. Если присутствует одна таблица, структура изменилась или права отличаются, команда отказывает. Проверка выполняется в транзакции только для чтения и завершается `ROLLBACK`. Содержимое реестра и разрешение `READY` проверяются отдельно. ### Установка защиты таблицы отметок миграций Когда остальные объекты утверждённого профиля 57 подготовлены, используйте операторскую команду `marker-fence-enroll` с параметрами `--approval`, `--approval-sha256`, `--transport`, `--transport-sha256` и `--ca` по образцу `registry-enroll`. Подключение выполняется закреплённой ролью `operator`, владельцем `public.schema_migrations`. В отдельном утверждении укажите `format` со значением `application-writer-marker-fence-enrollment-v1`, `deploymentRequest`, `manifestSha256`, `definitionSha256` определения профиля 57 и `catalogSha256` утверждённого итогового каталога для публикации профиля. Команда допускает таблицу без пользовательских триггеров. В рамках одной транзакции она проверяет отметки миграций, ожидаемые права и существующую защиту DDL, устанавливает три утверждённых триггера с режимом `ALWAYS` и сверяет итоговый каталог с пином перед `COMMIT`. Частично установленные триггеры требуют ручной сверки. При потере подтверждения `COMMIT` сначала проверьте каталог операторским подключением. Публикация профиля выполняется отдельно. ### Контроль фактической схемы при запуске После подготовки и проверки БД оператор запускает `npm --prefix backend run db:inspect-schema` с тем же TLS-профилем источника и SQL-ролью, которые использует приложение. В собранном backend команда запускается как `node dist/scripts/inspect-database-schema.js`. Она читает каталог PostgreSQL в одном снимке под общими блокировками обслуживания и записей в партиции и выводит `schemaSha256`. После сверки утверждённое значение передаётся приложению через `DATABASE_RUNTIME_SCHEMA_SHA256`. При несовпадении старт останавливается до чтения маркеров миграции. Хеш охватывает логическую структуру `public` и `mmapp_control`, если она есть, включая определения триггеров, вызываемые ими функции, права, владельцев, версию PostgreSQL и конкретные партиции. Для event trigger, вызывающего функцию в `mmapp_control`, снимок включает событие, режим, теги, владельца и ссылку на функцию. При переходе с предыдущей проверки на БД с `mmapp_control` оператор пересчитывает и утверждает хеш. Такое же подтверждение нужно после ротации партиций, изменения схемы или прав и обновления PostgreSQL. Данные в таблицах `mmapp_control` в хеш схемы не входят. История данных и полномочия `READY` подтверждаются отдельно. ### Подписанный профиль записи с карантином Для подписанного профиля с карантином приложение принимает `DATABASE_RUNTIME_WRITER_APPROVAL_FILE` и отдельно утверждённый `DATABASE_RUNTIME_WRITER_APPROVAL_SHA256`. Файл JSON содержит `format: "database-runtime-writer-approval-v1"`, `publicKeyPem`, `publicKeySpkiSha256`, `minimumEpoch` и `minimumHeadSha256` из подтверждённой квитанции публикации. `minimumEpoch` задаётся строкой. Храните утверждение вне контура восстановления и монтируйте его только для чтения. Режим требует активацию источника, закреплённый хеш схемы, карантин и внешний файл контрольной точки. При выдаче SQL-соединения приложение сверяет подписи, срок действия, источник и OID всех пяти ролей. В пределах работающего процесса оно запоминает последнюю принятую эпоху и отклоняет откат или другую голову в той же эпохе. После перезапуска начальная граница берётся из файла утверждения. Чтобы закрепить более позднюю эпоху на случай отката хранилища, обновите внешний файл и его независимо сохранённый хеш после подтверждения публикации. Для первой `sealed` контрольной точки этого профиля запишите `writerHead` с полями `epoch` и `sha256` из подтверждённой публикации. Стадия `pending` сохраняет голову, которую приложение увидело перед восстановлением. После подтверждённого `applied` издатель сверяет восстановленный каталог и публикует следующую эпоху. `db:seal-restore-checkpoint` проверяет, что подпись новой эпохи выпущена после `applied`, и записывает её в `sealed`. Снятие карантина и следующий старт сверяют сохранённую эпоху с действующей подписанной политикой. ### Сверка данных после восстановления Оператор получает ожидаемый снимок из проверенного воспроизведения архива в изолированной БД после применения требуемых миграций. Команда `npm --prefix backend run db:inspect-schema -- --data` выводит `dataSha256` для настроенного и подтверждённого TLS-источника. Роли для этой проверки требуется читать таблицы и последовательности приложения. Ожидаемый снимок привязан к той же логической схеме, версии PostgreSQL, владельцам и правам, что и целевая БД. Укажите SHA-256 точных байтов архива в `DATABASE_RESTORE_ARCHIVE_SHA256` и отдельно утверждённый хеш снимка в `DATABASE_RESTORE_DATA_SHA256`. Для режима также нужны `DATABASE_RESTORE_QUARANTINE=true` и отдельная роль восстановления через `DATABASE_RESTORE_URL_FILE`. Несовпадение архива останавливает операцию до замены БД. После восстановления и миграций операторская роль сверяет под общей блокировкой строки и состояния последовательностей `public`. Определения `mmapp_control` входят в хеш схемы. Строки и последовательности этой схемы сохраняются отдельно от архива. При несовпадении данных операция записывается как `unconfirmed` и карантин остаётся. Один снимок ограничен миллионом строк, 128 МиБ представления данных и 60 секундами. Выход за пределы оставляет проверку неподтверждённой. Для старого архива с миграциями, создающими недетерминированные данные, требуется отдельное доказательство преобразования. В этом режиме начало и итог восстановления записываются во внешний журнал с одним ID операции, той же парой хешей, отпечатком цели и отпечатком активации, если она настроена. Для каждой подписанной записи при чтении проверяется HMAC с отдельным производным ключом от `encryption-key` состояния MCP. Операция сохраняет длину и SHA-256 подтверждённого журнала в строке карантина `mmapp_control` вместе с постановкой и снятием карантина. При запуске, резервном копировании и следующем восстановлении PostgreSQL и файл журнала должны совпасть. Сохраняйте каталог состояния и ключ вместе. Если прервалась запись итога, сохраните файл и точный ID карантина для ручной сверки. Для новой установки используйте [DDL контрольной таблицы](../backend/src/db/database-restore-quarantine.ts). На существующей установке роль владельца контрольной схемы выполняет при остановленных потребителях: ```sql ALTER TABLE mmapp_control.database_restore_quarantine ADD COLUMN journal_prefix_bytes integer, ADD COLUMN journal_prefix_sha256 text, ADD CONSTRAINT database_restore_quarantine_journal_head CHECK ( (journal_prefix_bytes IS NULL) = (journal_prefix_sha256 IS NULL) AND journal_prefix_bytes BETWEEN 1 AND 8388608 AND journal_prefix_sha256 ~ '^[a-f0-9]{64}$' ); ``` Роли приложения требуется `SELECT` на контрольную таблицу. Роли восстановления предоставьте `UPDATE` только на `operation_id`, `journal_prefix_bytes` и `journal_prefix_sha256` в дополнение к необходимому `SELECT`. После изменения определения и прав заново получите утверждённый хеш схемы и снимок данных. Для старого журнала только с неподписанными записями допустима пустая контрольная запись. Если есть подписанная история без контрольной записи, запуск требует операторской сверки. Нужна отдельная процедура для совместного отката PostgreSQL и каталога состояния. ### Снятие карантина после прерванного подтверждения Если PostgreSQL ещё хранит ID операции и контрольную запись `intent`, а журнал заканчивается подписанным `applied` той же операции, остановите backend и сохраните файл журнала. Сверьте `operationId` последней записи и SHA-256 точных байтов всего `database-maintenance.jsonl`. С прежним подключением приложения, файлом подключения владельца, каталогом состояния, пинами архива, данных и активации выполните: ```sh npm --prefix backend run db:complete-restore -- ``` В собранном backend используйте `node dist/scripts/complete-database-restore.js` с теми же аргументами. Команда повторно сверяет данные PostgreSQL, подписанные записи и сохранённый карантин под блокировками, синхронизирует файл журнала с диском и фиксирует завершение одной транзакцией. Архив повторно не применяется. История журнала и внешняя квитанция MCP сохраняются как есть. Если итог команды неизвестен, перед следующим запуском проверьте строку карантина и контрольную запись журнала. Для `unconfirmed` или пропавшей записи `applied` требуется отдельное расследование. ### Независимая контрольная точка журнала `DATABASE_RESTORE_CHECKPOINT_FILE` указывает на канонический абсолютный путь файла, которым управляет оператор. Смонтируйте его **каталог** только для чтения и храните на стороне хоста отдельно от `PGDATA`, архива и `MCP_STATE_DIR`. Независимость от их совместного отката зависит от этого размещения. Путь внутри `MCP_STATE_DIR` отклоняется. При отсутствии параметра приложение использует прежний режим карантина. Если результат предыдущего шага неизвестен, оператор может сверить файл, журнал и строку карантина под блокировкой обслуживания: ```sh npm --prefix backend run db:inspect-restore-checkpoint ``` Команда возвращает статус, ID операции и хеши без записей в PostgreSQL или во внешний файл. `matches-sealed` и `matches-pending` означают совпадение указателей при открытом карантине. `applied-consumed` и `applied-sealed` указывают на точный подписанный `applied` при сохранённом карантине. `inspection-required` сохраняет расхождения для проверки. Текущее содержимое PostgreSQL повторно проверяют команды публикации и снятия карантина. Файл формата `database-restore-checkpoint-v1` содержит `runtimeTargetSha256`, `activationSha256` (или `null`) и `head` (`{ "bytes": 123, "sha256": "…" }` либо `null` до первой подписанной записи). `runtimeTargetSha256` формируется тем же способом, что в привязке подписанного журнала. При `status: "sealed"` приложение требует совпадения контрольной точки, журнала и PostgreSQL. Перед восстановлением проверьте SHA-256 точных байтов внешнего файла `sealed`. На операторском хосте с утверждёнными переменными `DATABASE_RESTORE_ARCHIVE_SHA256` и `DATABASE_RESTORE_DATA_SHA256` выполните: ```sh npm --prefix backend run db:stage-restore-checkpoint -- ``` В сборке используйте `node dist/scripts/stage-database-restore-checkpoint.js`. Команда сверяет `sealed` с PostgreSQL и журналом, затем публикует `pending` с прежним `head`, новым `operationId` и утверждённой парой хешей. Выполните штатное восстановление через уже запущенный backend, поскольку `pending` блокирует запуск нового процесса. На стороне хоста запустите операторский процесс с правом записи в независимый каталог. В собранном backend эквивалент команды — `node dist/scripts/serve-restore-checkpoint-claims.js`: ```sh npm --prefix backend run db:serve-restore-claims -- <путь-к-файлу> <локальный-сокет> ``` Укажите тот же локальный сокет в `DATABASE_RESTORE_CHECKPOINT_CLAIM_SOCKET` работающего backend. На POSIX сокет имеет права `0660`. Ограничьте доступ к каталогу сокета хостом и backend. При замене точки операторский процесс сохраняет UID, GID и обычные POSIX-права исходного файла. Дайте backend доступ на чтение и монтируйте сам каталог точки только для чтения. Перед первой записью журнала backend запрашивает одноразовый переход `pending` → `consumed`. Операторский процесс сравнивает весь прежний допуск, синхронизирует замену файла и возвращает подтверждение. `pending` и `consumed` блокируют обычный старт и резервное копирование. Новый запрос восстановления при `consumed` отклоняется, даже если PostgreSQL и журнал вернулись к прежней паре. Уже подтверждённый вызов сохраняет карантин после подписанного `applied`. При потере ответа, наличии `.lock` или `.pending` рядом с файлом либо неопределённом завершении сохраните контрольную точку и журнал для проверки. Для записи с подтверждённой синхронизацией каталога нужен POSIX. Windows-тесты используют именованный канал и проверяют логику перехода. После `applied` остановите backend. Сверьте `operationId` и SHA-256 всего `database-maintenance.jsonl`. Запустите команду на хосте с доступом к PostgreSQL, прежним пинам восстановления и активации, журналу и правом записи во внешний каталог: ```sh npm --prefix backend run db:seal-restore-checkpoint -- npm --prefix backend run db:complete-restore -- ``` В собранном backend первая команда доступна как `node dist/scripts/seal-database-restore-checkpoint.js`. Она сверяет исходный указатель, точный `consumed.claimId` в обеих подписанных записях и текущие данные под блокировками, затем атомарно публикует `sealed`. PostgreSQL остаётся в карантине. Вторая команда повторно проверяет данные и новую контрольную точку перед снятием карантина. При неподтверждённом `applied` или неопределённом исходе публикации сохраните текущие свидетельства для проверки. Совпадение старого журнала и PostgreSQL возможно после совместного отката, поэтому его недостаточно для восстановления предшествующего `sealed`.