docs(mcp): добавить документацию, аудиты вызовов и квитанции приёмки MCP
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
531d822338
commit
1d519b1734
945 files changed
+384627
No files matched your search
@@ -0,0 +1,68 @@
|
||||
# Рабочий источник ключа и метаданных 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).
|
||||
Reference in new issue
Block a user