mesh/server/CLAUDE.md

CLAUDE.md — Mesh Server

This file provides server-specific guidance for the Mesh control plane implementation.

Server Role

The Mesh Server is the control plane only. It:

• Authenticates users and agents
• Manages rooms and ACL
• Issues capability tokens (60-180s TTL)
• Provides WebRTC signaling
• Orchestrates P2P sessions (QUIC)
• Sends Gotify notifications

The server NEVER transports media or heavy data. This is a fundamental architectural constraint.

Technology Stack

• Python 3.12+ (IMPORTANT: Utiliser python3 pour les commandes, pas python)
• FastAPI for REST API
• WebSocket for real-time events
• JWT for authentication
• SQLAlchemy for database (SQLite initially, PostgreSQL for production)
• httpx for Gotify integration
• Docker recommandé pour éviter les problèmes de compatibilité de versions

Project Structure

server/
├── src/
│   ├── main.py              # FastAPI app entry point
│   ├── config.py            # Configuration management
│   ├── auth/
│   │   ├── jwt.py           # JWT token management
│   │   ├── capabilities.py  # Capability token generation
│   │   └── models.py        # Auth data models
│   ├── rooms/
│   │   ├── manager.py       # Room management
│   │   ├── acl.py           # Access control lists
│   │   └── models.py        # Room data models
│   ├── websocket/
│   │   ├── connection.py    # WebSocket connection manager
│   │   ├── events.py        # Event handlers
│   │   └── router.py        # WebSocket routing
│   ├── signaling/
│   │   ├── webrtc.py        # WebRTC signaling
│   │   └── p2p.py           # QUIC P2P session orchestration
│   ├── notifications/
│   │   └── gotify.py        # Gotify client
│   └── db/
│       ├── models.py        # Database models
│       └── session.py       # Database session management
├── tests/
├── requirements.txt
├── Dockerfile
└── CLAUDE.md

Development Commands

Setup Local (avec virtualenv)

cd server
python3 -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows
pip install -r requirements.txt
cp .env.example .env
# Éditer .env avec votre configuration

Setup avec Docker (Recommandé)

cd server
cp .env.example .env
# Éditer .env avec votre configuration

# Construire l'image
docker build -t mesh-server:dev .

# Lancer le serveur
docker run -d --name mesh-server -p 8000:8000 --env-file .env mesh-server:dev

# Voir les logs
docker logs mesh-server -f

# Arrêter et supprimer
docker rm -f mesh-server

Run Development Server (Local)

python3 -m uvicorn src.main:app --reload --host 0.0.0.0 --port 8000

Run Tests

# Tester l'API (avec le serveur lancé)
python3 test_api.py

# Tests unitaires
pytest tests/

Type Checking

mypy src/

Event Protocol

All WebSocket events follow this structure (see protocol_events_v_2.md):

{
  "type": "event.type",
  "id": "uuid",
  "timestamp": "ISO-8601",
  "from": "peer_id|device_id|server",
  "to": "peer_id|device_id|room_id|server",
  "payload": {}
}

Capability Tokens

Capability tokens are short-lived JWTs (60-180s) that authorize specific P2P actions:

{
  "sub": "peer_id or device_id",
  "room_id": "room_id",
  "caps": ["call", "screen", "share:file", "terminal:view"],
  "exp": timestamp,
  "target_peer_id": "optional",
  "max_size": "optional",
  "max_rate": "optional"
}

Critical rules:

• Never accept WebRTC offers without valid capability tokens
• Never create P2P sessions without valid capability tokens
• Validate token expiration on every use
• Terminal control requires explicit terminal:control capability

Security Checklist

• All WebSocket connections authenticated with JWT
• Capability tokens have short TTL (60-180s)
• Room ACL enforced server-side
• No sensitive data in logs
• TURN credentials are temporary (when implemented)
• Rate limiting on auth endpoints
• Input validation on all endpoints

Database Schema

Key entities:

• User: user_id, username, hashed_password, created_at
• Device: device_id, user_id, name, last_seen
• Room: room_id, name, owner_user_id, created_at
• RoomMember: room_id, user_id, role (owner/member/guest)
• Session: session_id, peer_id, device_id, room_id, expires_at

WebSocket Events to Implement

System

• system.hello (client → server)
• system.welcome (server → client)

Rooms

• room.join, room.joined
• room.leave, room.left
• presence.update

Chat

• chat.message.send, chat.message.created

WebRTC Signaling

• rtc.offer, rtc.answer, rtc.ice

P2P Sessions (QUIC)

• p2p.session.request, p2p.session.created
• p2p.session.closed

Terminal Control

• terminal.control.take, terminal.control.granted
• terminal.control.release

Gotify Integration

Send notifications for:

• New chat messages (when user offline)
• Missed calls
• Share completed
• Terminal share started
• Agent offline

Never include secrets in notification text.

Error Handling

Return structured errors:

{
  "type": "error",
  "code": "CAP_EXPIRED",
  "message": "Capability token expired"
}

Error codes:

• CAP_REQUIRED: Missing capability token
• CAP_EXPIRED: Token expired
• CAP_INVALID: Token invalid or tampered
• ROOM_NOT_FOUND: Room doesn't exist
• ACCESS_DENIED: User not in room or insufficient permissions
• P2P_SESSION_DENIED: P2P session creation failed
• UNROUTABLE: Peer not connected

Testing Strategy

1. Unit tests: Individual functions (JWT, capabilities, validation)
2. Integration tests: WebSocket event flows
3. E2E tests: Complete user journeys (join room, send message, start call)

Notes sur Python et Dépendances

Python 3.13 Compatibility

⚠️ Important: Les dépendances actuelles (pydantic==2.5.3 avec pydantic-core==2.14.6) ne sont pas compatibles avec Python 3.13.

Solutions:

1. Docker (Recommandé): Utiliser l'image Docker qui utilise Python 3.12
2. Mise à jour: Upgrader vers pydantic>=2.10 pour Python 3.13 (nécessite tests de régression)
3. Downgrade: Installer Python 3.12 localement

Dépendances Importantes

• pydantic[email]==2.5.3 - Inclut email-validator pour la validation des emails
• passlib[bcrypt]==1.7.4 + bcrypt==4.1.2 - Hash des mots de passe
• python-jose[cryptography]==3.3.0 + pyjwt[crypto]==2.8.0 - JWT tokens
• sqlalchemy==2.0.25 + alembic==1.13.1 - ORM et migrations

Commandes Python

Toujours utiliser python3 explicitement sur les systèmes Unix/Linux:

python3 -m pip install -r requirements.txt
python3 -m uvicorn src.main:app --reload
python3 test_api.py

Performance Considerations

• Keep WebSocket connections lightweight
• Use connection pooling for database
• Cache room membership lookups
• Implement backpressure for high-frequency events
• Monitor active connections count

---

Remember: The server is control plane only. Any attempt to route media or large data through the server violates the architecture.