Files
MikrotikManager/docs/bandwidth-operator-peer-sources.md
T

56 lines
10 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.
# Guarded managed/external sources оператора
OP-M3 принят **как компонент**: оба источника привязаны к genuine исходному operator window, а metadata проверяет текущие данные без повторной выдачи credentials. Это третий из четырёх внутренних шагов остатка S3-06. Полная регистрация с measured Docker latency и эксплуатационное окно ещё не приняты; public callers не активированы.
## Допуск и время жизни
`windows.createPeerSourceGuard(window, original)` выдаёт private-branded guard только для своего оригинального допуска и удерживаемого window с действующим `lifetimeSignal`. Копии, JSON, структурные validators и чужие окна не принимаются. Публичный immutable `installationId` берётся из исходного grant и не даёт дополнительных полномочий.
- `verifyRead(binding, scope)` проверяет точный peer/sourceProof/generation/epoch исходного signed grant, его актуальность, реальный PID/session-exclusive lock и текущий Q. Проверка не возвращает credentials или raw connection.
- `verifyMetadata(binding, scope)` проверяет текущий исходный допуск и жизненный цикл окна без Q, SQL, ключей и native. Результат metadata остаётся снимком, а не доказательством Q или новым разрешением на effect.
`ProbeStorageConnection.lifetimeSignal` — только канал отзыва. Реальный connector всегда создаёт собственный native signal и синхронно отзывает его при error/deadline/release **до** physical release. Core/node передают тот же signal; их quiet key/HMAC paths также проверяют его. Window подписывается на него и немедленно отзывает guards. При нормальном завершении window сначала переводится в terminal и снимает listener, поэтому намеренное закрытие после COMMIT не превращает известный успех в UNKNOWN.
Добавление закрывает воспроизведённый дефект: успешный HELD probe → owner исчезает во время последующего await Q → Q возвращается нормально. До исправления guard мог завершиться успешно; после исправления consumer не получает допуска к key/decrypt. Это отзыв при обнаруженном закрытии физического соединения, не новый distributed/atomic fencing proof. Legacy окна без source guard сохраняют совместимость, но новый guard без lifecycle channel не выдаётся.
## Managed source
`createConfiguredManagedBandwidthPeerSource(config, guard)` получает только фиксированный server ID и public binding исходного grant. Constructor инертен. После проверки original authority и получения application lease genuine read guard допускает один фиксированный SQL с gated credential projection: точные ID, enabled и endpoint epoch обязательны в том же запросе. Поля и размер результата проверяются, затем current predicate и closing read guard подтверждаются до публикации приватного snapshot.
Metadata допускается только после успешного read этой instance, сравнивает private original snapshot и использует [managed boolean checker](bandwidth-peer-metadata.md) между двумя current-original metadata guards. Пароль остаётся приватным bound predicate внутри PG; unkeyed password hash не создаётся. Первый wall и monotonic deadline не продлеваются новым scope. Используется существующий application pool, без дополнительного pool, роли или миграции.
## Encrypted external source
`createConfiguredExternalBandwidthPeerSource(config, guard)` читает только явно подготовленные operator files. Constructor ничего не создаёт. `profileFile` и `keyFile` — разные canonical absolute paths; installation должна совпадать с genuine guard **до I/O**. External peer остаётся external enrollment ID, без фиктивного application server ID.
Profile — canonical UTF-8 JSON формата `mmapp-bandwidth-external-management-v1`:
| Поле | Значение |
| --- | --- |
| `installationId`, `enrollmentId` | UUID установки и external peer |
| `generation`, `routingEndpointEpoch` | UUID текущего management-source поколения и endpoint |
| `enabled` | Разрешён только текущий включённый профиль |
| `keySha256` | Public pin 32-byte operator key |
| `ciphertext` | base64url от `iv12 || GCM-tag16 || ciphertext` |
AES-256-GCM AAD — canonical UTF-8 JSON всех public header fields, кроме `ciphertext`. Plaintext — strict canonical JSON шести полей: host, port, useSsl, verifySsl, username, password. IV при подготовке должен быть новым криптографически случайным значением; компонент не выполняет provisioning и не использует обычный `encryptSecret` без этого AAD. `sourceProof` — SHA-256 всего canonical **randomized ciphertext profile**, а не пароля/plaintext.
Read проверяет свежий profile и source directory identity, genuine read guard до key read, 32-byte key pin, guard до decrypt и fresh profile/guard до возврата. Key/plaintext Buffers очищаются внутри async work `finally`, включая поздние результаты после отмены. JS credential strings остаются приватными в исходном snapshot; гарантия стирания всей памяти не заявляется.
Metadata требует успешного первоначального read той же instance. Проверяются private original snapshot, текущие ciphertext/profile/generation/epoch, source directory realpath/dev/ino и original authority guards. Key не читается, decrypt не выполняется, Q/control SQL/native не вызываются. Metadata работает при отсутствии key file и **не утверждает**, что текущий key доступен или endpoint сейчас принимает пароль. Смена generation/ciphertext или byte-identical directory clone отзывает исходный source; fallback и автоматического replay нет.
## Серверная композиция
`createBandwidthOperatorWriterComposition` принимает один из вариантов: legacy `observationSource` либо `createObservationSource(guard)`. Factory захватывается при создании сервиса и вызывается только после удержания genuine window, внутри registry phase. Это trusted server construction, не callback или путь из HTTP/MCP/model payload. Source закрывается в `finally`; Docker wrapper передаёт factory дальше. Runtime default, публичный endpoint, producer ключей или автоматическая активация не добавлены.
Профиль, ключ и signed grant готовятся доверенным оператором отдельно. Новые sources не останавливают backend, не меняют policy/образы и не выполняют RouterOS mutations. Следующий OP-M4 должен использовать эти факты в закрытой fixed effect composition на том же физическом lease; текущие legacy nested guards не объявляются быстрыми только из-за наличия metadata methods.
## Приёмка
- 57 focused connector/source/guard/composition tests; до исправления owner-during-Q сохранён failing counterexample. Настоящие signatures, AES/files и исходные pure validators; raw SQL/Q в unit явно синтетические.
- 9 actual owned PostgreSQL/localhost групп: encrypted external и managed positive, generation/ciphertext/directory/grant/copy negatives, owner loss до initial read и после настоящего HELD ACK во время Q. Metadata не добавляет Q/control SQL/native/credentials, включая опыт с отсутствующим key file.
- Завершается только PID, совпавший с owned database и owner role; signal abort подтверждается до нормального возврата Q и до исходного deadline. После этого отсутствуют новый GET/POST и COMMIT. Cleanup join наблюдает завершение начатого callback, не продлевая authority.
- Native 77/77, полная peer-регрессия, probe/storage models и build прошли. Legacy owned PG: 24 группы, 89 license GET, 2 btest POST, сохранение unknown и 39 миграций.
Q и catalog source новой owned-композиции обозначены synthetic fixtures; это не положительная production Docker-window приёмка. Реальные CHR, рабочая БД и оставшееся разрешённое окно стенда не использовались. [Source-pinned отчёт](mcp-guarded-peer-sources-acceptance-20261029.json).