Primo commit - Prompt 02 — WebSocket endpoints /agent e /client + parsing robusto

CODEX_INIT.txt

@@ -0,0 +1,255 @@
+1. Contesto del progetto (READ FIRST)
+
+Stiamo costruendo un sistema di controllo remoto composto da:
+
+Windows Client (Electron)
+        ⇅ WebSocket (control-plane)
+VPS Signaling Server (Node.js / TS)
+        ⇅ WebSocket
+Android Tablet Agent (Kotlin)
+
+
+⚠️ IMPORTANTE
+
+Il VPS NON trasporta video/audio/input.
+
+Il VPS serve SOLO per:
+
+autenticazione
+
+signaling
+
+presence (online/offline)
+
+autorizzazione connessioni
+
+In fasi successive, il traffico media passerà via WebRTC P2P/TURN (NON in Fase 1).
+
+2. Stack tecnologico (decisioni definitive)
+Linguaggi
+
+TypeScript ovunque possibile
+
+server: Node.js + TypeScript
+
+windows: Electron + TypeScript
+
+shared: TypeScript
+
+Android: Kotlin (fuori scope TS)
+
+Scelte chiave (NON cambiare senza chiedere)
+
+Client Windows: Electron
+
+Protocollo: WebSocket + JSON tipizzato
+
+Condivisione tipi: pacchetto shared/protocol
+
+Stato: in-memory per Fase 1 (DB arriverà dopo)
+
+Auth Fase 1: seed user + pairingKey (MVP)
+
+3. Modalità operativa tablet (definitiva)
+
+Tablet Android:
+
+sempre in ascolto
+
+ForegroundService sempre attivo
+
+MediaProjection verrà avviata in Fase 2
+
+Connessioni in ingresso:
+
+SEMPRE con accettazione manuale
+
+notifica Android con “Accetta / Rifiuta”
+
+⚠️ Non implementare:
+
+auto-accept
+
+connessioni silenziose
+
+bypass dei permessi Android
+
+4. Fase attuale del progetto
+✅ Fase 1 — Control-plane ONLY
+
+In questa fase:
+
+❌ NIENTE WebRTC
+
+❌ NIENTE MediaProjection
+
+❌ NIENTE streaming
+
+❌ NIENTE input remoto
+
+✔️ SOLO:
+
+WebSocket server
+
+login client
+
+register agent
+
+device list
+
+connect_request
+
+accept / deny / expired
+
+Se una PR introduce WebRTC o video → È SBAGLIATA
+
+5. Protocollo di comunicazione
+
+Tutti i messaggi:
+
+{
+  "v": 1,
+  "type": "...",
+  "requestId": "...",
+  "...": "..."
+}
+
+
+I tipi sono definiti in:
+
+/shared/protocol
+
+
+⚠️ Regole:
+
+Non inventare campi fuori dai tipi condivisi
+
+Non usare stringhe “magiche”
+
+Se serve un nuovo messaggio → aggiornare shared/protocol
+
+6. Regole di sviluppo per Codex
+Come lavorare
+
+Ogni task = UNA PR
+
+PR piccole, focalizzate
+
+Niente “mega commit”
+
+Ogni PR DEVE includere:
+
+Codice funzionante
+
+Logging minimo (no spam)
+
+Error handling (no crash)
+
+Checklist “come testare manualmente”
+
+NON fare:
+
+refactor non richiesti
+
+miglioramenti “creativi”
+
+cambiare stack
+
+anticipare fasi future
+
+7. Stato & persistenza (Fase 1)
+
+Tutto in memoria
+
+Restart server = stato perso (OK per MVP)
+
+Nessun database obbligatorio ora
+
+Strutture tipiche:
+
+devicesById
+
+sessionsById
+
+clientSessionsByWs
+
+8. Sicurezza (livello attuale)
+
+Fase 1 = MVP controllato
+
+Seed user + password in env
+
+PairingKey in env
+
+TLS solo in VPS (non locale)
+
+⚠️ Non implementare:
+
+hashing avanzato
+
+JWT
+
+refresh token
+
+OAuth
+
+Arriveranno in Fase 3.
+
+9. Error handling (obbligatorio)
+
+Su errore:
+
+{
+  "v": 1,
+  "type": "error",
+  "requestId": "...",
+  "code": "UNAUTHORIZED | BAD_REQUEST | NOT_FOUND | CONFLICT | DEVICE_OFFLINE",
+  "message": "human readable"
+}
+
+
+Mai crashare il server
+
+Mai lasciare una promise non gestita
+
+10. Naming e stile
+
+camelCase per JSON
+
+kebab-case per file
+
+TypeScript strict
+
+No any salvo motivazione
+
+11. Test mindset
+
+Ogni feature deve essere:
+
+testabile via CLI o WS
+
+osservabile via log
+
+verificabile senza UI (se possibile)
+
+Se non è testabile → probabilmente è sbagliata.
+
+12. Frase guida del progetto
+
+“Il VPS coordina, non guarda.
+Il tablet decide, non subisce.
+Il client controlla, non buca.”
+
+13. In caso di dubbio
+
+Se una decisione:
+
+tocca sicurezza
+
+cambia protocollo
+
+anticipa WebRTC
+
+rompe compatibilità
+
+👉 FERMATI e chiedi prima.