# Модуль Федерации (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` в глобальном конфиге для формирования подписей.