CODLAB / Blog · Software e sviluppo

Come CardinalHost comunica con il Mac: client nativo macOS, agente di supporto e ricerca in corso su compressione e trasferimento dati

15 nov 2026 CODLAB Team 10 min

Aggiornato a novembre 2026: Nell’architettura di CardinalHost (documentata in pre-lancio su cardinalhost.org), il Mac — dalle postazioni desktop al MacBook — svolge due ruoli distinti: client nativo in Swift e SwiftUI (ServerMountApp) per amministrare macchine Linux e macOS remote, e nodo assistito governato dall’agente macOS (pubblico-macos.sh). Documentiamo qui sia la comunicazione macOS già consolidata nel codice, inclusa la macchina a 3 stati TCC, sia la ricerca in corso su compressione lossless a tasselli (Tela e zstd), pacing dei pacchetti su tratte radio schedulate e trasferimento dati tra Mac e server.

Due ruoli sul Mac: client operatore e macchina assistita

Nella Famiglia Cardinal — accanto a CardinalMail e CardinalOS — CardinalHost usa direttamente le API native di sicurezza e cattura multimediale del sistema anziché incorporare un browser runtime. Come riassunto nella panoramica di ricerca CardinalHost, la comunicazione macOS si articola su tre livelli:

  • Client operatore (ServerMountApp): Su MacBook o Mac fisso, l’app Swift/SwiftUI gestisce host remoti via SSH e SFTP, salva le credenziali nel Keychain, usa CryptoKit e governa i tunnel con SSHTunnelManager e il modello puro SpecInoltro per inoltri locali (-L), remoti (-R) e SOCKS dinamici (-D).
  • Sistema assistito (pubblico-macos.sh): Quando un Mac remoto condivide schermo, audio, appunti o file durante il supporto, uno script unificato regola la sessione. Nella matrice dichiarativa (capacita.json), macos espone tutte le 11 capacità: terminale, file, file-sessione, stream, controllo, chat, stampa, appunti, registrazione, salute e audio (audio di sistema da macOS 13 tramite ScreenCaptureKit).
  • Diagnosi senza agente via SSH (ParserSaluteMacOS): Anche senza agente Cardinal installato, il client legge via SSH lo stato essenziale del Mac remoto senza inventare stime arbitrarie.

Questo livello completa gli altri articoli della serie: Wayland nativo su Linux e trasporto video, cancello comandi e diagnosi IA BYOK con consenso, e contratti di protocollo e sincronizzazione cifrata.

Confini di sessione, macchina a stati TCC e telemetria macOS onesta

Sul campo, il supporto remoto su macOS raramente si blocca sul socket di rete; le criticità nascono sulla scadenza delle credenziali temporanee e sul modello Transparency, Consent, and Control (TCC) di Apple, entrambi modellati in modo deterministico.

Agente chiuso di default e sessioni a scadenza

Lo script pubblico-macos.sh lascia l’accesso remoto chiuso per impostazione predefinita dopo l’installazione. Solo quando chi usa il Mac avvia --sessione viene emessa una credenziale temporanea valida 30 minuti per impostazione predefinita (selezionabile con --durata anche a due ore oppure aperta fino alla chiusura manuale); la modalità con credenziale fissa richiede il passaggio esplicito a --permanente (mentre il consenso per connessione resta un’impostazione separata), e --blocca revoca subito ogni accesso attivo o pianificato.

Su macOS l’agente usa dscl, nasconde l’account dedicato (IsHidden 1) e passa le credenziali via standard input affinché nessun segreto compaia in argv. Per le sessioni a tempo, un job periodico launchd controlla ogni 5 secondi se la finestra configurata è scaduta, chiudendo automaticamente il canale alla scadenza (mentre nella modalità aperta fino a chiusura manuale non viene armato alcun timer di scadenza). Inoltre --json espone lo stato in sola lettura senza privilegi elevati e i file di salute sono scritti in modalità 0600 con rinomina atomica. Non pubblichiamo mai dettagli sfruttabili del recinto come utenti dedicati, porte del tunnel o percorsi interni.

Perché PermessiMacOS modella lo schermo nero TCC in 3 stati

Attivando la condivisione schermo su un Mac emerge una nota trappola TCC: concedendo Registrazione schermo (CGPreflightScreenCaptureAccess con ScreenCaptureKit) mentre il processo è già attivo, il preflight risponde positivamente ma il processo cattura nero finché l’app non riparte. Accessibilità (AXIsProcessTrusted per tastiera e mouse) è invece immediata.

Per evitare attese cieche davanti a uno schermo nero, PermessiMacOS.swift codifica questa regola come macchina a stati pura (ProceduraPermessi). Per ogni voce di PermessoMac, StatoPermesso distingue 3 stati: mancante, concessoInAttesaDiRiavvio (concesso a processo vivo ma con riavvio richiesto perché richiedeRiavvioDopoConcessione vale per la registrazione schermo) e pronto; nello stato mancante il modello punta ai pannelli Privacy_ScreenCapture o Privacy_Accessibility, mentre concessoInAttesaDiRiavvio richiede il riavvio dell’app. Le transizioni pure sono coperte da test unitari, mentre la finestra passo-passo nell’app non è ancora costruita e il dialogo reale di sistema resta destinato al collaudo su Mac fisico.

ParserSaluteMacOS: nil invece di RAM inventata

Su SSH standard senza agente, ParserSaluteMacOS.swift valuta sw_vers, df -P /, sysctl -n kern.boottime e uptime come funzione pura parametrizzata sull’orario corrente. In kern.boottime accetta sec solo come parola isolata, escludendo sottostringhe come usec o sector. Il campo ramUsataPercento resta volutamente nil anziché 0: poiché su macOS manca via SSH un equivalente stabile del MemAvailable di Linux e vm_stat mescola pagine compresse e svuotabili, una percentuale stimata sarebbe ingannevole.

Ricerca in corso sulla compressione video e dati tra Mac e server

Lavorando da un MacBook Retina verso un server remoto emerge il limite dei codec video classici: H.264 hardware in 4:2:0 gestisce il movimento ma sfuma caratteri del terminale ed editor. La nostra ricerca in corso esplora quindi il livello ibrido Tela, presentato come ricerca aperta e mai come funzione conclusa.

Tasselli lossless 16×16 con prefisso zstd contro i residui video

La prima domanda di ricerca (2026-10-22-tela-esatta) su base video hardware HEVC confrontava l’invio quasi lossless del residuo (errore massimo 1 tra pixel sorgente e quadro HEVC decodificato) con la compressione lossless diretta dei tasselli di testo cambiati. Le prove hanno smentito l’approccio residuale: il rumore di quantizzazione sui bordi dei caratteri alza l’entropia e sul testo ha richiesto da 3 a 8 volte più byte rispetto alla codifica lossless diretta dei tasselli originali.

Su questa base Tela.swift suddivide la vista in tasselli da 16×16 pixel (lato massimo 8.192 pixel, finestra logaritmica 27), integra un decoder zstd 1.5.7 a file singolo senza assembly (-DZSTD_DISABLE_ASM) più zlib e usa la tela cliente come dizionario prefisso. Per le fasce contigue negozia record streaming FLUSSO (tipo 4) verificati con CRC-32, azzerando lo stato in modo fail-closed con tela reset su qualsiasi errore.

Dizionario di glifi e risultati negativi nella ricerca in corso

Il filone razzo-149 studia un dizionario di glifi cifrato a riposo e persistito tra sessioni (tela glifi 1, tipo 5) che sceglie per record tra glifi e zstd, controlla CRC-32 e cifra la cache locale con ChaCha20-Poly1305 e HKDF (cancellando le chiavi alla revoca host). Due misure di laboratorio guidano le scelte attuali:

  1. Singole battiture senza prefisso: Su 12 battiture misurate, i piccoli delta XOR senza prefisso da 160 righe occupano 43–53 byte contro una mediana di 197 byte con prefisso.
  2. Limite sui cambi scena a pieno schermo: Nel prototipo Python/NumPy la scomposizione in glifi 1440p al cambio scena richiede 150–200 ms CPU contro 37 ms di zstd (mentre la decodifica Swift -O in VM misura 19,0 ms mediani); la soppressione video sui cambi scena resta quindi disattivata di default in attesa di un encoder nativo.

Specchio storico verificato al pixel e limiti aperti

Alternando finestre o schede già viste sul MacBook, grandi aree tornano identiche dopo secondi o minuti. Il ramo razzo-150 valuta uno specchio effimero solo in RAM cifrato per sessione (zlib più ChaCha20-Poly1305) con comandi SALVA (22 byte) e COPIA su hash a 64 bit. Per verificare l’integrità dello slot memorizzato, il ricevitore ricalcola CRC-32 sui pixel decifrati dello slot: corruzione di memoria, manomissione o uno slot di un’epoca superata scartano lo slot e attivano tela reset (mentre la selezione dei tasselli copiati segue gli hash dei tasselli, quindi il checksum dello slot non protegge da una collisione dell’hash).

In 20 corse ABBA a 1440p e 20 Mbit/s sul client di riferimento (bassa contesa CPU PSI entro 3,49 %), la banda a regime è scesa dai 4,828 Mbit/s della versione precedente a 0,902 Mbit/s con ritorno mediano in 31–32 ms e 0 tasselli corrotti. Restano però tre limiti aperti: il client macOS produttivo non richiede ancora l’estensione; in 4K a 20 Mbit/s il p95 in movimento sale da 81 ms a 153–161 ms per l’accodamento di fotogrammi esatti grandi; la contesa multi-thread allunga le code.

Ricerca in corso su pacing dei pacchetti e trasferimento file tra MacBook e server

Parallelamente studiamo la stima di capacità su tratte radio e il trasferimento verificabile dei file tra Mac e server.

Perché le coppie brevi ingannano sul Wi-Fi (SCM_TIMESTAMP_MONOTONIC)

Su un MacBook collegato spesso via Wi-Fi o su tratte schedulate lo scheduler radio aggrega i frame imponendo pause. Nello studio tra server Linux e client macOS (2026-10-23-sonda-capacita-ciclo-accesso), 40 treni UDP reali per 540 su 540 datagrammi ricevuti da 1.202 byte marcati via SCM_TIMESTAMP_MONOTONIC hanno mostrato pause radio in tutti i 40 casi: 5,5 µs mediani nel burst contro 2,38 ms di pausa mediana.

Sonde brevi da 6 o 16 pacchetti leggono quindi le pause radio o il picco del burst anziché il collo di bottiglia (54,2 Mbit/s sul percorso provato); il nostro pacing non dichiara mai una velocità superiore a quella consegnata da unità di accesso lunghe.

Trasferimento file multi-percorso: sessione, rsync e servizio file SFTPService su ControlMaster

Per muovere dati tra Mac e server affianchiamo basi operative e ricerca attiva:

  • File di sessione (file-sessione): In pubblico-macos.sh, file-ricevi verifica dimensione e SHA-256 esadecimale da 64 caratteri (normalizzato internamente in minuscolo) prima di salvare in Download; file-scegli invia solo il singolo file scelto dall’assistito.
  • Coda rsync riprendibile (TransferManager.swift): Esegue rsync su SSH con ripresa tramite una cartella separata dei parziali (--partial-dir, così un trasferimento interrotto lascia intatto il file di destinazione fino alla sostituzione finale), config temporanee isolate (0700 e 0600) e buffer esplicito a due tratte ServerMountApp-xfer-<UUID> per copie server-to-server.
  • Servizio file SFTPService senza mount (comandi SSH e cat su ControlMaster) su main e ricerca in corso in pa-sftp (SFTPService.swift): Già nel ramo principale SFTPService.swift (così chiamato per ragioni storiche, senza usare il sottosistema SFTP) esegue comandi quotati e flussi binari via cat su socket SSH ControlMaster senza estensioni FUSE, protegge gli argomenti con -- e presidia le radici (percorsoCanonico e protectedPaths). Il ramo di sviluppo pa-sftp studia inoltre il calcolo SHA-256 in streaming a 256 KiB; nelle prove un singolo file da 8 MiB resta più lento di scp, mentre lotti da 128 file da 16 KiB sono risultati nettamente più rapidi di scp -r. Pipelining parallelo, trasferimento diretto senza transito sul Mac e compressione adattiva restano domande di ricerca aperte.
  • Indice locale e stato nodi da istantanea (IndiceSyncLocale, SyncCartelleManager, StatoSyncStore): Calcola hash in blocchi da 64 KiB (O_NOFOLLOW, O_NONBLOCK), applica fnmatch, filtra i file temporanei dal suffisso UUID a 36 caratteri e salva JSON atomici. SyncCartelleManager legge lo stato per nodo da StatoSyncStore (o la pausa), ricadendo su .offline solo senza istantanea o su errore: l’aggiornamento automatico richiede un’autorizzazione file persistente senza ripieghi, quello manuale può ripiegare su indiceRemotoViaElenco (file-elenca) nel rispetto del consenso; comando indice con hash lato agente e sync continua restano in costruzione.
Ambito Base implementata nel codice Ricerca in corso e limiti aperti
Agente macOS e permessi pubblico-macos.sh (11 capacità, chiuso di default, sessione predefinita di 30 minuti, configurabile con --durata, verifica scadenza ogni 5 s); automa TCC a 3 stati in PermessiMacOS; ParserSaluteMacOS Finestra passo-passo nell’app e collaudo dei pannelli di sistema e del riavvio su hardware Mac fisico (non ancora eseguito)
Compressione lossless Tela Tasselli 16×16 fino a 8.192 pixel, zstd 1.5.7 con prefisso tela e record FLUSSO (tipo 4) verificati con CRC-32 nel ramo di sviluppo client Codificatore nativo dei glifi per cambi scena 1440p (oggi 150–200 ms in Python contro 37 ms zstd); integrazione client dello specchio SALVA/COPIA e code d’invio in 4K
Pacing di rete Mac↔Server 40 treni UDP misurati (540 datagrammi da 1.202 byte) con SCM_TIMESTAMP_MONOTONIC che mostrano pause radio da 2,38 ms contro 5,5 µs nel burst Sblocco adattivo della banda su unità di accesso lunghe sotto contesa Wi-Fi variabile nel percorso produttivo
Trasferimento file e sync cartelle file-ricevi con verifica SHA-256 a 64 caratteri; rsync con --partial-dir; servizio file SFTPService (SSH/cat su ControlMaster senza mount); IndiceSyncLocale a 64 KiB con filtro UUID a 36 caratteri; istantanea nodi in StatoSyncStore (.offline senza dati/su errore, ripiego manuale via indiceRemotoViaElenco) SHA-256 in streaming a 256 KiB nel ramo pa-sftp (file singoli da 8 MiB contro lotti 128 × 16 KiB), pipelining parallelo, compressione adattiva, comando indice con hash lato agente e sincronizzazione continua in background

Domande frequenti (FAQ)

Come garantisce CardinalHost su macOS che il canale di supporto resti chiuso per impostazione predefinita gestendo con chiarezza i permessi TCC?

Lo script di supporto pubblico-macos.sh mantiene l’accesso bloccato dopo l’installazione: le sessioni singole aperte con --sessione durano 30 minuti per impostazione predefinita (selezionabili con --durata anche a due ore o fino alla chiusura manuale) e, quando temporizzate, sono verificate ogni 5 secondi da un job launchd, mentre --blocca revoca subito l’accesso (coprendo le 11 capacità dichiarate in capacita.json, con audio di sistema da macOS 13+). In parallelo, PermessiMacOS modella i permessi TCC in 3 stati espliciti così la logica distingue il riavvio dell’app necessario dopo la registrazione schermo da un permesso mancante (mentre la finestra passo-passo nell’app non è ancora costruita).

Perché CardinalHost studia tasselli lossless 16×16 con zstd invece di inviare immagini differenza sopra la base video HEVC?

Nella nostra ricerca in corso (2026-10-22-tela-esatta), persino un residuo quasi lossless (errore massimo 1) tra pixel sorgente e base HEVC decodificata attorno ai bordi nitidi del testo ha richiesto da 3 a 8 volte più byte rispetto ai tasselli lossless 16×16 diretti, perché il rumore di quantizzazione alza l’entropia. Il ramo di ricerca abbina quindi zstd 1.5.7 con la tela del client come dizionario prefisso e controllo CRC-32, mentre la scomposizione in glifi a pieno schermo 1440p (150–200 ms CPU in Python contro 37 ms di zstd) resta disattivata di default in attesa di un encoder nativo.

Che cosa hanno mostrato le misure di pacing dei pacchetti con SCM_TIMESTAMP_MONOTONIC tra server Linux e Mac?

Su 40 treni reali di pacchetti UDP per 540 datagrammi ricevuti da 1.202 byte ciascuno, tutte le 40 prove hanno mostrato pause dello scheduler della rete d’accesso: nel burst i pacchetti distavano in mediana 5,5 µs, separati però da pause mediane di 2,38 ms. Sonde brevi da 6 o 16 pacchetti misurano quindi le pause radio anziché il collo di bottiglia da 54,2 Mbit/s, motivo per cui la ricerca in corso limita la velocità dichiarata a quanto consegnato da unità di accesso lunghe.

Quali percorsi di trasferimento file tra Mac e server sono già operativi oggi e quali restano oggetto di ricerca?

Su main sono operativi il trasferimento file-ricevi con verifica SHA-256 a 64 caratteri, la coda rsync (--partial-dir), il servizio file SFTPService senza mount (SSH/cat su ControlMaster con presidio dei percorsi), l’indicizzatore in streaming da 64 KiB IndiceSyncLocale e lo stato nodi tramite SyncCartelleManager e StatoSyncStore (.offline solo senza istantanea o su errore; l’aggiornamento automatico esige un’autorizzazione file persistente senza ripiego, quello manuale può ripiegare su indiceRemotoViaElenco nel rispetto del consenso). Sono oggetto di ricerca in pa-sftp e nei filoni collegati lo SHA-256 in streaming a 256 KiB (128 file da 16 KiB più rapidi di scp -r, singolo file da 8 MiB dietro scp), il pipelining parallelo, la compressione adattiva, il comando indice con hash lato agente e la sync continua.

Condividi questo articolo

Commenti

Nessun commento ancora. Sii il primo a commentare!

Lascia un commento

Non sarà pubblicata

Articoli Correlati

Hai un progetto in mente?

Sviluppiamo software personalizzato e soluzioni IA. Iniziamo insieme il tuo prossimo progetto.

Primo colloquio gratuito