4nk/sdk_relay
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Documentation: ajout ARCHITECTURE.md, API.md, SECURITY.md et mise à jour INDEX.md

Browse Source
This commit is contained in:
Nicolas Cantu 2025-08-25 15:07:28 +02:00
parent 26379f4dca
commit b96269fd5d
5 changed files with 870 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
.gitlab-ci.yml
View File

@ -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

62
SECURITY.md Normal file
View File

@ -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é !** 🔒

466
docs/API.md Normal file
View File

@ -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.** 🚀

332
docs/ARCHITECTURE.md Normal file
View File

@ -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<String, String> },
ProcessData { processes: Vec<ProcessInfo> },
MemberData { members: Vec<MemberInfo> },
RelayData { relays: Vec<RelayInfo> },
HealthData { health: HealthStatus },
MetricsData { metrics: SyncMetrics },
// ... autres types
}
```
## Cache de Déduplication
### MessageCache
```rust
pub struct MessageCache {
cache: Arc<Mutex<HashMap<String, CacheEntry>>>,
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.** 🚀

15
docs/INDEX.md
View File

@ -1,13 +1,18 @@
# Documentation - sdk_relay # Documentation - sdk_relay
## Guides ## Guides
- [Architecture](ARCHITECTURE.md) - [Architecture](ARCHITECTURE.md) - Architecture technique détaillée
- [API](API.md) - [API](API.md) - Référence complète des APIs WebSocket et HTTP
- [Contribution](../CONTRIBUTING.md) - [Contribution](../CONTRIBUTING.md) - Guide de contribution
- [Sécurité](../SECURITY.md) - [Sécurité](../SECURITY.md) - Politique de sécurité
- [Changelog](../CHANGELOG.md) - [Changelog](../CHANGELOG.md) - Historique des versions
## Tests ## Tests
- Exécuter: `cargo test --all` - Exécuter: `cargo test --all`
- Lint: `cargo clippy -- -D warnings` - Lint: `cargo clippy -- -D warnings`
- Format: `cargo fmt -- --check` - Format: `cargo fmt -- --check`
## Développement
- Build: `cargo build --release`
- Run: `cargo run -- --config .conf`
- Docker: `docker build -f Dockerfile .`