Files
MikrotikManager/docs/mcp-bandwidth-node-source.md
T

69 lines
9.5 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.
# Рабочий источник ключа и метаданных canonical registry
`bandwidth-node-source.ts` соединяет подписанный core source, отдельный постоянный HMAC issuer key, операторский bootstrap и фактическую registry-схему. В отличие от SQL/host-компонента, здесь уже нет передаваемых моделью verifier/key callbacks: production getter использует фиксированный core source и операторские переменные окружения. Конструкторы/import не читают файлы, не подключаются к БД и не создают authority/ключи/таблицы.
Источник не выдаёт разрешение пользователя на enrollment или native dispatch. Подписанная quiescence-привязка также не заменяет общий writer barrier и проверку исходного человеческого разрешения. Физическая уникальность, защита от клонирования/rollback самого control provider и общая DB READY здесь не объявляются.
## Операторские входные данные
Сначала нужен [подписанный core source](mcp-bandwidth-control-source.md) с отдельной control-БД. Registry DDL устанавливается её внешним owner. Core runtime получает дополнительные точные права: `SELECT` authority; `SELECT, INSERT` nodes/events; `SELECT, INSERT, UPDATE` aliases; `EXECUTE` фиксированных trigger functions. Он не получает node/authority UPDATE, DELETE, TRUNCATE, CREATE или owner membership. Основные core-права продолжают проверяться отдельно.
Три обязательные настройки перечислены в `backend/.env.example`:
```dotenv
MMAPP_BANDWIDTH_NODE_ISSUER_KEY_FILE=/etc/mmapp/control/node-issuer.key
MMAPP_BANDWIDTH_NODE_ISSUER_KEY_SHA256=<sha256-of-the-raw-32-byte-issuer-key>
MMAPP_BANDWIDTH_NODE_BOOTSTRAP_FILE=/etc/mmapp/control/node-bootstrap.json
```
Issuer key — заранее созданные **32 raw bytes**, постоянные для canonical identity. Это отдельный ключ: bootstrap с hash, равным core event key hash, отклоняется. Ротация credentials/адреса/MCP generation не меняет его. Startup/native dispatch никогда не создаёт ключ автоматически. Key/config files должны быть защищены от записи runtime и исключены из application backup вместе с control store; приватный Ed25519 ключ внешнего issuer backend не получает.
Bootstrap payload имеет строго следующие поля:
```json
{
"format": "mmapp-bandwidth-node-bootstrap-v1",
"installationId": "<same-installation-UUID-as-authenticated-core-source>",
"issuerKeySha256": "<64 lowercase hex characters>",
"quiescenceProof": "<operator-approved-initial-quiescence-evidence-hash>",
"registrySchemaSourceSha256": "<hash-of-current-literal-registry-DDL>",
"registryCatalogSha256": "<verified-actual-registry-catalog-hash>",
"attestationRef": "<operator change reference, 30 to 2000 characters>"
}
```
Внешний оператор подписывает canonical UTF-8 payload своим Ed25519 ключом. Используются `canonicalBandwidthNodeBootstrap()` и `bandwidthNodeRegistrySchemaSourceSha256()` из `bandwidth-node-bootstrap.ts`, а actual digest выдаёт фиксированный `observeBandwidthNodeRegistryCatalog()`. Подпись проверяется по независимому SPKI pin **того же внешнего issuer**, что закреплён в core source. Конверт:
```json
{
"format": "mmapp-bandwidth-node-bootstrap-envelope-v1",
"payload": "<canonical-payload-as-base64url-without-padding>",
"signature": "<64-byte-Ed25519-signature-as-base64url-without-padding>"
}
```
Owner отдельно устанавливает единственную immutable строку `bandwidth_node_authority` с совпадающими installation/key/quiescence значениями и `status=active`. Это внешняя операторская установка: отсутствие строки/файла, неверная подпись или несовпадение не запускают bootstrap. Готового разрешения нейросети на физический enrollment из этих данных не получается. Положительный автоматический issuer/publish/fault сценарий на поддерживаемой Linux FS и процедура genuine initial quiescence остаются отдельными открытыми условиями.
## Backend composition
Фиксированный production getter `getProductionBandwidthNodeSource()` предоставляет `open(scope, dispatchGuard?)`. Session использует **один** физический core lease и предлагает `connection`, `binding()`, `keyedProof()` и `close()`. Четыре одновременных session сохраняют четыре исходных backend PID; дополнительный пятый checkout при проверке ключа не требуется.
При создании registry host backend передаёт его фиксированному authorizer глубоко замороженное genuine observation. Authorizer обязан сопоставить его с исходным одобренным intent, проверить текущие права/expiry и лишь затем вернуть actor-specific authority. `binding()` предоставляет для этого installation/key/quiescence и source/bootstrap fingerprints; эти значения сами не являются разрешением. Public caller не передаёт callbacks, выбранный node UUID или JSON `ready=true`.
До `open()` фиксированная backend-композиция вычисляет один phase scope: минимум caller deadline, срока genuine observation и срока исходного actor grant. Этот же scope передаётся source session и registry host. Dispatch guard заново проверяет genuine observation/source и одобренные claims, затем последним actor grant. Он не должен проверять только actor-флаг, игнорируя более короткий native TTL.
`dispatchGuard` — серверный checker исходного actor/source grant. Он не должен повторно входить в этот control lease. Registry/source проверки проходят через ограниченный raw fence на том же физическом соединении **после** core metadata и до actual driver SQL; затем последним вызывается actor guard. Raw fence перестаёт действовать при завершении guard, его нельзя сохранить для позднего SQL. Проверки выполняются также перед выдачей результата. Это snapshots с отказом при обнаруженном drift, а не доказательство атомарной остановки всех filesystem/SQL/actor writers; общий barrier остаётся обязательным.
Перед HMAC файлы bootstrap/key читаются повторно после async metadata. Целиком закрепляются исходные signed bootstrap и core record; даже новый корректно подписанный record не подхватывается старым lease. Подтверждённый новый core generation допускается новым session и сохраняет прежние canonical UUID. Неизвестная занятость автоматически не освобождается.
Срок session ограничен исходным wall/monotonic budget до 10 секунд. Signal, `close()` и `release()` завершают pending waits, уничтожают lease и обнуляют все отслеживаемые key buffers, включая случай зависшего callback. Позднее завершение callback не даёт SQL/COMMIT. File reads ограничены размером и canonical no-symlink проверками; ошибки не возвращают содержимое ключей или provider responses.
## Проверка
```powershell
npm --prefix backend run test:bandwidth-node-source
npm --prefix backend run test:bandwidth-node-source:pg
```
[Приёмка](mcp-bandwidth-node-source-acceptance-20261026.json) использует реальные SQL-роли, подписи/ключи, genuine localhost observations и public dump/restore восьми control-таблиц. Operator/quiescence и actor grants в этом стенде явно synthetic. Дальше требуются настоящая enrollment authority, общий bandwidth guard всех callers, capacity/retention и полный public speed workflow из [реестра работ](mcp-remaining-work-20261026.md).