Files
MikrotikManager/docs/mcp-db-offline-bootstrap.md
T

190 lines
37 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Подготовка ключей установки 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 <sha256> \
--transport /protected/operator/control-transport.json --transport-sha256 <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 -- <operation-id> <sha256-журнала>
```
В собранном 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 -- <sha256-файла-sealed>
```
В сборке используйте `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 -- <operation-id> <sha256-журнала>
npm --prefix backend run db:complete-restore -- <operation-id> <sha256-журнала>
```
В собранном backend первая команда доступна как `node dist/scripts/seal-database-restore-checkpoint.js`. Она сверяет исходный указатель, точный `consumed.claimId` в обеих подписанных записях и текущие данные под блокировками, затем атомарно публикует `sealed`. PostgreSQL остаётся в карантине. Вторая команда повторно проверяет данные и новую контрольную точку перед снятием карантина. При неподтверждённом `applied` или неопределённом исходе публикации сохраните текущие свидетельства для проверки. Совпадение старого журнала и PostgreSQL возможно после совместного отката, поэтому его недостаточно для восстановления предшествующего `sealed`.