Структура, доп модули, федерация, документация

backend/src/Docs/federation_module_documentation.md

@@ -0,0 +1,79 @@
+# Модуль Федерации (Federation Module) — Knot Messager
+
+Модуль федерации обеспечивает децентрализованное взаимодействие между независимыми узлами (серверами) Knot Messager. Он реализует безопасный обмен сообщениями, синхронизацию присутствия (Presence), проксирование медиафайлов и координацию системных политик.
+
+---
+
+## 🏗 Архитектура конфедерации
+
+Федерация Knot Messager построена на принципах **Zero-Knowledge** и **Intersected Policies**. Ключевые аспекты:
+1.  **Peer-to-Peer Trust**: Узлы доверяют друг другу на основе предварительного обмена публичными ключами (Handshake).
+2.  **Domain Isolation**: Модуль Федерации полностью изолирован от других модулей. Взаимодействие происходит через **Domain Events** (MediatR).
+3.  **No Data Duplication**: Файлы не копируются на чужие сервера, а стримятся через авторизованные прокси-каналы.
+
+---
+
+## 🔒 Безопасность и Шифрование
+
+Для защиты межсерверного трафика используется гибридная схема:
+*   **Payload Encryption (AES-256)**: Содержимое пакетов шифруется на лету уникальным ключом AES.
+*   **Key Wrapping (RSA-2048)**: Ключ AES и IV шифруются на публичный ключ сервера-получателя.
+*   **Authentication (RSA Signature)**: Каждый входящий пакет подписывается приватным ключом отправителя. Подпись проверяется получателем по белому списку доменов.
+
+---
+
+## 📥 Входящие типы пакетов (Inbound Messages)
+
+Модуль обрабатывает следующие типы федеративных транзакций через [InboundFederationCommand](file:///e:/GIT/forkmessager/backend/src/Modules/Federation/Application/Federation/Commands/InboundFederationCommand.cs#19-20):
+
+| Тип сообщения | Описание | Действие |
+| :--- | :--- | :--- |
+| `text` | Обычное текстовое сообщение. | Сохранение в БД и уведомление локальных юзеров. |
+| `presence_update` | Обновление статуса (Online/Offline/LastSeen). | Обновление кэша `IsOnline` для внешнего контакта. |
+| `sync_capabilities` | Синхронизация системных настроек. | Обновление правил (Media, Polls, RTC) для партнера. |
+| `rtc_signal` | WebRTC сигнализация (Offer/ICE). | Проброс сигнала конечному пользователю для звонка. |
+| `message_edited` | Редактирование сообщения. | Обновление контента локальной копии сообщения. |
+| `message_deleted` | Удаление сообщения "у всех". | Перманентное удаление сообщения из локальной БД. |
+| `reaction_added` | Добавление эмодзи-реакции. | Синхронизация реакции внешнего пользователя. |
+
+---
+
+## 📂 Проксирование медиа (Storage Proxy)
+
+Критически важный механизм, исключающий хранение чужих данных:
+1.  **Outgoing Proxy**: `/api/federation/v1/proxy/{id}` — сервер отдает файл только авторизованным серверам-партнерам.
+2.  **Incoming Proxy**: `/api/files/remote/{domain}/{id}` — ваш сервер выступает "транзитом", запрашивает файл у партнера и стримит его вашему клиенту.
+3.  **Безопасность**: Ссылки на медиа внутри сообщений всегда указывают на локальный прокси, а не на оригинальный домен отправителя.
+
+---
+
+## ⚙ Настройка и Handshake
+
+Администратор добавляет домен в белый список через `Admin Module`:
+1.  Генерируется пара RSA-ключей для своего сервера (если нет).
+2.  Выполняется запрос `/handshake` к удаленному серверу.
+3.  Обмениваются `Public Keys` и [Capabilities](file:///e:/GIT/forkmessager/backend/src/Shared/Knot.Shared.Kernel/Configuration/SystemSettingsDto.cs#90-98) (возможности сервера).
+4.  С этого момента домен считается **Trusted Node**.
+
+---
+
+## 📡 Реализованные API Эндпоинты
+
+*   `POST /api/federation/v1/handshake` — Установка связи.
+*   `POST /api/federation/v1/inbound` — Прием зашифрованных пакетов.
+*   `GET /api/federation/v1/resolve/{username}` — Поиск профиля по всей сети.
+*   `GET /api/federation/v1/proxy/{id}` — Стриминг контента для партнеров.
+
+---
+
+## 🧩 Взаимодействие с другими модулями (MediatR Events)
+
+*   [MessageSentDomainEvent](file:///e:/GIT/forkmessager/backend/src/Modules/Messaging/Domain/MessageSentDomainEvent.cs#9-10) ➡ Триггерит рассылку сообщения внешним участникам.
+*   [UserStatusChangedDomainEvent](file:///e:/GIT/forkmessager/backend/src/Modules/Auth/Domain/User.cs#5-6) ➡ Пушит статус пользователя всем серверам-контактам.
+*   [SystemSettingsUpdatedDomainEvent](file:///e:/GIT/forkmessager/backend/src/Modules/Admin/Domain/Events/SystemSettingsUpdatedDomainEvent.cs#10-11) ➡ Синхронизирует возможности (Capabilities) с сетью.
+*   `MessageEdited/DeletedDomainEvent` ➡ Транслирует действия с сообщениями.
+
+---
+
+> [!IMPORTANT]
+> Модуль Федерации требует корректно настроенного `System:DomainUrl` в глобальном конфиге для формирования подписей.