Files
MikrotikManager/docs/router-configuration-guard.md
T

25 KiB
Raw Blame History

Router configuration guard: протокол и текущая граница интеграции

Состояние на 2026-10-28: production-компонент реализован и прошёл owned PostgreSQL-приёмку. Он не активирован: нет startup assembly, default-конфигурации, подключения всех writers или действующего production mapping issuer. Наличие компонента, подписи и advisory lock само по себе не подтверждает полноту writer coverage и не завершает S3-07.

Дополнение: ordinary MCP operation origin принят на настоящем одноразовом PostgreSQL. Runtime публикует приватный контекст всей операции до удерживаемых operation/application/server locks. Admission выдаётся собственным INSERT в создающей транзакции, фиксирует исходные principal/grant/sealed payload/evidence, directory/key/generation и wall/monotonic lifetime; из существующей pending-строки его получить нельзя. Потеря ACK закрывает только собственный nonce, чужой победитель CAS сохраняется. Приватный marker не выдаётся модели и прямому web apply. Новых production-пулов, процессов и миграций этот компонент не добавляет.

Приняты 4 SQL-группы, 12 unit нового root, 13 совместимости service-origin и 14 lock-unit; backend build и общая auth/MCP-регрессия прошли. Это provenance для следующего шага интеграции: writer guard ещё нужно вызвать между публикацией root и первыми legacy locks, затем покрыть остальные REST/scheduler/worker entrypoints. Existing service-origin остаётся доступен внутри service-шагов, но не заменяет whole-operation origin до блокировок. Отдельные restore/recovery paths и global activation этой приёмкой не закрыты. Требование общей установки ≤2 GB и бюджет всех control pools сохраняются.

Реализация и API

Исходники находятся в backend/src/services/:

Файл Назначение
router-configuration-guard.ts Явный createConfiguredRouterGuard(config, dependencies), отдельный pool, проверка подписанного source, leases и приватные receipts
router-configuration-guard-schema.ts Внешняя owner-install DDL, фиксированные role/catalog проверки, требования к интеграции и application pool hook
router-configuration-guard.sql-helper.ts 18 owned сценариев и чистые отрицательные DSN-проверки
router-configuration-guard.sql-fixture.ts Реальные одноразовые БД/роли/ключи, localhost HTTP и TCP proxy потери COMMIT ACK
router-configuration-guard.sql.test.ts Explicit-owned entry, без fallback на application DATABASE_URL
router-configuration-guard-compatibility.sql-helper.ts Opt-in сравнение настоящих v1/v2 control sources до/после установки отдельного guard namespace

Factory принимает databaseUrl, applicationDatabaseUrl, абсолютные отдельные sourceFile, trustKeyFile, eventKeyFile и SPKI SHA-256 trustKeySha256. Environment getter и автоматического создания источника нет. Обе DSN проходят существующий строгий bandwidthControlEndpointSha256: query authority overrides запрещены, сравниваются декодированные имена БД и ролей, а actual SQL дополнительно проверяет OID/role identity. %61pp не создаёт независимость от app.

Захваченные server-owned dependencies: applicationPool, assertNoLowerLockContext, authorize, readOriginalWriterAuthority, фиксированный nativeTransport. Последние два нельзя получать из request JSON или публичного callback-параметра. authorize и оригинальная authority перепроверяются; caller scope может только сократить срок.

Метод Фактическое поведение
acquireMapping(scope) Берёт shared session lock, проверяет authenticated idle head; возвращает verify, run, close, signal
runCompound(binding, scope, work) Объединяет вложенные writers в один exclusive cohort; произвольный результат work не является ACK
runNative(binding, scope) Валидный managed server ID, захваченные endpoint/command/actor MAC, настоящий ClientRequest, socket-ready authority check и приватный physical response receipt
runApplication(binding, scope, work) Собственная реальная application PG transaction; callback получает ограниченный query facade, ACK только от фактического driver COMMIT
close() Закрывает активные leases/свой pool, не очищает durable pending

Mapping lifetime ограничен исходными wall/monotonic/cancellation границами и максимумом 5 секунд. Для writer только initial authority lookup ограничен 5 секундами; дальнейший срок — минимум исходных actor expiry, command deadline и monotonic end, дополнительно сокращённый caller scope. Длительный import нельзя обрезать произвольным новым 5-секундным writer timeout или продлевать повторным чтением grant.

Внешняя установка и trust boundary

Owner отдельно устанавливает mmapp_router_guard в явно выбранной control DB, физически отличной от application DB. Отдельные NOLOGIN owner и NOINHERIT runtime не наследуют core/application роли. Runtime получает только USAGE namespace; SELECT четырёх таблиц; INSERT attempts/events; UPDATE head; EXECUTE protect_rows. Нет UPDATE source identity, DELETE/TRUNCATE history, CREATE, grant options или доступа к mmapp_control. PUBLIC grants отсутствуют. Owner, namespace, роли, полная структура, trigger bodies и ALWAYS topology проверяются вместе с подписанным catalog pin.

Отдельный Ed25519 envelope имеет purpose mmapp-router-guard-source-v1. Record привязывает installation/generation, endpoint, DB name/OID/owner, runtime/schema-owner, schema source/catalog digests, SHA-256 отдельного 32-byte event key и reviewed cutover evidence. Необязательный signed application OID дополнительно сверяется с реальным application client. Signed record и исходный MAC head устанавливает owner; пустые таблицы не запускают bootstrap. Stub mmapp_control не используется.

Это отдельный namespace/pool/key/role. Он не меняет 39 обычных application migrations, v1/v2 control/node DDL, их подписи или generation. Он не использует mcp_audit: backend/src/modules/mcp/workers.ts удаляет старый audit по retention. Application archive/restore должен дополнительно исключать --exclude-schema=mmapp_router_guard; физическое разделение БД остаётся основной границей. Автоматическое operating enrollment, owner-install CLI/UI и проверенный cutover workflow ещё не реализованы.

Операторская подпись подтверждает явно доверенный installation/cutover statement. Она не останавливает старые процессы, чужие RouterOS sessions, автономный DHCP/SLAAC/routing, внешний NAT или DNS. Rollback всего control provider вместе с подписанными файлами/ключами остаётся внешним trust assumption; этот протокол не обнаруживает согласованный rollback всех своих якорей.

Durable journal и настоящие receipts

Один session advisory key 8723129: mapping держит S, configuration writer держит X. Guard использует собственный pool, не заимствует core pool connection внутри уже удерживаемого native SQL gate. На том же физическом guard PID проверяются роль, source, catalog, MAC head и факт lock ownership.

Протокол writer:

  1. Проверить исходную authority и authenticated idle head.
  2. Под X записать immutable attempt, intent event и следующий head; получить настоящий synchronous COMMIT ACK до native/application I/O.
  3. Выполнить реальные действия, сохраняя X и исходные bounds. Дочерние writers заимствуют тот же lease/PID через private ALS, с refcount; параллельные siblings/retired scope отвергаются.
  4. Собрать модульные physical receipts для каждого фактически учтённого действия. Число receipts должно точно совпасть с activity count. Zero activity даёт no-send, не acknowledged.
  5. Записать terminal event/head отдельным реальным COMMIT. Ошибка не разрешает автоматический replay.

head — O(1) authenticated singleton: installation/generation, sequence, state, current attempt, last event и last-event MAC. MAC последнего event проверяется отдельно вместе с sequence/attempt binding. Отсутствие строки в WHERE state='pending' не доказывает idle: valid-shape поддельные ACK event + idle head от runtime DB role с неправильным MAC отвергаются. ALWAYS triggers запрещают rewind и удаление истории; MAC не позволяет DB runtime самостоятельно выдавать terminal evidence.

В application facade наблюдается настоящий connection.readyForQuery packet I/T/E. Каждый callback query должен дать ровно один обычный driver result и остаться в T; несколько statements, COMMIT/ROLLBACK/SAVEPOINT и ошибки помечают cohort failed, даже если callback поймал исключение. Собственный финал требует фактических COMMIT и I. Unawaited/concurrent query не становится receipt. Checked-out application/guard clients имеют ранние error/end handlers; потеря соединения закрывает lease и физический client, обработчик поздних ошибок не снимается преждевременно.

Native receipt требует настоящий связанный ClientRequest, точные method/path/auth/host, finish и полный bounded успешный response плюс успешный фиксированный trusted parser. POST в этом компоненте консервативно всегда unknown; 2xx для async command не доказывает completion. Для PUT/PATCH/DELETE malformed JSON и error/message/detail response также не дают receipt. До активации список синхронных операций и их фиксированные parsers надо явно связать с реальным transport; generic success JSON не заменяет эту работу.

Неопределённое выполнение оставляет durable pending; схема также поддерживает sticky unknown. Оба запрещают mapping. Нет TTL, GC, startup repair, DELETE, auto-clear или adoption новой generation. Если потерян terminal COMMIT ACK, сервер мог уже сохранить подлинный idle после доказанного завершения действий: caller всё равно получает unknown/no-replay, но последующий authenticated reader может принять этот реально committed terminal. Потеря intent/application COMMIT ACK оставляет pending; application transaction могла реально сохраниться.

Ручное reconciliation ещё не реализовано. Нельзя очищать pending SQL UPDATE, переустановкой пустого head, заменой подписи, restore application DB или возрастом записи. Нужны отдельные доверенные процедуры сверки реального результата, физического завершения старого executor и owner-authorized разрешения неопределённости с сохраняемой историей.

Конкретная карта следующего подключения

Текущая карта основана на исходниках, а не на предположении, что существующий audit уже является guard receipt.

Действующая точка Что реально есть сейчас Необходимое подключение
mikrotik.ts: MikrotikClient.mutation, post/put/patch/delete Managed-ID check, затем server lock и executeGuardedConfigurationWrite; низкоуровневые rosPost/rosPut/rosPatch/rosDelete создают реальные HTTP requests Войти в guard X до server lock; внутри captured native transport привязать фактический request до flush и проверить source/authority после socket assignment. Сохранить исходные body/path/auth/timeouts и parsers
config-mutation-policy.ts: executeGuardedApplicationWrite Application lock берётся до dependency resolution, protection checks, audit и work() Guard cohort должен оборачивать весь этот вход снаружи withApplicationMutationLock; callback success/audit acknowledged не выдаёт receipt
config-mutation-policy.ts: executeGuardedConfigurationWrite Reauthorization, protections, audit intent/ack; уже вызывается под server lock Только заимствовать существующий guard cohort; приобретать новый X здесь поздно
db/index.ts: createPool, экспорт pool, drizzle(pool), dbQuery Один основной Pool на thread, другие callers используют Drizzle, pool.query и checked-out clients Private hook ставится сразу при создании каждого actual application pool, до Drizzle/export. Перехват actual connect Promise/callback и один raw client.query; Pool.query не считать повторно. Фиксировать реальные dispatch/result/ReadyForQuery/COMMIT, outstanding queries/clients, errors и abort. Public markAck(bool) отсутствует
modules/mcp/runtime.ts: executeOperation, executeOperationWithLease, applyWithLocks, recovery Operation client уже берётся и передаётся через withOperationConfigurationLockClient; service stages удерживают application + server locks до serviceExecute Захватить/проверить original actor/step lifetime и guard на уровне operation/service admission до application/server locks; сохранить runtime authorization и private service provenance. Вложенные service/native writers используют тот же guard PID
bandwidth-peer-execution-host.ts, bandwidth-native-dispatch-composite.ts Поддержана композиция mapping-first S и registry/owner gate через настоящий private-permit handoff до ClientRequest.finish Fixed production mapping assembly должна поставить действительный held configuration fence первым gate. Эта композиция не выдаёт mapping grant и не доказывает all-writer participation

Обязательный порядок: guard GLOBAL → application → отсортированные server locks. Existing operation-serialization lock и его runner-owned SQL facade нельзя молча считать configuration guard. withOperationConfigurationLockClient экспортирует только allowlisted app/server advisory statements, а не право заимствовать независимый guard pool. Порядок operation lock относительно global guard надо закрепить единообразно при wiring и тестировать на конкурирующих operations.

Критический существующий ambient-lock риск: runtime.ts вызывает withApplicationMutationLock(applyWithLocks) для service evidence, затем внутри withConfigMutationLock исполняет service. Дополнительно application/server locks берутся снаружи application-write helper в ipsec-native-write-actions.ts, ospf-legacy-execution.ts, routing-community-scoped-service.ts, routing-community-scoped-recovery.ts, wireguard-interface-create/update/delete.ts, wireguard-peer-create/update/delete.ts, wireguard-revision-restore.ts, а OSPF cost helper в mikrotik.ts имеет свой compound wrapper. Вставка X только в нижний mutation/application helper здесь инвертирует порядок. Нужен верхний cohort до этих locks; дочерний вход обязан заимствовать тот же физический lease, без S→X upgrade и без второго checkout.

Отдельный concrete diagnostic case: managed-ID strict bandwidth post сейчас проходит mutation → withConfigMutationLock(server) → executeGuardedConfigurationWrite → private dispatch/composite.acquire(mapping S). Будущий mapping S здесь может оказаться ниже уже взятого server lock; blanket X для всех mutation добавит конфликт с собственной S. Fixed private-permit diagnostic path требует верхнего захвата mapping S до ambient configuration locks и последующего заимствования того же private lease до finish. Existing managed audit/server lock и проверку действительного private permit нельзя удалять; request JSON не выбирает exemption. Имеющийся id-less strict private-permit diagnostic exception не разрешает id-less config write или legacy bandwidth POST.

Практические native/metadata группы, которые необходимо перевести и проверить вместе:

  • RouterOS/UI/MCP native writes: firewall-rule-write.ts:writeFirewallRule, routes firewall.ts, containers.ts, filters.ts; WireGuard interface/peer create/update/delete, executeWireguardImport, revision restore; IPsec server init/delete, user create/update/delete, peer update/delete, certificate delete/export/import, revision restore; executeFlowOverlay; RouterOS file/import/execute/certificate/ip-service helpers в mikrotik.ts. POST import/execute нельзя автоматически считать синхронным ACK.
  • Source identity/alias metadata: modules/servers/service/servers-service.ts:createServer/updateServer/deleteServer → repository/Drizzle actual writes; поля endpoint, enabled, credentials и epoch должны попасть в общий cohort. speed-probe-catalog.ts:replaceSpeedProbeCatalog, ping probe replacement в uptime-collector.ts, filters SQL + native stages также требуют общего lifetime.
  • Остальные существующие executeGuardedApplicationWrite callers: users bindings, events, ACME/certificates, alerts/outbox/Telegram, backup settings/artifacts, EvoBGP/GeoIP, internet path, logs settings, REST-ping/traffic/uptime settings, NetFlow host files/keys/settings/ingest/facts rebuild; MCP BGP binding/export/community actions и WireGuard export. Их нынешний общий helper — точка подключения, но не доказательство отсутствия иных SQL/host writers.
  • Database replacement: system-database-backup.ts:restoreSystemDatabaseBackup и modules/mcp/database-restore.ts имеют отдельный lifecycle. Restore/archive exclusion и блокировка mapping во время replacement обязательны; hook application query сам по себе не покрывает external restore process.
  • Workers/background jobs и alternate pools: каждый actual createPool/worker execution entry и все прямые source-metadata writes должны участвовать до активации. Наличие SQL facade на основном thread не распространяется на другой процесс, external native API client или foreign RouterOS writer.

Для REST/UI, scheduler и MCP нужны отдельные конкретные original-authority adapters. withConfigurationActor хранит actor ID, а не подписанный lifetime; его нельзя объявить готовой writer authority. Для MCP уже существуют private captureVerifiedMcpServiceExecution / inspection/lifetime с исходными expiry/monotonic/signal — их можно использовать только в действительном активном service context, без изготовления token из JSON. Для остальных entrypoints исходные authentication/command deadlines надо захватить в trusted boundary. Нельзя включать guard через ready=true, no-op authorize или default synthetic source.

До включения обязательны inventory и остановка старых executors, согласованный restart/cutover всех процессов, доказательство покрытия SQL/native/restore writers, concurrency tests порядка locks и процедура unresolved-attempt operations. Отдельно остаются mapping operator enrollment и реальная независимая DNS/NAT authority/fence. Native direct observation не является атомарным routing/NAT snapshot.

Полученные доказательства

Следующие отчёты — actual owned disposable PostgreSQL/localhost acceptance; operator/source authority в них явно synthetic fixture authority. Production configuration, CHR и удалённая сеть не использовались.

Evidence Результат
tmp/mcp-router-configuration-guard-owned-pg-20261028.log Promoted kernel, exit 0: все 18 сценариев + DSN group; реальные роли/namespace/Ed25519/head MAC, same-PID nesting, mapping X-exclusion, forged ACK/idle refusal, restart persistence, actual COMMIT ACK loss
tmp/mcp-router-guard-v1-compatibility-owned-pg-20261028.log v1 same-control compatibility + полный existing 25-case suite PASS
tmp/mcp-speed-run-identity-owned-pg-20261028.log v2 same-control compatibility, wholeflow 6 и run-ID 4 PASS

Compatibility group устанавливает только собственные новые guard namespace/roles в той же настоящей control DB. До/после сравниваются exact core/node role/catalog digests; для v2 также external role/catalog/incoming FKs. Неизменённые реально настроенные core.identity, node.open().binding и физические SQL queries продолжают проходить существующие signed pins. Подписи, TTL и generation не переиздаются. Группа запускается только с MMAPP_TEST_ROUTER_GUARD_COMPATIBILITY=true; default harness не устанавливает guard. Эти проверки подтверждают совместимость протоколов, а не production cutover или all-writer activation.