Chiedi a Metnos con una richiesta come quella di questo esempio: «Mostrami come collegare Telegram all'utente Lucia». Il Tutor indica il percorso nella chat web anche quando la domanda proviene da Telegram.

In Metnos, associare significa stabilire un'identità verificata prima di elaborare una richiesta. L'identità non viene mai dedotta dal testo del messaggio. Utente logico, recapito del canale, sessione di chat e dispositivo di esecuzione sono oggetti distinti, con registri e revoche indipendenti.

1. Le quattro associazioni

Un browser associato non è automaticamente un dispositivo remoto. Il primo consente di usare la chat; il secondo riceve lavoro dal server e lo esegue sulla macchina in cui risiedono dati o applicazioni. Analogamente, trasferire una sessione web non modifica il pairing Telegram né la proprietà di un dispositivo.

2. Utenti, ruoli e isolamento

runtime/users.py mantiene un solo utente con ruolo host e gli eventuali utenti guest. Ogni record ha un identificativo tecnico, un nome univoco, un ruolo, un proprietario opzionale e un livello di autonomia. user_channels collega quello stesso utente ai canali verificati telegram, mail e http.

La lingua e le preferenze vengono risolte dall'associazione autenticata prima del turno e applicate in un contesto locale alla richiesta. Una modifica per un utente non cambia la lingua o la sessione di un altro. Anche conversazioni, dialoghi pendenti e diritto di scrittura della chat web sono circoscritti per utente e canale.

I due registri usano vocabolari diversi e non vanno confusi:

• users.db: read_only, restricted, full;
• pairings.db: ReadOnly, Supervised, Full.

Nel daemon Telegram, ReadOnly impedisce l'avvio di un turno operativo. Supervised e Full possono entrare nel runtime; ogni executor resta comunque soggetto ai propri manifest, ai controlli di sicurezza e alle approvazioni previste. Il livello memorizzato non è, da solo, la prova che una specifica azione sia consentita.

3. Associare Telegram o un browser

Dalla chat web apri Settings > Sistema > Utenti. Crea o seleziona l'utente, quindi usa il controllo di associazione del canale desiderato. Se stai leggendo queste istruzioni da Telegram, il percorso indicato si trova nella chat web di Metnos, non nell'app Telegram.

Telegram

1. Nel dettaglio dell'utente emetti il token per il canale Telegram.
2. Trasferisci il token alla persona tramite un mezzo fidato.
3. La persona apre il bot Metnos e invia /start <token>.
4. Il daemon consuma il token, lega il chat_id all'utente e conferma l'associazione.

Il token è casuale, monouso e valido un'ora. Il consumo usa una transazione SQLite: due richieste concorrenti non possono usare entrambe lo stesso token. Il comando /start associa l'utente ma non esegue una richiesta operativa; il messaggio successivo avvia un nuovo turno.

Browser e altri dispositivi web

1. Nel dettaglio dell'utente emetti il collegamento per il canale HTTP.
2. Apri quel collegamento una sola volta sul browser da associare.
3. Metnos consuma il token, registra il binding e salva un cookie firmato, HttpOnly e Secure.

Il cookie utente dura al massimo 90 giorni, ma a ogni verifica il server controlla che il binding HTTP esista ancora. Rimuovere il canale dal dettaglio dell'utente invalida quindi l'accesso anche se il browser conserva il cookie.

4. Codici firmati di canale

runtime/pairing.py espone anche il flusso tecnico /pair PAIR.<payload>.<firma>. Il payload dichiara versione, identificativo, livello di autonomia, scadenza ed emittente; la firma Ed25519 viene verificata contro le chiavi pubbliche fidate. Il codice scade dopo cinque minuti per impostazione predefinita e può essere consumato una sola volta.

./.venv/bin/python -m runtime.pairing generate <ReadOnly|Supervised|Full> 5m
./.venv/bin/python -m runtime.pairing list
./.venv/bin/python -m runtime.pairing revoke telegram <sender_id>

Questo flusso crea il record di basso livello (channel, sender_id). Per associare una persona già presente nel registro utenti, il percorso Settings > Sistema > Utenti con /start è più diretto perché conserva esplicitamente l'identità logica.

Se il bootstrap è abilitato, il primo messaggio proveniente dal default_chat_id può creare un pairing Full soltanto quando il canale non contiene ancora alcun pairing. L'opzione --no-bootstrap richiede invece un'associazione esplicita anche per l'host.

5. Sessione attiva e trasferimento della conversazione

Per ogni coppia (utente, canale web) Metnos ammette una sola sessione di scrittura attiva. Se apri la chat su un dispositivo mentre la sessione appartiene a un altro, la finestra propone tre scelte:

La risoluzione è atomica e legata all'utente autenticato. Il token di risoluzione è monouso; un utente non può trasferire la conversazione di un altro. Il dispositivo precedente riceve, quando connesso, l'evento di revoca e passa in sola lettura. La conversazione appartiene all'utente, non al browser.

6. Dispositivi per executor remoti

Dalla chat web apri Settings > Sistema > Dispositivi. La pagina elenca nome, proprietario, sistema operativo, versione del client, impronta della chiave, ultimo heartbeat e stato. Puoi installare il client sul PC corrente, generare un collegamento per un altro PC oppure emettere un token manuale.

Il flusso guidato è il seguente:

1. L'amministratore sceglie nome e proprietario e genera una sessione di adesione.
2. Il PC di destinazione apre il collegamento e scarica l'installer per Windows o Linux.
3. Il client genera localmente una coppia di chiavi Ed25519; la chiave privata non lascia il dispositivo.
4. POST /agent/register consuma il token e registra chiave pubblica, impronta, proprietario e caratteristiche del sistema.
5. Il server restituisce la propria chiave pubblica; il client la fissa e la usa per verificare gli ordini successivi.
6. Il primo heartbeat conclude il percorso osservabile di installazione.

La sessione guidata usa un token firmato, monouso, normalmente valido 30 minuti; la variante manuale emessa dalla pagina vale 10 minuti. Un secondo consumo con la stessa chiave è idempotente, mentre lo stesso token presentato con una chiave diversa viene rifiutato. Un token nuovo associato alla medesima chiave costituisce una ri-autorizzazione esplicita e può riattivare un dispositivo revocato.

Il protocollo degli executor remoti usa per impostazione predefinita la porta 8765 sulla rete interna o su una rete privata. Poll, risultati e heartbeat sono firmati dal dispositivo sui byte esatti del corpo. Gli ordini e i bundle del server sono verificati dal client tramite la chiave associata durante l'appaiamento. last_heartbeat segnala che il processo è vivo; last_poll segnala separatamente che il worker sta chiedendo lavoro.

7. Revoca e ciclo di vita

8. Invarianti di sicurezza

• Identità prima del contenuto. Il testo non può dichiarare un utente, un ruolo o un proprietario.
• Token a scadenza e monouso. Il consumo è serializzato prima di creare o aggiornare il binding.
• Proprietà verificata. Sessioni e conversazioni vengono lette e trasferite soltanto entro lo stesso utente e canale.
• Revoca consultata a ogni accesso. Una firma o un cookie validi non riattivano un binding rimosso.
• Chiavi private locali. La chiave privata del dispositivo remoto non viene inviata al server.
• Registri separati. Revocare un oggetto non muta implicitamente gli altri; l'operatore vede quale identità sta modificando.

Per il contratto generale dei trasporti vedi channel; per le approvazioni delle azioni vedi approvazioni e controllo umano; per le rotte HTTP vedi http_api.