179 lines
35 KiB
Markdown
179 lines
35 KiB
Markdown
# Vnox: предложение по серверной архитектуре
|
||
|
||
Статус: выбранное архитектурное направление по обратной связи пользователя; точные API и криптографические протоколы ещё проектируются. Новый дизайн клиента утверждён и реализуется отдельно. Сервер сообщества всегда обслуживает свой голос локально; отдельные голосовые машины исключены из плана.
|
||
|
||
## Продуктовая модель
|
||
|
||
Система состоит из центрального `vnox-hub` и независимых `vnox-server`. Hub — одна логическая служба глобальной сети; каждый сервер сообщества запускается одной программой, объединяющей gateway, голос, SQLite и каталог файлов. Отдельные голосовые машины не проектируются.
|
||
|
||
Одна обычная установка сервера — одно основное сообщество. Существующие guild_id сохраняются для корректной области прав и совместимости данных; миграция многогильдейских установок потребует отдельного решения. Первый клиентский этап сохраняет одно активное подключение к серверу; удобное одновременное присутствие в нескольких сообществах потребует менеджера соединений.
|
||
|
||
### Ответственность Hub
|
||
|
||
- Постоянные user_id, уникальный handle, публичный профиль, зарегистрированные устройства и их отзыв.
|
||
- Глобальные друзья, запросы, блокировки и настройки видимости присутствия.
|
||
- Реестр server_id, ключей, подтверждённых адресов, описаний, версий протокола и состояния доступности.
|
||
- Публичный поиск только для серверов, включивших публикацию. Регистрация ID не означает публичность.
|
||
- Персональная очередь зашифрованных личных сообщений и синхронизация между устройствами. Hub хранит ciphertext и служебные метаданные, а не ключи расшифрования. Сам E2EE-протокол и восстановление истории требуют отдельной спецификации.
|
||
|
||
### Ответственность сервера сообщества
|
||
|
||
Каналы, категории, роли, членство, приглашения, сообщения и история сообщества, файлы, голосовые комнаты, локальная модерация и аудит. Дружба в Hub не даёт доступа к закрытому сообществу. Hub не получает историю каналов для поиска и не передаёт голосовые пакеты.
|
||
|
||
Глобальные личные сообщения идут через Hub, а не через случайный общий сервер друзей. Старые server-local DM не превращаются в глобальные автоматически: нужна явная миграция с учётом ключей и участников. Межсерверную федерацию сообщений первой версии не строим.
|
||
|
||
## Регистрация и доверие серверу
|
||
|
||
1. Сервер локально создаёт identity; приватный ключ остаётся у владельца.
|
||
2. Владелец авторизуется в Hub и регистрирует сервер, доказывая владение ключом. Hub проверяет управление заявленным endpoint и выдаёт постоянный server_id.
|
||
3. Hub подписывает запись, связывающую server_id, ключ и адреса, с версией/сроком действия. Клиент проверяет подпись записи и владение сервером соответствующим ключом. TLS остаётся обязательным сетевым механизмом доверия согласно выбранной политике сертификатов; запись Hub не оправдывает отключение проверки TLS.
|
||
4. Переезд на другой адрес сохраняет ID. Смена ключа требует подтверждённой процедуры, записи смены и обновления доверия; потерянный ключ не заменяется молча.
|
||
5. Публичность настраивается отдельно: public — индексируется; unlisted — доступ по приглашению/точному ID; private — сведения только разрешённым пользователям. Приватный адрес не публикуется в общедоступных ответах реестра.
|
||
|
||
`server_id` доказывает связь с зарегистрированной identity, а не честность администратора. Знание ID не является правом доступа. Heartbeat показывает свежесть наблюдения о доступности, а не гарантирует доступность для любого клиента.
|
||
|
||
### Что можно проверить у сборки
|
||
|
||
Официальные артефакты подписываются и проверяются при установке/обновлении, привязываются к исходникам и процессу сборки. Воспроизводимость позволяет независимо сравнить результат сборки. Это не доказывает, что удалённая машина сейчас исполняет этот артефакт.
|
||
|
||
Присланный сервером hash/version или ответ на тестовый запрос не является доказательством исполняемого кода. Поэтому интерфейс показывает отдельные факты: «identity зарегистрирована», «endpoint подтверждён», «совместимость проверена», «версия заявлена сервером». Не выдавать значок «безопасный сервер» или «точно неизменённый код» на этой основе.
|
||
|
||
Удалённая аттестация требует отдельного доверенного источника измерений и связывания с текущей сессией. TPM/TEE и подобная инфраструктура не входят в MVP и не дают абсолютной гарантии отсутствия ошибок, утечек или вредоносного администратора.
|
||
|
||
## Профиль, устройства и приватность
|
||
|
||
user_id постоянный; handle уникальный и может меняться по политике переименования; отображаемые имена не обязаны быть уникальными. Сообщество может иметь локальный nickname. Авторизация устройства отделена от права администратора сервера; чужому серверу не передаётся универсальный токен Hub.
|
||
|
||
Вход на сервер использует доказательство владения ключом устройства и короткоживущее, привязанное к этому server_id подтверждение Hub. Конкретный формат подтверждений, защита от повторов и отзыв задаются общим протоколом. Устройства и учётная запись различаются, чтобы отзыв одного устройства не требовал менять глобальную identity. Протокол обязан задать максимальную задержку отзыва уже активных community-сессий: при недоступном Hub немедленный глобальный отзыв не гарантируется. Верхняя граница задаётся сроком авторизации и политикой проверки свежести, а не бессрочным кэшем.
|
||
|
||
Поиск людей по умолчанию — точный handle/ID или общие сообщества с разрешённой видимостью. Нельзя перечислять всех пользователей. Запросы в друзья ограничиваются настройками получателя и лимитами. Блокировки действуют и на запросы/DM. Где пользователь находится и во что играет, видно только выбранной аудитории.
|
||
|
||
Шифрование DM не скрывает автоматически метаданные от Hub: получателей, время, объём и факт связи. Обычные каналы сообщества доступны его серверу; шифрование транспорта не означает E2EE. Восстановление аккаунта и ключей истории — разные процедуры: сброс входа сам по себе не расшифровывает старую историю.
|
||
|
||
## Сроки хранения глобальной лички
|
||
|
||
Решение пользователя: сообщения Hub хранятся 7 дней; вложения до 20 МБ хранятся 4 дня. Это политика глобальных DM, не автоматическое ограничение истории сообществ.
|
||
|
||
- Время задаётся сервером в UTC: message.expires_at = accepted_at + 7×24 часа; attachment.expires_at = upload_completed_at + 4×24 часа. Прочтение, скачивание и повтор запроса с тем же idempotency key не продлевают срок.
|
||
- Неотправленные/незавершённые загрузки имеют отдельный короткий TTL и учитываются в квотах; нельзя хранить файлы бессрочно, не завершив сообщение.
|
||
- При expires_at API немедленно прекращает выдачу ciphertext и скачивание. Фоновая очистка удаляет объекты, записи, производные данные и кэши с повтором после ошибок и контролем отставания. Нужно задать и проверить отдельный SLA физического удаления до публичного запуска.
|
||
- Вложение может исчезнуть раньше сообщения. Клиент показывает срок до отправки и «Срок хранения файла истёк» после, не бесконечную загрузку. Ключ вложения и его метаданные передаются внутри E2EE сообщения.
|
||
- Лимит «20 МБ» трактуем как 20 000 000 байт исходного файла. Допустимый размер шифрованной загрузки определяется выбранным форматом с ограниченным overhead; Hub ограничивает реально принятые байты потока, а не доверяет Content-Length. Точные пределы ciphertext фиксируются в спецификации вложений.
|
||
- Ограничивается не только один файл: нужны суммарные квоты, число параллельных/незавершённых загрузок и скорость запросов. Лимит 20 МБ сам по себе не ограничивает суммарную нагрузку.
|
||
- Вложения приватные: проверка участника DM на каждый download, непрозрачные object_id, отсутствие общедоступных вечных URL. Пересылка ссылки не отменяет истечение срока.
|
||
- По умолчанию payload DM и файлы не включаем в долговременные backup. Для оперативных снимков/реплик и журналов задать срок, очистку и защиту от воскрешения expired данных при restore. В логи не попадают текст сообщений, ключи и содержимое файлов.
|
||
- Клиентский кэш учитывает expires_at и очищается; давно офлайн-устройство очищается при следующем запуске/синхронизации. Нельзя гарантировать удаление сохранённой получателем копии, скриншота или данных на изменённом клиенте. TTL на Hub не является доказательством стирания всех копий или форензического стирания носителя.
|
||
|
||
## Безопасность: отдельная спецификация перед глобальными DM
|
||
|
||
Нужно проектировать протокол и жизненный цикл ключей целиком, а не выбирать только название шифра. Перед реализацией зафиксировать угрозы: подмена сервера/устройства, злонамеренный Hub, утрата устройства, повторы, потери и перестановка пакетов, недоступность центра, вредоносные вложения и исчерпание ресурсов.
|
||
|
||
1. Сеть: актуальная поддерживаемая реализация TLS 1.3 с проверкой сертификатов; TLS и E2EE решают разные задачи.
|
||
2. Личка: проверенная реализация протокола асинхронного обмена с обновлением ключей (семейство Signal key agreement + ratchet — кандидат, не уже выбранная библиотека). Double Ratchet не заменяет первичную аутентификацию, управление устройствами и проверку ключей собеседника.
|
||
3. Устройства: отдельные авторизованные ключи, подтверждение добавления, отзыв, заметное изменение identity и возможность сверить fingerprint/QR. Ключи расшифрования остаются на устройствах. Компрометация Hub не должна позволять незаметную подмену доверенного устройства; точная модель transparency/verification требует разбора.
|
||
4. Вложения: отдельный случайный ключ на объект, аутентифицированное шифрование на клиенте, ключ внутри E2EE сообщения. Hub хранит ciphertext. Сервер не может одновременно не знать plaintext и обещать его антивирусную проверку; не запускать и не открывать активные файлы автоматически. Ограничивать парсеры превью и распаковку на клиенте.
|
||
5. Реализация: библиотеки и их поддержку/лицензии проверить отдельно; никаких собственных схем nonce, обмена ключами или групповой криптографии. Нужны независимое ревью и тесты на replay, tampering, смену/отзыв ключей, потерю пакетов, дубли, истечение TTL и восстановление после сбоя.
|
||
|
||
Текущий client/server E2EE не считается готовой основой глобальной лички: UI-аудит обнаружил отправку обычным DmSend и несогласованное использование message_id при расшифровании. До согласованного исправления нельзя показывать подтверждённое сквозное шифрование или незаметно отправлять plaintext вместо encrypted DM.
|
||
|
||
Источники для проработки: [Double Ratchet](https://signal.org/docs/specifications/doubleratchet/), [Sesame: несколько устройств и асинхронные сессии](https://signal.org/docs/specifications/sesame/), [OWASP: ограничения и обработка загрузок](https://cheatsheetseries.owasp.org/cheatsheets/File_Upload_Cheat_Sheet.html).
|
||
|
||
## Поиск, доступность и отказ центра
|
||
|
||
В каталог попадают явно опубликованные карточки: название, описание, язык, теги и политика вступления. Публичный поиск исключает приватные каналы и списки друзей. Модерация каталога, жалобы, rate limits и защита от массовой регистрации нужны до общего публичного запуска.
|
||
|
||
Уже установленные локальные подключения к серверам не проверяют Hub на каждом сообщении. При недоступности Hub они продолжают работу в рамках своей действующей авторизации. Серверы запускаются с сохранённой identity и регистрацией; отключение центра не выключает голос активных сообществ.
|
||
|
||
Новый глобальный вход, поиск, изменения друзей и глобальная очередь DM при отказе центра недоступны. Повторное подключение известных участников по кэшированным подтверждениям допускается только в пределах явного срока и политики отзыва; не обещать неограниченную офлайн-авторизацию. Просроченный кэш не превращается в доверенный автоматически. Прямое подключение по сохранённому адресу не обходит локальные bans и права.
|
||
|
||
## Сценарий подключения
|
||
|
||
1. Владелец запускает сервер и получает одноразовый способ назначения владельца. Нельзя автоматически назначать владельцем первого произвольного сетевого клиента.
|
||
2. Пользователь добавляет адрес или приглашение. Клиент получает подписанную Hub запись server_id и проверяет TLS/владение ключом; смена ключа не принимается молча.
|
||
3. Пользователь предъявляет привязанное к серверу подтверждение глобальной identity и доказывает владение авторизованным ключом устройства. Права на конкретном сервере определяются локально.
|
||
4. Сервер проверяет допуск: приватное сообщество требует приглашения/существующего членства; публичное может разрешать самостоятельный вход. Подключение к узлу само по себе не даёт доступ ко всем данным.
|
||
5. Сервер отправляет согласованный снимок доступных каналов, участников и настроек плюс курсор событий. Затем идут обновления. Границу снимка и потока фиксировать явно, чтобы не терять события между ними.
|
||
|
||
## Раздельные состояния
|
||
|
||
`ConnectionSession` хранит аутентификацию, устройство и курсор синхронизации. `VoiceSession` хранит отдельное участие в комнате. Выбранная переписка — клиентское состояние; сервер проверяет доступ к каждому запросу истории или отправки.
|
||
|
||
Подписки разделяются по объёму: изменения структуры и счётчики непрочитанного для доступных каналов; подробный поток сообщений для открытых разговоров. Переход в текстовый канал или DM не изменяет голос. Доступ перепроверяется при изменении ролей, kick/ban и отзыве приглашения; активные подписки и голос могут быть отозваны.
|
||
|
||
## Сообщения и восстановление
|
||
|
||
Команда отправки содержит client_request_id, целевой conversation_id и контент. Сервер проверяет права и лимиты, назначает итоговые ID/время/порядок, сохраняет запись и возвращает подтверждение отправителю. Повтор с тем же ключом в рамках отправителя/устройства возвращает прежний результат, а не создаёт дубль.
|
||
|
||
Для истории нужны курсоры со стабильным порядком (не один timestamp), пагинация и непрочитанное на основе позиции прочтения. Для reconnect — durable события или версионированное состояние с явной полной пересинхронизацией при невозможности догнать. Запись сообщения и события должна быть согласована транзакцией; outbox понадобится при отдельном фоне доставки.
|
||
|
||
Потеря событий из очереди не должна ограничиваться записью в лог. Переполненный клиент получает resync_required либо отключается с возможностью догнать. Сетевой reader непрерывно собирает кадры; writer обслуживает ограниченную очередь. Медленный клиент не блокирует обработку других клиентов. Парсинг неполного кадра не должен терять состояние при отмене ожидания.
|
||
|
||
## Права и членство
|
||
|
||
Один общий сервис авторизации обслуживает handlers. Права проверяются на сервере для чтения, истории, отправки, редактирования, удаления, управления каналами/ролями, приглашений и голосового подключения/передачи. Решение учитывает фактическое членство, владельца, роли и channel overrides с явно определённым порядком применения. Управление ролями не должно позволять повысить себя выше выданных полномочий.
|
||
|
||
Выход из сообщества затрагивает только самого пользователя; удаление другого — отдельная проверяемая команда kick. Приватный join не обходит invite. Удаление членства, назначений ролей и обновление активных сессий должны быть согласованы.
|
||
|
||
## Голос
|
||
|
||
Gateway проверяет подключение к комнате и выдаёт короткоживущий допуск, связанный с пользователем, сессией, комнатой и локальным голосовым модулем сервера. Клиент регистрируется на локальном голосовом модуле из настоящего UDP-сокета; адрес не берётся из TCP-порта. Relay проверяет допуск и подтверждение владения сессией. Одного знания channel_id или endpoint недостаточно.
|
||
|
||
Использовать единую модель channel_id между хранилищем, протоколом и relay. При необходимости компактный числовой идентификатор выдаётся явным отображением, а не parse строкового имени. Пакеты несут явный номер последовательности/epoch; потеря пакета не сбивает расшифровку последующих. Аудит текущего кода выявил усечение sequence до32бит при построении nonce: до повторного использования необходимо обновить ключи/сессию или завершить соединение. Обновление crypto-crates само по себе эту протокольную проблему не устраняет. Нужны replay window, ограничения размера/скорости и обновление ключей/nonce space.
|
||
|
||
Heartbeat сохраняет молчащих слушателей. Выход, kick, ban, смена комнаты и отзыв прав очищают допуск и маршрут. Jitter и смешивание относятся к отдельным потокам отправителей; итоговую задержку оценивать с учётом буферов relay и клиента.
|
||
|
||
Криптографический режим голоса остаётся открытым решением: transport encryption до доверенного relay либо настоящее групповое E2EE с управлением ключами и их сменой при изменении состава. Текущий relay нельзя называть работающим E2EE без проверки распределения ключей. Не проектировать собственную групповую криптографию поверх текущего session crypto без отдельного протокольного разбора.
|
||
|
||
## Хранение и эксплуатация
|
||
|
||
SQLite — простой стартовый backend. PostgreSQL остаётся альтернативой, проверяемой теми же сценариями; сам выбор PostgreSQL не даёт кластеризацию. Переход к нескольким gateway требует согласованных сессий, маршрутизации и событий.
|
||
|
||
Нужны последовательные миграции БД, восстановление сохранённых каналов при старте, корректный shutdown, диагностика состояния и проверяемый backup/restore. Резервная копия включает БД, файлы, конфигурацию и identity сервера; секреты защищаются отдельно. Presence отражает живые сессии и не восстанавливается как вечный ONLINE из БД.
|
||
|
||
Вложения — отдельный этап: хранилище объектов/каталог, лимиты, квоты и проверка права скачивания. Административные операции имеют отдельные права и журнал; admin API по умолчанию локальный, удалённый доступ явно защищён.
|
||
|
||
## Приоритет реализации
|
||
|
||
Минимальный Hub включает реестр, identity, друзей и поиск. Глобальный E2EE mailbox, синхронизация устройств и восстановление истории — следующий отдельный этап, а не условие запуска первого реестра. До этого личные сообщения явно помечаются как server-local; их нельзя показывать как уже глобальные.
|
||
|
||
|
||
1. Зафиксировать границы Hub/сообщества и общий protocol crate, подключить клиент к Protobuf/TLS.
|
||
2. Создать минимальный Hub: registry, server_id/ключи, user_id/устройства и привязанные к серверу подтверждения. Глобальные друзья/поиск идут следующим слоем, DM — после спецификации E2EE.
|
||
3. Закрыть авторизацию членства и операций; восстановление данных и миграции.
|
||
4. Разделить просмотр переписки, подписки и VoiceSession.
|
||
5. Согласовать UDP registration, ID, heartbeat и криптографический режим голоса.
|
||
6. Доставка с подтверждением, идемпотентность, история и reconnect/resync.
|
||
7. Проверить два клиента: сообщения, голос, переключение, обрыв, повторная отправка, kick и рестарт сервера.
|
||
8. Затем обсуждения/вложения и расширение глобальных функций. Отдельные голосовые машины исключены. Межсерверная федерация позже и только при реальной потребности.
|
||
|
||
## Подтверждённые ограничения текущего кода
|
||
|
||
- `domain/session.rs`: единственный channel_id объединяет текст и голос.
|
||
- `handler/deliver.rs`: доставка по текущему каналу; глобальные события требуют проверки области видимости.
|
||
- `handler/run.rs`: Lagged только логируется; read_encrypted содержит read_exact внутри select.
|
||
- `handler/content/chat.rs`: время клиента сохраняется, если ненулевое; нет полноценного ack отправителю.
|
||
- `handler/guild/members.rs`: join добавляет членство напрямую; leave принимает чужой user_id без kick-проверки.
|
||
- `gateway/src/lib.rs`: при создании State используется new_store; существующий load_channels_to_cache не подключён.
|
||
- `net/state.rs`: signalling голоса — broadcast строк JSON внутри процесса.
|
||
- `voice-node/src/runner.rs`: UDP отправитель самостоятельно добавляется по channel_id.
|
||
- Клиент сериализует JSON, gateway использует Protobuf; это блокирует совместный сценарий до согласования протокола.
|
||
|
||
## Источники по границам проверки кода
|
||
|
||
- Sigstore: проверка подписей артефактов — https://docs.sigstore.dev/cosign/verifying/verify/
|
||
- Reproducible Builds: что означает воспроизводимость — https://reproducible-builds.org/docs/definition/
|
||
- IETF RFC 9334: модель доверия и evidence для remote attestation — https://www.rfc-editor.org/rfc/rfc9334.html
|
||
|
||
Эти механизмы решают разные задачи. Подпись дистрибутива не является удалённой аттестацией процесса.
|
||
|
||
## Согласование старой документации
|
||
|
||
`docs/05-features/central-hub.md` описывает прежний необязательный Hub без хранения DM; `docs/02-protocol/identity.md` отрицает центральный реестр. Они требуют обновления перед реализацией нового контракта. Этот документ фиксирует новое направление и не утверждает, что Hub уже реализован.
|
||
|
||
## Плагины и маркетплейс
|
||
|
||
Новое направление: WASM-плагины на сервере сообщества, общий Plugin API и SDK для Rust/Lua/Python; Wasmtime — основной кандидат. Каталог и immutable release-пакеты находятся в Hub. Плагины работают с явными правами и лимитами, не получают глобальную E2EE-личку или полный доступ к host. Отдельные голосовые машины не требуются. Подробная модель: [plugins-and-marketplace.md](plugins-and-marketplace.md).
|
||
|
||
## Регистрация и профили
|
||
|
||
Для первого Hub предлагаются GitHub OAuth и email-код, с устойчивым внутренним user_id, явной привязкой способов входа и отдельными ключами устройств. Подробности и UX редактора аватара: [accounts-and-avatars.md](accounts-and-avatars.md).
|