mesh/NEXT_STEPS.md

# Prochaines Étapes - Projet Mesh

**Date**: 2026-01-04
**Phase Actuelle**: Agent Rust ✅ COMPLET
**Phase Suivante**: Serveur Python + Tests E2E

---

## 🎉 Où en sommes-nous ?

### Composants Terminés

#### ✅ Agent Rust (100%)
- **WebSocket Client**: Connexion serveur + event routing
- **QUIC Endpoint**: TLS 1.3 + P2P handshake
- **File Transfer**: Chunking 256KB + Blake3 hash
- **Terminal Streaming**: PTY cross-platform
- **CLI**: run, send-file, share-terminal
- **Tests**: 14/14 passants
- **Documentation**: README, E2E_TEST, STATUS

**Binaire**: `agent/target/release/mesh-agent` (4,8 MB)

#### ✅ Infrastructure (100%)
- Docker Compose
- Pre-commit hooks
- VS Code snippets
- Documentation complète

#### 🟡 Serveur Python (~40%)
- Structure projet ✅
- Configuration ✅
- Health check API ✅
- **À faire**: Auth JWT, WebSocket, DB, P2P API

#### 🟡 Client React (~40%)
- Setup Vite + React ✅
- Thème Monokai ✅
- Routing ✅
- **À faire**: Auth UI, WebSocket, Chat, WebRTC

---

## 🎯 Prochaine Priorité: Serveur Python

### Objectif
Implémenter le **Control Plane** (serveur) pour permettre les tests E2E avec l'agent.

### Tâches Critiques

#### 1. Base de Données & Modèles (4h)
**Fichiers à créer**:
- `server/app/models/user.py`
- `server/app/models/room.py`
- `server/app/models/session.py`
- `server/alembic/versions/001_initial.py`

**Actions**:
- Définir modèles SQLAlchemy (User, Room, P2PSession)
- Créer migrations Alembic
- Tester connexion PostgreSQL

**Validation**:
```bash
cd server
poetry run alembic upgrade head
poetry run python -c "from app.models import User; print('OK')"
```

#### 2. Authentification JWT (4h)
**Fichiers à créer**:
- `server/app/auth/jwt.py`
- `server/app/api/auth.py`
- `server/app/schemas/auth.py`

**Actions**:
- Endpoints `/api/auth/register` et `/api/auth/login`
- Génération JWT avec PyJWT
- Password hashing avec bcrypt
- Middleware authentication

**Validation**:
```bash
curl -X POST http://localhost:8000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username":"test","password":"test123"}'

# Doit retourner: {"access_token": "...", "token_type": "bearer"}
```

#### 3. WebSocket Connection Manager (6h)
**Fichiers à créer**:
- `server/app/ws/manager.py`
- `server/app/ws/handlers/system.py`
- `server/app/ws/handlers/room.py`
- `server/app/ws/handlers/p2p.py`

**Actions**:
- ConnectionManager pour tracking clients WebSocket
- Event routing par type (system.*, room.*, p2p.*)
- Handlers pour system.hello, room.join, p2p.session.request
- Broadcast messages aux membres d'une room

**Validation**:
```bash
# Terminal 1
cd server
poetry run uvicorn app.main:app --reload

# Terminal 2 - Test WebSocket
wscat -c "ws://localhost:8000/ws?token=<jwt_token>"
> {"type":"system.hello","device_id":"test-device"}
# Doit retourner: {"type":"system.welcome",...}
```

#### 4. API P2P Session Creation (4h)
**Fichiers à créer**:
- `server/app/api/p2p.py`
- `server/app/schemas/p2p.py`
- `server/app/services/p2p.py`

**Actions**:
- Endpoint `POST /api/p2p/sessions`
- Génération session_token avec TTL (60-180s)
- Stockage session en DB avec expires_at
- Event `p2p.session.created` via WebSocket

**Validation**:
```bash
curl -X POST http://localhost:8000/api/p2p/sessions \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "file",
    "target_device_id": "device-b",
    "ttl": 120
  }'

# Doit retourner:
# {
#   "session_id": "abc123",
#   "session_token": "xyz789",
#   "expires_at": "2026-01-04T23:00:00Z",
#   "endpoints": {
#     "initiator": {"ip": "192.168.1.50", "port": 5000},
#     "target": {"ip": "192.168.1.100", "port": 5000}
#   }
# }
```

---

## 🧪 Tests E2E Agent ↔ Serveur

### Scénario 1: Connexion Agent → Serveur

**Prérequis**:
- Serveur running avec WebSocket
- Agent compilé avec config valide

**Test**:
```bash
# Terminal 1 - Serveur
cd server
poetry run uvicorn app.main:app --host 0.0.0.0 --port 8000

# Terminal 2 - Agent
cd agent
RUST_LOG=info ./target/release/mesh-agent run
```

**Résultat attendu**:
- Agent logs: `WebSocket connected`, `Sent system.hello`
- Serveur logs: `WebSocket client connected`, `Event: system.hello`
- Agent reçoit `system.welcome`

### Scénario 2: P2P Session Creation

**Test**:
```bash
# Terminal 1 - Agent A (daemon)
cd agent
RUST_LOG=info ./target/release/mesh-agent run

# Terminal 2 - Create P2P session (via API ou Web UI)
curl -X POST http://localhost:8000/api/p2p/sessions \
  -H "Authorization: Bearer <jwt>" \
  -d '{"kind":"file","target_device_id":"device-a","ttl":120}'

# Observer Agent A logs
# Attendu: "P2P session created: session_id=..., expires_in=120"
```

### Scénario 3: File Transfer E2E

**Test**:
```bash
# Terminal 1 - Agent A (daemon, récepteur)
RUST_LOG=info ./target/release/mesh-agent run

# Terminal 2 - Agent B (sender)
RUST_LOG=info ./target/release/mesh-agent send-file \
  --session-id "session_from_server" \
  --peer-addr "192.168.1.50:5000" \
  --token "token_from_server" \
  --file test.txt
```

**Résultat attendu**:
- Agent B: `Connecting to peer...`, `P2P connection established`, `File sent successfully!`
- Agent A: `Incoming QUIC connection`, `P2P handshake successful`, `File received`
- Hash Blake3 identique des deux côtés

---

## 📋 Checklist Phase Serveur

### Base de Données
- [ ] Modèles SQLAlchemy (User, Room, P2PSession)
- [ ] Migrations Alembic
- [ ] Connexion PostgreSQL testée
- [ ] CRUD operations (create, read, update, delete)

### Authentification
- [ ] Endpoint `/api/auth/register`
- [ ] Endpoint `/api/auth/login`
- [ ] JWT generation (access_token)
- [ ] Password hashing (bcrypt)
- [ ] Middleware auth pour routes protégées

### WebSocket
- [ ] ConnectionManager (tracking clients)
- [ ] Event routing par type
- [ ] Handler `system.hello` → `system.welcome`
- [ ] Handler `room.join` → `room.joined`
- [ ] Handler `p2p.session.request` → `p2p.session.created`
- [ ] Broadcast messages dans rooms

### API P2P
- [ ] Endpoint `POST /api/p2p/sessions`
- [ ] Génération session_token (JWT ou random)
- [ ] TTL management (expires_at)
- [ ] Event `p2p.session.created` via WebSocket
- [ ] Endpoint info (IP:port des peers)

### Tests
- [ ] Tests unitaires (pytest)
- [ ] Tests integration (DB, WebSocket)
- [ ] Tests E2E (Agent ↔ Serveur)

---

## 📚 Documentation à Consulter

### Pour Serveur Python
1. **[server/CLAUDE.md](server/CLAUDE.md)** - Guidelines serveur
2. **[docs/protocol_events_v_2.md](docs/protocol_events_v_2.md)** - Events WebSocket
3. **[docs/signaling_v_2.md](docs/signaling_v_2.md)** - P2P signaling
4. **[docs/security.md](docs/security.md)** - Modèle sécurité

### Pour Agent (référence)
1. **[agent/README.md](agent/README.md)** - Usage agent
2. **[agent/E2E_TEST.md](agent/E2E_TEST.md)** - Scénarios tests
3. **[docs/AGENT.md](docs/AGENT.md)** - Architecture agent

---

## 🚀 Commandes Utiles

### Serveur
```bash
# Installer dépendances
cd server
poetry install

# Migrations DB
poetry run alembic upgrade head

# Lancer serveur dev
poetry run uvicorn app.main:app --reload

# Tests
poetry run pytest

# Linter
poetry run ruff check .
```

### Agent (rappel)
```bash
# Compiler
cd agent
cargo build --release

# Tests
cargo test

# Lancer daemon
RUST_LOG=info ./target/release/mesh-agent run
```

### Docker Compose (full stack)
```bash
# Démarrer tous les services
docker-compose up -d

# Logs
docker-compose logs -f mesh-server
docker-compose logs -f postgres

# Arrêter
docker-compose down
```

---

## ⚠️ Points d'Attention

### Intégration Agent ↔ Serveur

1. **Event Format**:
   - Serveur et Agent utilisent le même format JSON
   - Champs: `type`, `id`, `timestamp`, `from`, `to`, `payload`
   - Voir `server/app/schemas/events.py` et `agent/src/mesh/types.rs`

2. **Session Token Lifecycle**:
   ```
   Client Web → POST /api/p2p/sessions
      ↓
   Serveur → Génère session_token (TTL 60-180s)
      ↓
   Serveur → Event p2p.session.created via WebSocket
      ↓
   Agent → Cache token localement
      ↓
   Agent → Valide token lors P2P_HELLO
   ```

3. **QUIC Endpoint Discovery**:
   - Agent envoie son QUIC port au serveur (system.hello)
   - Serveur stocke IP:port dans DB
   - API P2P retourne endpoints des 2 peers
   - Agents se connectent directement (P2P)

4. **Firewall/NAT**:
   - Pour MVP: Tests LAN seulement
   - Production: STUN/TURN à implémenter
   - Port UDP QUIC doit être ouvert

---

## 🎯 Objectif Final MVP

**Définition of Done**:
- [ ] 2 utilisateurs peuvent s'authentifier
- [ ] Chat en temps réel fonctionne
- [ ] Appel audio/vidéo WebRTC établi
- [ ] **Fichier transféré via Agent QUIC** ← **VALIDABLE DÈS SERVEUR PRÊT**
- [ ] Terminal partagé en preview
- [ ] Notifications Gotify reçues

**Timeline Estimée**:
- Serveur Python: 2-3 semaines
- Client React: 2-3 semaines
- Tests E2E & Debug: 1 semaine
- **Total MVP**: 5-7 semaines

---

## 📞 Rappel Workflow

1. **Avant de commencer**:
   - Lire CLAUDE.md du composant
   - Choisir tâche dans TODO.md
   - Utiliser `/clear` si changement de contexte

2. **Pendant développement**:
   - Itérations courtes (1-2h max)
   - Headers de traçabilité sur fichiers
   - Commentaires en français
   - Commits fréquents

3. **Après implémentation**:
   - Tester (unit + integration)
   - Mettre à jour DEVELOPMENT.md
   - Mettre à jour TODO.md
   - Documenter dans STATUS.md

---

**Principe Fondamental**:
> **La vérité du projet Mesh est dans les fichiers.** La conversation n'est qu'un outil temporaire.

---

**Dernière mise à jour**: 2026-01-04
**Prochaine action**: Implémenter Serveur Python (Phase 1: Base de Données & Modèles)