Architettura — Comunicazione a doppio piano

OxideTerm separa i dati del terminale dai comandi di controllo in due piani indipendenti:

┌─────────────────────────────────────┐
│        Frontend (React 19)          │
│  xterm.js 6 (WebGL) + 19 stores     │
└──────────┬──────────────┬───────────┘
           │ Tauri IPC    │ WebSocket (binario)
           │ (JSON)       │ porta per sessione
┌──────────▼──────────────▼───────────┐
│         Backend (Rust)              │
│  NodeRouter → SshConnectionRegistry │
│  Wire Protocol v1                   │
│  [Type:1][Length:4][Payload:n]      │
└─────────────────────────────────────┘

• Piano dati (WebSocket): ogni sessione SSH ottiene la propria porta WebSocket. I byte del terminale fluiscono come frame binari con header Type-Length-Payload — nessuna serializzazione JSON, nessuna codifica Base64, zero overhead nel percorso critico.
• Piano di controllo (Tauri IPC): gestione connessioni, operazioni SFTP, inoltri, configurazione — JSON strutturato, ma fuori dal percorso critico.
• Indirizzamento per nodo: il frontend non tocca mai sessionId né connectionId. Tutto viene indirizzato tramite nodeId, risolto atomicamente lato server dal NodeRouter. La riconnessione SSH modifica il connectionId sottostante — ma SFTP, IDE e inoltri non sono minimamente coinvolti.

🔩 SSH puro in Rust — russh 0.59

L'intero stack SSH è russh 0.59 compilato con il backend crittografico ring:

• Zero dipendenze C/OpenSSL — l'intero stack crittografico è in Rust. Niente più debug «quale versione di OpenSSL?».
• Protocollo SSH2 completo: scambio chiavi, canali, sottosistema SFTP, port forwarding
• Suite crittografiche ChaCha20-Poly1305 e AES-GCM, chiavi Ed25519/RSA/ECDSA
• AgentSigner personalizzato: avvolge il SSH Agent di sistema e implementa il trait Signer di russh, risolvendo problemi di bound Send RPITIT clonando &AgentIdentity in un valore posseduto prima di attraversare .await

pub struct AgentSigner { /* wraps system SSH Agent */ }
impl Signer for AgentSigner { /* challenge-response via Agent IPC */ }

• Supporto piattaforma: Unix (SSH_AUTH_SOCK), Windows (\\.\pipe\openssh-ssh-agent)
• Catene proxy: ogni salto utilizza l'autenticazione Agent in modo indipendente
• Riconnessione: AuthMethod::Agent riprodotto automaticamente

🔄 Riconnessione intelligente con periodo di grazia

La maggior parte dei client SSH distrugge tutto alla disconnessione e riparte da zero. L'orchestratore di riconnessione di OxideTerm adotta un approccio fondamentalmente diverso:

1. Rilevamento del timeout heartbeat WebSocket (300 s, calibrato per macOS App Nap e throttling dei timer JS)
2. Snapshot dello stato completo: pannelli terminale, trasferimenti SFTP in corso, port forward attivi, file IDE aperti
3. Sondaggio intelligente: eventi visibilitychange + online attivano keepalive SSH proattivo (~2 s di rilevamento contro 15–30 s di timeout passivo)
4. Periodo di grazia (30 s): sonda la vecchia connessione SSH via keepalive — se si ripristina (es.: cambio di access point WiFi), le tue app TUI (vim, htop, yazi) sopravvivono completamente intatte
5. Se il recupero fallisce → nuova connessione SSH → ripristino automatico degli inoltri → ripresa dei trasferimenti SFTP → riapertura dei file IDE

Pipeline: queued → snapshot → grace-period → ssh-connect → await-terminal → restore-forwards → resume-transfers → restore-ide → verify → done

Tutta la logica passa attraverso un ReconnectOrchestratorStore dedicato — zero codice di riconnessione sparso in hook o componenti.

🛡️ Pool di connessioni SSH

SshConnectionRegistry con conteggio dei riferimenti supportato da DashMap per accesso concorrente senza lock:

• Una connessione, molti consumatori: terminale, SFTP, port forward e IDE condividono una singola connessione SSH fisica — nessun handshake TCP ridondante
• Macchina a stati per connessione: connecting → active → idle → link_down → reconnecting
• Gestione del ciclo di vita: timeout di inattività configurabile (5 min / 15 min / 30 min / 1 h / mai), intervallo keepalive di 15 s, rilevamento guasti heartbeat
• Heartbeat WsBridge: intervallo di 30 s, timeout di 5 min — tollera macOS App Nap e throttling JS del browser
• Propagazione a cascata: guasto dell'host di salto → tutti i nodi a valle automaticamente marcati come link_down con sincronizzazione dello stato
• Disconnessione per inattività: emette connection_status_changed al frontend (non solo node:state interno), prevenendo desincronizzazione dell'interfaccia

🤖 OxideSens AI

Assistente IA incentrato sulla privacy con due modalità di interazione:

• Pannello inline (⌘I): comandi terminale rapidi, output iniettato tramite bracketed paste
• Chat laterale: conversazioni persistenti con cronologia completa
• Contesto workspace orientato ai target: vede connessioni salvate, sessioni SSH live, buffer del terminale, percorsi SFTP, impostazioni e voci della knowledge base come target del workspace
• Azioni approvate: può diagnosticare output remoto, eseguire comandi approvati, ispezionare file e spiegare guasti senza richiedere un account OxideTerm
• Supporto MCP: connessione a server Model Context Protocol esterni (stdio e SSE) per integrazione di strumenti di terze parti
• Knowledge base RAG (v0.20): importa documenti Markdown/TXT in collezioni con scope (globale o per connessione). La ricerca ibrida fonde indice di keyword BM25 + similarità coseno vettoriale tramite Reciprocal Rank Fusion. Chunking consapevole del Markdown che preserva la gerarchia dei titoli. Tokenizer a bigrammi CJK per cinese/giapponese/coreano.
• Provider: OpenAI, Ollama, DeepSeek, OneAPI, o qualsiasi endpoint /v1/chat/completions
• Sicurezza: chiavi API conservate nel portachiavi OS; su macOS, la lettura delle chiavi è protetta da Touch ID tramite LAContext — nessun entitlement o firma del codice richiesti, in cache dopo la prima autenticazione per sessione

Port Forwarding — I/O senza lock

Inoltro locale (-L), remoto (-R) e SOCKS5 dinamico (-D) completo:

• Architettura message-passing: il canale SSH è posseduto da un singolo task ssh_io — nessun Arc<Mutex<Channel>>, eliminando completamente la contesa mutex
• Report di terminazione: i task di inoltro segnalano attivamente il motivo di uscita (disconnessione SSH, chiusura porta remota, timeout) per diagnostica chiara
• Ripristino automatico: gli inoltri Suspended riprendono automaticamente alla riconnessione senza intervento dell'utente
• Timeout di inattività: FORWARD_IDLE_TIMEOUT (300 s) previene l'accumulo di connessioni zombie

📦 trzsz — Trasferimento File Integrato

Carica e scarica file direttamente attraverso la sessione SSH — senza connessione SFTP:

• Protocollo integrato: i file viaggiano come frame Base64 all'interno del flusso terminale esistente — funziona in modo trasparente attraverso catene ProxyJump e tmux senza porte o agenti aggiuntivi
• Bidirezionale: il server esegue tsz <file> per inviare file al client; trz avvia il caricamento lato client; supporto drag-and-drop
• Supporto directory: trasferimenti ricorsivi tramite trz -d / tsz -d
• Limiti di trasferimento: limiti configurabili per sessione per dimensione del blocco, numero di file e byte totali
• I/O nativo Tauri: lettura e scrittura di file tramite dialoghi nativi Tauri e Rust I/O — nessun vincolo di memoria del browser
• Notifiche in tempo reale: notifiche Toast per avvio, completamento, annullamento ed errori — incluso un suggerimento quando viene rilevato trzsz ma la funzione è disabilitata
• Attivare in Impostazioni → Terminale → Trasferimento Integrato

🔌 Sistema di plugin runtime

Caricamento ESM dinamico con superficie API congelata e rinforzata in sicurezza:

• API PluginContext: 18 namespace — terminal, ui, commands, settings, lifecycle, events, storage, system
• 24 componenti UI Kit: componenti React precostruiti (pulsanti, campi di input, dialoghi, tabelle…) iniettati nelle sandbox dei plugin tramite window.__OXIDE__
• Membrana di sicurezza: Object.freeze su tutti gli oggetti di contesto, ACL basata su Proxy, whitelist IPC, circuit breaker con disattivazione automatica dopo errori ripetuti
• Moduli condivisi: React, ReactDOM, zustand, lucide-react esposti per l'uso dei plugin senza duplicazione dei bundle

⚡ Rendering adattivo

Scheduler di rendering a tre livelli che sostituisce il batching fisso di requestAnimationFrame:

Le transizioni sono completamente automatiche — guidate dal volume dei dati, dall'input utente e dall'API Page Visibility. I tab in background continuano a svuotare i dati tramite timer di inattività senza svegliare RAF.

🔐 Export crittografato .oxide

Backup di connessione portatile e a prova di manomissione:

• Crittografia autenticata ChaCha20-Poly1305 AEAD
• KDF Argon2id: costo memoria di 256 MB, 4 iterazioni — resistente al brute-force GPU
• Checksum di integrità SHA-256
• Embedding opzionale delle chiavi: chiavi private codificate in base64 nel payload crittografato
• Analisi preliminare: breakdown dei tipi di autenticazione, rilevamento chiavi mancanti prima dell'export

📡 ProxyJump — Multi-hop con consapevolezza topologica

• Profondità della catena illimitata: Client → Salto A → Salto B → … → Destinazione
• Parsing automatico di ~/.ssh/config, costruzione del grafo topologico, pathfinding Dijkstra per la rotta ottimale
• Nodi di salto riutilizzabili come sessioni indipendenti
• Propagazione di guasti a cascata: host di salto down → tutti i nodi a valle automaticamente marcati come link_down

⚙️ Terminale locale — PTY thread-safe

Shell locale multipiattaforma tramite portable-pty 0.8, protetto dal feature gate local-terminal:

• MasterPty avvolto in std::sync::Mutex — thread I/O dedicati mantengono le letture PTY bloccanti fuori dall'event loop di Tokio
• Rilevamento automatico della shell: zsh, bash, fish, pwsh, Git Bash, WSL2
• cargo build --no-default-features rimuove PTY per build mobile/leggeri

🪟 Ottimizzazione Windows

• ConPTY nativo: invoca direttamente l'API Windows Pseudo Console — supporto completo TrueColor e ANSI, nessun WinPTY legacy
• Scanner shell: rileva automaticamente PowerShell 7, Git Bash, WSL2, CMD tramite Registro e PATH

E altro ancora

• Modalità IDE: CodeMirror 6 via SFTP, 24 linguaggi, albero file con stato Git, multi-scheda, risoluzione conflitti — agente remoto opzionale (~1 MB) per funzionalità avanzate su Linux
• Profiler risorse: CPU/memoria/rete in tempo reale tramite canale SSH persistente che legge /proc/stat, calcolo basato su delta, degradazione automatica a solo RTT su sistemi non-Linux
• Motore temi personalizzato: 30+ temi integrati, editor visuale con anteprima live, 20 campi xterm.js + 24 variabili colore UI, derivazione automatica dei colori UI dalla palette del terminale
• Registrazione sessioni: formato asciicast v2, registrazione e riproduzione complete
• Broadcast input: digita una volta, invia a tutti i pannelli divisi — operazioni batch sui server
• Galleria sfondi: immagini di sfondo per tab, 16 tipi di tab, controllo opacità/sfocatura/adattamento
• Companion CLI (oxt): binario di ~1 MB, JSON-RPC 2.0 tramite Unix Socket / Named Pipe, status/health/list/forward/config/connect/focus/attach/SFTP/import/AI con output leggibile o --json
• WSL Graphics ⚠️ sperimentale: visualizzatore VNC integrato — 9 ambienti desktop + modalità singola applicazione, rilevamento WSLg, Xtigervnc + noVNC