fixes

2025-07-27 03:12:33 +03:00
1 parent 8b68b0f1e3
commit 274c8f1f09
@@ -0,0 +1,515 @@
+# MY Network v3.0 - Межузловое общение с Ed25519
+
+## Обзор
+
+MY Network v3.0 использует криптографические подписи Ed25519 для безопасного межузлового общения. Каждая нода идентифицируется уникальным ключом Ed25519, что обеспечивает:
+
+- **Аутентификацию**: Каждое сообщение подписано приватным ключом отправителя
+- **Целостность**: Подпись гарантирует, что сообщение не было изменено
+- **Идентификацию**: Node ID основан на публичном ключе в формате base58
+- **Децентрализацию**: Ноды могут менять IP адреса, сохраняя постоянную идентичность
+
+## Архитектура
+
+```
+┌─────────────────┐    Ed25519 Signature     ┌─────────────────┐
+│     Node A      │◄──────────────────────────►│     Node B      │
+│   Private Key   │                           │   Public Key    │
+│   Public Key    │    Signed Messages        │   Verification  │
+│   Node ID       │                           │   Node ID       │
+└─────────────────┘                           └─────────────────┘
+```
+
+## Настройка Ed25519 ключей
+
+### Автоматическая генерация (рекомендуется)
+
+При запуске через `start.sh` ключи генерируются автоматически:
+
+```bash
+curl -sSL https://raw.githubusercontent.com/username/uploader-bot/main/start.sh | bash
+```
+
+### Ручная генерация
+
+```bash
+# Создание директории для ключей
+sudo mkdir -p /opt/my-network/keys
+sudo chmod 700 /opt/my-network/keys
+
+# Генерация ключей (выполняется в start.sh)
+# Приватный ключ: /opt/my-network/keys/ed25519_private.key
+# Публичный ключ: /opt/my-network/keys/ed25519_public.key
+# Node ID: /opt/my-network/keys/node_id.txt
+```
+
+### Структура ключей
+
+```
+/opt/my-network/keys/
+├── ed25519_private.key    # Приватный ключ (64 символа hex)
+├── ed25519_public.key     # Публичный ключ (64 символа hex)
+└── node_id.txt           # Node ID (base58 от публичного ключа)
+```
+
+## API Endpoints для межузлового общения
+
+### 1. Handshake - `/api/node/handshake`
+
+Инициализация связи между нодами.
+
+**Запрос:**
+```http
+POST /api/node/handshake
+Content-Type: application/json
+X-Node-Communication: true
+X-Node-ID: 8x7KJmG5w2d3FhN9QpLmB4c6VzY3Xt2a
+X-Node-Public-Key: a1b2c3d4e5f6...
+X-Node-Signature: 1a2b3c4d5e6f...
+
+{
+  "action": "handshake",
+  "node_info": {
+    "node_id": "8x7KJmG5w2d3FhN9QpLmB4c6VzY3Xt2a",
+    "version": "3.0.0",
+    "capabilities": [
+      "content_upload",
+      "content_sync", 
+      "decentralized_filtering",
+      "ed25519_signatures"
+    ],
+    "network_info": {
+      "public_key": "a1b2c3d4e5f6...",
+      "protocol_version": "1.0"
+    }
+  },
+  "timestamp": "2024-01-15T10:30:00.000Z"
+}
+```
+
+**Ответ:**
+```json
+{
+  "success": true,
+  "timestamp": "2024-01-15T10:30:01.000Z",
+  "node_id": "9y8LKnH6x3e4GiO0RqMnC5d7WaZ4Yu3b",
+  "data": {
+    "handshake_accepted": true,
+    "node_info": {
+      "node_id": "9y8LKnH6x3e4GiO0RqMnC5d7WaZ4Yu3b",
+      "version": "3.0.0",
+      "capabilities": [...],
+      "network_info": {...}
+    }
+  }
+}
+```
+
+### 2. Content Sync - `/api/node/content/sync`
+
+Синхронизация контента между нодами.
+
+**Типы синхронизации:**
+- `new_content` - Уведомление о новом контенте
+- `content_list` - Запрос списка доступного контента  
+- `content_request` - Запрос конкретного файла
+
+**Пример - Новый контент:**
+```http
+POST /api/node/content/sync
+{
+  "action": "content_sync",
+  "sync_type": "new_content",
+  "content_info": {
+    "hash": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
+    "title": "Example Video",
+    "size": 1048576,
+    "content_type": "video/mp4",
+    "timestamp": "2024-01-15T10:30:00.000Z"
+  },
+  "timestamp": "2024-01-15T10:30:00.000Z"
+}
+```
+
+### 3. Network Ping - `/api/node/network/ping`
+
+Проверка доступности и измерение задержки.
+
+**Запрос:**
+```http
+POST /api/node/network/ping
+{
+  "action": "ping",
+  "timestamp": "2024-01-15T10:30:00.000Z",
+  "data": {"test": true}
+}
+```
+
+**Ответ:**
+```json
+{
+  "success": true,
+  "data": {
+    "action": "pong",
+    "ping_timestamp": "2024-01-15T10:30:00.000Z",
+    "response_timestamp": "2024-01-15T10:30:01.000Z"
+  }
+}
+```
+
+### 4. Node Status - `/api/node/network/status`
+
+Получение статуса ноды (GET запрос, подпись не требуется).
+
+```http
+GET /api/node/network/status
+```
+
+```json
+{
+  "success": true,
+  "data": {
+    "node_id": "8x7KJmG5w2d3FhN9QpLmB4c6VzY3Xt2a",
+    "public_key": "a1b2c3d4e5f6...",
+    "version": "3.0.0",
+    "status": "active",
+    "capabilities": [...],
+    "timestamp": "2024-01-15T10:30:00.000Z"
+  }
+}
+```
+
+### 5. Node Discovery - `/api/node/network/discover`
+
+Обнаружение других нод в сети.
+
+```http
+POST /api/node/network/discover
+{
+  "action": "discover",
+  "known_nodes": [
+    {"node_id": "...", "url": "http://node1.example.com:8000"},
+    {"node_id": "...", "url": "http://node2.example.com:8000"}
+  ],
+  "timestamp": "2024-01-15T10:30:00.000Z"
+}
+```
+
+## Использование клиентских функций
+
+### Базовое использование
+
+```python
+from app.core.network.node_client import NodeClient, NodeNetworkManager
+
+# Создание клиента
+async with NodeClient() as client:
+    # Получение статуса ноды
+    status = await client.get_node_status("http://node.example.com:8000")
+    
+    # Отправка пинга
+    ping_result = await client.send_ping("http://node.example.com:8000")
+    
+    # Хэндшейк
+    our_node_info = {
+        "node_id": "our_node_id",
+        "version": "3.0.0",
+        "capabilities": ["content_upload", "content_sync"]
+    }
+    handshake_result = await client.send_handshake(
+        "http://node.example.com:8000", 
+        our_node_info
+    )
+```
+
+### Менеджер сети
+
+```python
+from app.core.network.node_client import get_network_manager
+
+# Получение менеджера
+network_manager = await get_network_manager()
+
+# Обнаружение нод
+bootstrap_nodes = [
+    "http://bootstrap1.mynetwork.org:8000",
+    "http://bootstrap2.mynetwork.org:8000"
+]
+discovered_nodes = await network_manager.discover_nodes(bootstrap_nodes)
+
+# Проверка здоровья нод
+health_results = await network_manager.check_node_health(discovered_nodes)
+
+# Трансляция нового контента
+content_info = {
+    "hash": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
+    "title": "New Video",
+    "size": 1048576,
+    "content_type": "video/mp4"
+}
+broadcast_results = await network_manager.broadcast_content(content_info)
+```
+
+## Подпись сообщений
+
+### Формат подписи
+
+1. **Сообщение**: JSON объект сериализуется в строку
+2. **Подпись**: Ed25519 подпись от сериализованного JSON
+3. **Заголовки**: Подпись и метаданные передаются в HTTP заголовках
+
+### Обязательные заголовки для межузлового общения
+
+```http
+X-Node-Communication: true
+X-Node-ID: <base58_node_id>
+X-Node-Public-Key: <hex_public_key>
+X-Node-Signature: <hex_signature>
+```
+
+### Пример создания подписи
+
+```python
+from app.core.crypto import get_ed25519_manager
+
+crypto_manager = get_ed25519_manager()
+
+# Сообщение
+message = {
+    "action": "ping",
+    "timestamp": "2024-01-15T10:30:00.000Z",
+    "data": {"test": True}
+}
+
+# Создание подписи
+signature = crypto_manager.sign_message(message)
+
+# Заголовки
+headers = {
+    "X-Node-Communication": "true",
+    "X-Node-ID": crypto_manager.node_id,
+    "X-Node-Public-Key": crypto_manager.public_key_hex,
+    "X-Node-Signature": signature
+}
+```
+
+### Проверка подписи
+
+```python
+# Проверка подписи (выполняется автоматически в middleware)
+is_valid = crypto_manager.verify_signature(
+    message, signature, public_key_hex
+)
+```
+
+## Конфигурация
+
+### Переменные окружения
+
+```bash
+# Пути к ключам (по умолчанию /opt/my-network/keys/)
+MY_NETWORK_KEYS_DIR=/opt/my-network/keys
+
+# Таймауты для межузлового общения
+NODE_CLIENT_TIMEOUT=30
+
+# Bootstrap ноды для обнаружения сети
+MY_NETWORK_BOOTSTRAP_NODES=http://bootstrap1.mynetwork.org:8000,http://bootstrap2.mynetwork.org:8000
+```
+
+### Настройка в Docker
+
+```yaml
+# docker-compose.yml
+version: '3.8'
+services:
+  my-network-node:
+    image: my-network:latest
+    volumes:
+      - my_network_keys:/opt/my-network/keys
+    environment:
+      - MY_NETWORK_KEYS_DIR=/opt/my-network/keys
+      - NODE_CLIENT_TIMEOUT=30
+    ports:
+      - "8000:8000"
+
+volumes:
+  my_network_keys:
+```
+
+## Безопасность
+
+### Защита приватных ключей
+
+1. **Файловые права**: `chmod 600 /opt/my-network/keys/ed25519_private.key`
+2. **Владелец**: Только пользователь приложения имеет доступ
+3. **Бэкапы**: Регулярное резервное копирование ключей
+4. **Ротация**: Возможность смены ключей с сохранением истории
+
+### Проверка подписей
+
+```python
+# Все входящие межузловые сообщения автоматически проверяются
+# в CryptographicMiddleware
+
+# Ручная проверка подписи
+from app.core.crypto import get_ed25519_manager
+
+crypto_manager = get_ed25519_manager()
+is_valid = crypto_manager.verify_signature(message, signature, public_key)
+
+if not is_valid:
+    raise SecurityError("Invalid message signature")
+```
+
+### Защита от replay-атак
+
+1. **Timestamp**: Каждое сообщение содержит timestamp
+2. **Nonce**: Опционально можно добавить nonce для дополнительной защиты
+3. **TTL**: Сообщения имеют время жизни
+
+## Диагностика и отладка
+
+### Проверка состояния ключей
+
+```bash
+# Проверка наличия ключей
+ls -la /opt/my-network/keys/
+
+# Проверка Node ID
+cat /opt/my-network/keys/node_id.txt
+
+# Проверка прав доступа
+stat /opt/my-network/keys/ed25519_private.key
+```
+
+### Логирование
+
+```python
+# Включение debug логов для криптографии
+import logging
+logging.getLogger('app.core.crypto').setLevel(logging.DEBUG)
+
+# Включение debug логов для межузлового общения  
+logging.getLogger('app.core.network').setLevel(logging.DEBUG)
+```
+
+### Тестирование соединения
+
+```bash
+# Тест статуса ноды
+curl http://localhost:8000/api/node/network/status
+
+# Тест здоровья приложения
+curl http://localhost:8000/health
+```
+
+### Проверка подписи вручную
+
+```python
+# Скрипт для тестирования подписей
+import asyncio
+from app.core.crypto import get_ed25519_manager
+
+async def test_signature():
+    crypto_manager = get_ed25519_manager()
+    
+    message = {"test": "message", "timestamp": "2024-01-15T10:30:00.000Z"}
+    signature = crypto_manager.sign_message(message)
+    
+    is_valid = crypto_manager.verify_signature(
+        message, signature, crypto_manager.public_key_hex
+    )
+    
+    print(f"Node ID: {crypto_manager.node_id}")
+    print(f"Signature valid: {is_valid}")
+
+# Запуск теста
+asyncio.run(test_signature())
+```
+
+## Примеры интеграции
+
+### Добавление в существующие API
+
+```python
+# В вашем API endpoint
+from app.core.network.node_client import get_network_manager
+
+@app.post("/api/content/upload")
+async def upload_content(request):
+    # ... обработка загрузки ...
+    
+    # Уведомление других нод о новом контенте
+    network_manager = await get_network_manager()
+    
+    content_info = {
+        "hash": content_hash,
+        "title": title,
+        "size": file_size,
+        "content_type": content_type,
+        "timestamp": datetime.utcnow().isoformat()
+    }
+    
+    # Асинхронно уведомляем другие ноды
+    asyncio.create_task(
+        network_manager.broadcast_content(content_info)
+    )
+    
+    return {"status": "uploaded", "hash": content_hash}
+```
+
+### Периодическая синхронизация
+
+```python
+# Фоновая задача для синхронизации
+async def sync_with_network():
+    network_manager = await get_network_manager()
+    
+    while True:
+        # Проверяем здоровье известных нод каждые 5 минут
+        await network_manager.check_node_health(network_manager.known_nodes)
+        
+        # Попытка обнаружить новые ноды каждые 15 минут
+        if len(network_manager.active_nodes) < 3:
+            await network_manager.discover_nodes(bootstrap_nodes)
+        
+        await asyncio.sleep(300)  # 5 минут
+
+# Добавление задачи в приложение
+app.add_background_task(sync_with_network())
+```
+
+## Миграция и совместимость
+
+### Обновление с предыдущих версий
+
+1. **Backup существующих данных**
+2. **Генерация новых ed25519 ключей**
+3. **Обновление конфигурации**
+4. **Тестирование подключения к сети**
+
+### Совместимость версий
+
+- **v3.0+**: Обязательные ed25519 подписи
+- **v2.x**: Опциональные подписи (deprecated)
+- **v1.x**: Без криптографической защиты (не поддерживается)
+
+### План миграции
+
+```bash
+# 1. Остановка текущей версии
+docker-compose down
+
+# 2. Backup данных
+tar -czf my-network-backup.tar.gz /opt/my-network/
+
+# 3. Обновление до v3.0
+curl -sSL https://raw.githubusercontent.com/username/uploader-bot/main/start.sh | bash
+
+# 4. Проверка работоспособности
+curl http://localhost:8000/health
+curl http://localhost:8000/api/node/network/status
+```
+
+Данная интеграция обеспечивает полную криптографическую защиту межузлового общения в MY Network v3.0, гарантируя безопасность и децентрализованность сети.