diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml deleted file mode 100644 index 963943d..0000000 --- a/.gitlab-ci.yml +++ /dev/null @@ -1,26 +0,0 @@ -# You can override the included template(s) by including variable overrides -# SAST customization: https://docs.gitlab.com/ee/user/application_security/sast/#customizing-the-sast-settings -# Secret Detection customization: https://docs.gitlab.com/ee/user/application_security/secret_detection/#customizing-settings -# Dependency Scanning customization: https://docs.gitlab.com/ee/user/application_security/dependency_scanning/#customizing-the-dependency-scanning-settings -# Container Scanning customization: https://docs.gitlab.com/ee/user/application_security/container_scanning/#customizing-the-container-scanning-settings -# Note that environment variables can be set in several places -# See https://docs.gitlab.com/ee/ci/variables/#cicd-variable-precedence -stages: -- build -- test -- deploy -- review -- dast -- staging -- canary -- production -- incremental rollout 10% -- incremental rollout 25% -- incremental rollout 50% -- incremental rollout 100% -- performance -- cleanup -sast: - stage: test -include: -- template: Auto-DevOps.gitlab-ci.yml diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..e1aa181 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,62 @@ +# Politique de Sécurité - sdk_relay + +## Signalement de Vulnérabilités + +**NE PAS** créer d'issue publique pour les vulnérabilités de sécurité. + +**Contact :** security@4nkweb.com + +### Processus de Signalement +1. Email à security@4nkweb.com +2. Objet : "SECURITY VULNERABILITY - sdk_relay" +3. Description détaillée +4. Étapes de reproduction +5. Impact potentiel + +### Réponse +- Accusé de réception sous 48h +- Évaluation de la vulnérabilité +- Plan de correction +- Communication de la résolution + +## Bonnes Pratiques + +### Code +- Validation des entrées utilisateur +- Gestion sécurisée des erreurs +- Pas de secrets en dur +- Utilisation de dépendances à jour + +### Configuration +- Authentification Bitcoin Core +- Validation des messages WebSocket +- Rate limiting +- Logs sans données sensibles + +### Déploiement +- Images Docker signées +- Variables d'environnement sécurisées +- Monitoring de sécurité +- Mises à jour régulières + +## Audit de Sécurité + +### Composants +- **WebSocket** : Validation des messages +- **HTTP API** : Authentification et autorisation +- **Bitcoin Core** : Connexion RPC sécurisée +- **Synchronisation** : Validation des relais + +### Tests +- `cargo audit` pour les dépendances +- Tests de sécurité automatisés +- Validation des configurations +- Tests de pénétration + +## Responsabilité + +La sécurité est une responsabilité partagée entre l'équipe de maintenance et la communauté. + +--- + +**Merci de contribuer à maintenir sdk_relay sécurisé !** 🔒 diff --git a/docs/API.md b/docs/API.md new file mode 100644 index 0000000..a399327 --- /dev/null +++ b/docs/API.md @@ -0,0 +1,466 @@ +# API Reference - sdk_relay + +## Vue d'Ensemble + +`sdk_relay` expose deux interfaces principales : +- **WebSocket** (port 8090) : Communication temps réel +- **HTTP** (port 8091) : API REST + +## Interface WebSocket + +### Connexion +```javascript +const ws = new WebSocket('ws://localhost:8090'); +``` + +### Handshake Initial +```javascript +// Message de handshake +const handshake = { + "type": "handshake", + "client_id": "my-client", + "version": "1.0.0", + "capabilities": ["sync", "notifications"] +}; + +ws.send(JSON.stringify(handshake)); +``` + +### Types de Messages + +#### 1. Messages de Synchronisation +```json +{ + "type": "sync", + "sync_type": "StateSync", + "relay_id": "relay-1", + "payload": { + "state": { + "uptime": "3600", + "version": "1.0.0", + "network": "signet" + } + }, + "timestamp": 1703001600, + "message_id": "msg-123" +} +``` + +#### 2. Messages de Notification +```json +{ + "type": "notification", + "notification_type": "payment_detected", + "data": { + "txid": "abc123...", + "block_height": 12345, + "amount": "0.001", + "address": "sp1..." + }, + "timestamp": 1703001600 +} +``` + +#### 3. Messages de Santé +```json +{ + "type": "health", + "status": "healthy", + "metrics": { + "uptime": 3600, + "memory_usage": "128MB", + "cpu_usage": "5%", + "connections": 10 + }, + "timestamp": 1703001600 +} +``` + +### Événements WebSocket + +#### Connexion +```javascript +ws.onopen = function() { + console.log('Connecté à sdk_relay'); + // Envoyer le handshake + ws.send(JSON.stringify(handshake)); +}; +``` + +#### Réception de Messages +```javascript +ws.onmessage = function(event) { + const message = JSON.parse(event.data); + + switch(message.type) { + case 'handshake_response': + console.log('Handshake accepté'); + break; + case 'sync': + handleSyncMessage(message); + break; + case 'notification': + handleNotification(message); + break; + case 'health': + handleHealthUpdate(message); + break; + } +}; +``` + +#### Gestion d'Erreurs +```javascript +ws.onerror = function(error) { + console.error('Erreur WebSocket:', error); +}; + +ws.onclose = function(event) { + console.log('Connexion fermée:', event.code, event.reason); +}; +``` + +## Interface HTTP + +### Base URL +``` +http://localhost:8091 +``` + +### Endpoints + +#### 1. Santé du Service +```http +GET /health +``` + +**Réponse :** +```json +{ + "status": "healthy", + "uptime": 3600, + "version": "1.0.0", + "timestamp": 1703001600 +} +``` + +#### 2. Métriques +```http +GET /metrics +``` + +**Réponse :** +```json +{ + "sync_metrics": { + "known_relays": 3, + "mesh_connections": 6, + "sync_requests": 150, + "sync_responses": 150, + "cache_hits": 120, + "cache_misses": 30, + "avg_latency": 45.2, + "error_count": 0 + }, + "system_metrics": { + "memory_usage": "128MB", + "cpu_usage": "5%", + "active_connections": 10, + "total_requests": 1000 + } +} +``` + +#### 3. Configuration +```http +GET /config +``` + +**Réponse :** +```json +{ + "relay_id": "relay-1", + "network": "signet", + "ws_url": "0.0.0.0:8090", + "http_url": "0.0.0.0:8091", + "bitcoin_core": { + "url": "http://bitcoin:18443", + "wallet": "relay_wallet" + }, + "blindbit": { + "url": "http://blindbit:8000" + }, + "sync": { + "interval": 30, + "health_interval": 60 + } +} +``` + +#### 4. Relais Connus +```http +GET /relays +``` + +**Réponse :** +```json +{ + "relays": [ + { + "relay_id": "relay-1", + "address": "sdk_relay_1:8090", + "version": "1.0.0", + "uptime": 3600, + "health": "healthy", + "last_seen": 1703001600 + }, + { + "relay_id": "relay-2", + "address": "sdk_relay_2:8090", + "version": "1.0.0", + "uptime": 3600, + "health": "healthy", + "last_seen": 1703001600 + } + ] +} +``` + +#### 5. Statut de Synchronisation +```http +GET /sync/status +``` + +**Réponse :** +```json +{ + "status": "syncing", + "last_sync": 1703001600, + "next_sync": 1703001630, + "sync_types": [ + "StateSync", + "HealthSync", + "MetricsSync" + ], + "errors": [] +} +``` + +#### 6. Forcer la Synchronisation +```http +POST /sync/force +Content-Type: application/json + +{ + "sync_types": ["StateSync", "HealthSync"] +} +``` + +**Réponse :** +```json +{ + "status": "sync_triggered", + "sync_types": ["StateSync", "HealthSync"], + "timestamp": 1703001600 +} +``` + +#### 7. Logs +```http +GET /logs?level=info&limit=100 +``` + +**Paramètres :** +- `level` : debug, info, warn, error +- `limit` : nombre de lignes (défaut: 100) + +**Réponse :** +```json +{ + "logs": [ + { + "timestamp": "2024-12-19T10:00:00Z", + "level": "info", + "message": "Relay started successfully" + }, + { + "timestamp": "2024-12-19T10:00:30Z", + "level": "info", + "message": "Sync completed" + } + ] +} +``` + +## Codes d'Erreur + +### WebSocket +- `1000` : Fermeture normale +- `1001` : Client part +- `1002` : Erreur de protocole +- `1003` : Type de données non supporté +- `1006` : Connexion fermée anormalement +- `1011` : Erreur serveur + +### HTTP +- `200` : Succès +- `400` : Requête invalide +- `404` : Endpoint non trouvé +- `500` : Erreur serveur interne +- `503` : Service indisponible + +## Exemples d'Utilisation + +### Client JavaScript +```javascript +class SdkRelayClient { + constructor(url) { + this.ws = new WebSocket(url); + this.setupEventHandlers(); + } + + setupEventHandlers() { + this.ws.onopen = () => this.onConnect(); + this.ws.onmessage = (event) => this.onMessage(event); + this.ws.onerror = (error) => this.onError(error); + this.ws.onclose = (event) => this.onClose(event); + } + + onConnect() { + console.log('Connecté à sdk_relay'); + this.sendHandshake(); + } + + sendHandshake() { + const handshake = { + type: 'handshake', + client_id: 'js-client', + version: '1.0.0', + capabilities: ['sync', 'notifications'] + }; + this.ws.send(JSON.stringify(handshake)); + } + + onMessage(event) { + const message = JSON.parse(event.data); + console.log('Message reçu:', message); + } + + onError(error) { + console.error('Erreur WebSocket:', error); + } + + onClose(event) { + console.log('Connexion fermée:', event.code, event.reason); + } +} + +// Utilisation +const client = new SdkRelayClient('ws://localhost:8090'); +``` + +### Client Python +```python +import asyncio +import websockets +import json + +class SdkRelayClient: + def __init__(self, url): + self.url = url + self.websocket = None + + async def connect(self): + self.websocket = await websockets.connect(self.url) + await self.send_handshake() + + async def send_handshake(self): + handshake = { + "type": "handshake", + "client_id": "python-client", + "version": "1.0.0", + "capabilities": ["sync", "notifications"] + } + await self.websocket.send(json.dumps(handshake)) + + async def listen(self): + async for message in self.websocket: + data = json.loads(message) + print(f"Message reçu: {data}") + + async def close(self): + if self.websocket: + await self.websocket.close() + +# Utilisation +async def main(): + client = SdkRelayClient('ws://localhost:8090') + await client.connect() + await client.listen() + +asyncio.run(main()) +``` + +### Client cURL +```bash +# Vérifier la santé +curl http://localhost:8091/health + +# Obtenir les métriques +curl http://localhost:8091/metrics + +# Obtenir la configuration +curl http://localhost:8091/config + +# Forcer la synchronisation +curl -X POST http://localhost:8091/sync/force \ + -H "Content-Type: application/json" \ + -d '{"sync_types": ["StateSync"]}' +``` + +## Limites et Quotas + +### WebSocket +- **Connexions simultanées** : 1000 par défaut +- **Taille des messages** : 1MB maximum +- **Heartbeat** : 30 secondes +- **Timeout de connexion** : 60 secondes + +### HTTP +- **Taux limite** : 1000 requêtes/minute +- **Taille des requêtes** : 10MB maximum +- **Timeout** : 30 secondes +- **Connexions simultanées** : 100 + +## Sécurité + +### Authentification +- **WebSocket** : Authentification optionnelle via handshake +- **HTTP** : Authentification basique (à configurer) + +### Validation +- Validation JSON des messages +- Rate limiting +- Protection contre les attaques DoS + +### Chiffrement +- **WebSocket** : WSS (WebSocket Secure) recommandé +- **HTTP** : HTTPS recommandé + +## Monitoring + +### Métriques Clés +- **Latence** : Temps de réponse des APIs +- **Débit** : Messages par seconde +- **Erreurs** : Taux d'erreur +- **Connexions** : Nombre de connexions actives + +### Alertes +- Service indisponible +- Latence élevée (> 1s) +- Taux d'erreur élevé (> 5%) +- Mémoire/CPU élevés + +--- + +**Cette API permet une intégration complète avec sdk_relay pour les clients WebSocket et HTTP.** 🚀 diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..fb6bb5a --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,332 @@ +# Architecture - sdk_relay + +## Vue d'Ensemble + +`sdk_relay` est un service de relais Rust pour les paiements silencieux Bitcoin, conçu pour fonctionner dans l'écosystème 4NK Node. + +## Architecture Générale + +``` +┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ +│ Client Web │ │ Client HTTP │ │ Client Rust │ +│ (WebSocket) │ │ (REST API) │ │ (Library) │ +└─────────┬───────┘ └─────────┬───────┘ └─────────┬───────┘ + │ │ │ + └──────────────────────┼──────────────────────┘ + │ + ┌─────────────▼─────────────┐ + │ sdk_relay │ + │ ┌─────────────────────┐ │ + │ │ WebSocket Server │ │ + │ │ (tokio-tungstenite)│ │ + │ └─────────────────────┘ │ + │ ┌─────────────────────┐ │ + │ │ HTTP Server │ │ + │ │ (hyper) │ │ + │ └─────────────────────┘ │ + │ ┌─────────────────────┐ │ + │ │ Sync Manager │ │ + │ │ (Mesh Network) │ │ + │ └─────────────────────┘ │ + │ ┌─────────────────────┐ │ + │ │ Bitcoin Core │ │ + │ │ (RPC + ZMQ) │ │ + │ └─────────────────────┘ │ + │ ┌─────────────────────┐ │ + │ │ Blindbit │ │ + │ │ (HTTP API) │ │ + │ └─────────────────────┘ │ + └─────────────────────────────┘ +``` + +## Composants Principaux + +### 1. Serveur WebSocket (`src/websocket.rs`) +- **Technologie** : `tokio-tungstenite` +- **Port** : 8090 (configurable) +- **Fonctionnalités** : + - Handshake WebSocket + - Gestion des connexions multiples + - Messages temps réel + - Heartbeat automatique + +### 2. Serveur HTTP (`src/http.rs`) +- **Technologie** : `hyper` +- **Port** : 8091 (configurable) +- **Fonctionnalités** : + - API REST pour les clients + - Endpoints de santé + - Métriques et statistiques + - Configuration dynamique + +### 3. Gestionnaire de Synchronisation (`src/sync.rs`) +- **Architecture** : Mesh Network +- **Fonctionnalités** : + - Découverte automatique des relais + - Synchronisation périodique + - Cache de déduplication + - Métriques de synchronisation + +### 4. Intégration Bitcoin Core (`src/daemon.rs`) +- **RPC** : `bitcoincore-rpc` +- **ZMQ** : Notifications temps réel +- **Fonctionnalités** : + - Connexion RPC sécurisée + - Écoute des blocs/transactions + - Gestion des wallets + - Scan des paiements silencieux + +### 5. Service Blindbit (`src/blindbit.rs`) +- **Client HTTP** : `reqwest` +- **Fonctionnalités** : + - Récupération des filtres + - Validation des paiements + - Cache des résultats + +## Types de Synchronisation + +### SyncType Enum +```rust +pub enum SyncType { + StateSync, // État général du relais + ProcessSync, // Processus en cours + MemberSync, // Membres du réseau + TxSync, // Transactions + BlockSync, // Blocs + PeerSync, // Pairs connectés + RelaySync, // Informations des relais + HealthSync, // Santé du système + MetricsSync, // Métriques de performance + ConfigSync, // Configuration + CapabilitySync, // Capacités du relais +} +``` + +### Messages de Synchronisation +```rust +pub struct SyncMessage { + pub sync_type: SyncType, + pub relay_id: String, + pub payload: SyncPayload, + pub timestamp: u64, + pub message_id: String, +} + +pub enum SyncPayload { + StateData { state: HashMap }, + ProcessData { processes: Vec }, + MemberData { members: Vec }, + RelayData { relays: Vec }, + HealthData { health: HealthStatus }, + MetricsData { metrics: SyncMetrics }, + // ... autres types +} +``` + +## Cache de Déduplication + +### MessageCache +```rust +pub struct MessageCache { + cache: Arc>>, + ttl: Duration, +} + +pub struct CacheEntry { + pub message: SyncMessage, + pub timestamp: SystemTime, +} +``` + +**Fonctionnalités** : +- Évite les doublons de messages +- TTL configurable +- Nettoyage automatique +- Performance optimisée + +## Configuration + +### Fichier de Configuration (`.conf`) +```toml +# Bitcoin Core +core_url=http://bitcoin:18443 +core_wallet=relay_wallet +zmq_url=tcp://bitcoin:29000 + +# WebSocket +ws_url=0.0.0.0:8090 + +# Blindbit +blindbit_url=http://blindbit:8000 + +# Synchronisation +relay_id=relay-1 +sync_interval=30 +health_interval=60 + +# Réseau +network=signet +dev_mode=true +``` + +### Variables d'Environnement +```bash +RUST_LOG=debug,bitcoincore_rpc=trace +BITCOIN_COOKIE_PATH=/home/bitcoin/.4nk/bitcoin.cookie +ENABLE_SYNC_TEST=1 +``` + +## Flux de Données + +### 1. Initialisation +``` +1. Chargement de la configuration +2. Connexion à Bitcoin Core +3. Connexion à Blindbit +4. Démarrage du serveur WebSocket +5. Démarrage du serveur HTTP +6. Initialisation du SyncManager +7. Découverte des relais +``` + +### 2. Synchronisation Périodique +``` +1. Collecte des données locales +2. Création des messages de sync +3. Envoi aux relais connus +4. Réception des messages +5. Mise à jour du cache +6. Application des changements +7. Mise à jour des métriques +``` + +### 3. Traitement des Paiements +``` +1. Réception notification ZMQ +2. Récupération du bloc/transaction +3. Scan des outputs +4. Vérification avec Blindbit +5. Notification aux clients +6. Synchronisation avec les relais +``` + +## Métriques et Monitoring + +### SyncMetrics +```rust +pub struct SyncMetrics { + pub known_relays: u64, + pub mesh_connections: u64, + pub sync_requests: u64, + pub sync_responses: u64, + pub cache_hits: u64, + pub cache_misses: u64, + pub avg_latency: f64, + pub error_count: u64, +} +``` + +### HealthStatus +```rust +pub enum HealthStatus { + Healthy, + Warning, + Critical, + Unknown, +} +``` + +## Sécurité + +### Authentification +- **Bitcoin Core** : Cookie d'authentification +- **WebSocket** : Authentification optionnelle +- **HTTP** : Authentification basique + +### Validation +- Validation des messages de synchronisation +- Vérification des signatures (futur) +- Rate limiting +- Protection contre les attaques DoS + +## Performance + +### Optimisations +- **Asynchrone** : `tokio` pour la concurrence +- **Cache** : Déduplication des messages +- **Pooling** : Connexions HTTP réutilisées +- **Compression** : Messages compressés (futur) + +### Métriques de Performance +- Latence de synchronisation +- Débit des messages +- Utilisation mémoire +- CPU usage + +## Déploiement + +### Docker +```dockerfile +FROM rust:1.70 as builder +WORKDIR /app +COPY . . +RUN cargo build --release + +FROM debian:bookworm-slim +COPY --from=builder /app/target/release/sdk_relay /usr/local/bin/ +EXPOSE 8090 8091 +CMD ["sdk_relay"] +``` + +### Configuration Docker +```yaml +services: + sdk_relay: + image: 4nk_node_sdk_relay + ports: + - "8090:8090" + - "8091:8091" + volumes: + - ./config:/home/bitcoin/.4nk + environment: + - RUST_LOG=debug +``` + +## Évolution Future + +### Améliorations Planifiées +1. **Chiffrement** : Messages chiffrés end-to-end +2. **Signature** : Messages signés cryptographiquement +3. **Compression** : Compression des messages +4. **Persistance** : Stockage persistant des données +5. **API REST** : Interface REST complète + +### Nouvelles Fonctionnalités +1. **Plugins** : Système de plugins +2. **Webhooks** : Notifications webhook +3. **Analytics** : Tableaux de bord avancés +4. **Multi-réseaux** : Support de plusieurs réseaux Bitcoin + +## Dépannage + +### Problèmes Courants +1. **Connexion Bitcoin Core** : Vérifier le cookie et l'URL +2. **Synchronisation** : Vérifier la connectivité réseau +3. **WebSocket** : Vérifier les ports et le pare-feu +4. **Performance** : Monitorer les métriques + +### Logs Utiles +```bash +# Logs de synchronisation +RUST_LOG=debug,bitcoincore_rpc=trace + +# Logs WebSocket +RUST_LOG=debug,tokio_tungstenite=trace + +# Logs HTTP +RUST_LOG=debug,hyper=trace +``` + +--- + +**Cette architecture garantit un service de relais robuste, performant et évolutif pour l'écosystème 4NK Node.** 🚀 diff --git a/docs/INDEX.md b/docs/INDEX.md index 9b6cac7..f526c91 100644 --- a/docs/INDEX.md +++ b/docs/INDEX.md @@ -1,13 +1,18 @@ # Documentation - sdk_relay ## Guides -- [Architecture](ARCHITECTURE.md) -- [API](API.md) -- [Contribution](../CONTRIBUTING.md) -- [Sécurité](../SECURITY.md) -- [Changelog](../CHANGELOG.md) +- [Architecture](ARCHITECTURE.md) - Architecture technique détaillée +- [API](API.md) - Référence complète des APIs WebSocket et HTTP +- [Contribution](../CONTRIBUTING.md) - Guide de contribution +- [Sécurité](../SECURITY.md) - Politique de sécurité +- [Changelog](../CHANGELOG.md) - Historique des versions ## Tests - Exécuter: `cargo test --all` - Lint: `cargo clippy -- -D warnings` - Format: `cargo fmt -- --check` + +## Développement +- Build: `cargo build --release` +- Run: `cargo run -- --config .conf` +- Docker: `docker build -f Dockerfile .`