1. Scopo: chi sei prima di cosa vuoi

Alcuni canali (Telegram, Signal, Matrix) sono per definizione multi-utente: chiunque conosca l'handle può scrivere. Senza un meccanismo di riconoscimento, myclaw tratterebbe ugualmente Roberto e uno sconosciuto. Il pairing è il rito di "mi presento, aspetto il tuo permesso, poi siamo in affari".

Cosa copre

• Il flusso di pairing: richiesta → codice → approvazione admin → pairing attivo.
• Generazione e sicurezza del codice di accoppiamento.
• Ruoli assegnabili (admin, famiglia, ospite) e loro default di autonomy.
• Revoca e ri-pairing.

Cosa non copre

• Il canale CLI: non serve pairing (controllo di uid via Unix socket).
• La Policy che poi applica le regole al sender pairato (→ policy).
• Il flusso di approvazione per le tool call (→ approval_ux). Pairing è prima: decide chi può anche solo proporre.

2. Il flusso canonico

Sequenza in 5 passi. Vedi anche Architettura intro §7 fig. 4 per il diagramma narrativo.

1. Sconosciuto scrive: "ciao, posso parlare?" su Telegram.
2. Canale normalizza: gateway riceve sender="telegram:@nuovo_tizio". Pairing table non lo conosce.
3. Gateway genera codice: K7-DELTA-19 (formato umano, 3 sezioni). Stato pending. Risponde allo sconosciuto: "non ti conosco. Codice: K7-DELTA-19. Il tuo admin lo approverà o negherà."
4. Admin notificato: canale admin (CLI di Roberto, o Telegram @roberto pairato) riceve: "richiesta pairing: K7-DELTA-19 · telegram:@nuovo_tizio · primo contatto 2026-04-22 14:00. Approvi come: [admin | famiglia | ospite | nega]?"
5. Roberto decide: myclaw pairing approve telegram K7-DELTA-19 --as ospite. Pairing firmato, scritto in DB. Il sender ora può interagire, con autonomy mappata al ruolo (§4).

3. Generazione del codice

Formato: 3 segmenti di 2-6 caratteri alfanumerici separati da trattini, ispirato ai pairing code Bluetooth/Apple. Esempi: K7-DELTA-19, RB-AMBER-42.

def generate_pairing_code() -> str:
    # segment 1: 2 char (letter+digit)
    # segment 2: parola da lista curata 200 parole italiane/inglesi pronunciabili
    # segment 3: 2 digit
    import secrets
    s1 = secrets.choice(string.ascii_uppercase) + secrets.choice(string.digits)
    s2 = secrets.choice(WORD_LIST)
    s3 = f"{secrets.randbelow(100):02d}"
    return f"{s1}-{s2}-{s3}"

Spazio delle chiavi: 26·10 · 200 · 100 ≈ 5.2M. Entropia ~22 bit: non crittografica, ma sufficiente per contesto casalingo dove la collisione non è vettore di attacco serio (l'admin approva manualmente; il codice vive max 1h).

4. Approvazione admin e assegnazione ruolo

I ruoli

Comando admin

myclaw pairing approve <channel> <code> --as <role>
myclaw pairing deny    <channel> <code> [--never]
myclaw pairing list
myclaw pairing revoke  <channel> <sender_id> [--reason]

Il comando è disponibile solo da canale cli:roberto o dal sender admin stesso. Non è esposto come comando Telegram globale (troppo facile impersonation).

5. Stato "pending" e SLA di delivery

Una richiesta di pairing attende l'admin. Se l'admin dorme, lo sconosciuto non può stare in limbo all'infinito.

6. Firma e revoca

Firma HMAC

Al momento dell'approvazione, il record di pairing è firmato con una chiave interna di myclaw (in config/secrets.env come MYCLAW_HMAC_KEY). La firma copre: channel + sender_id + role + approved_at.

signature = hmac_sha256(
    key=MYCLAW_HMAC_KEY,
    msg=f"{channel}|{sender_id}|{role}|{approved_at_iso}"
)

A ogni messaggio ingerito, il gateway verifica la firma del pairing record. Se il record è stato manomesso (improbabile ma possibile se qualcuno edita il DB a mano), la firma non torna e il sender rientra in unknown.

Revoca

• Esplicita: myclaw pairing revoke <channel> <sender>. Record passa a revoked, mantiene la storia.
• Per policy: 3 deny consecutivi di azioni high-risk entro 10 minuti → warning admin. 10 deny in un giorno → revoca automatica + notifica.
• Per scadenza: ruolo ospite ha scadenza default 7 giorni (configurabile). Dopo, sender torna unknown e deve ri-pairare.

7. Storage e persistenza

-- workspace/state/pairings.db

CREATE TABLE pairings (
    pairing_id     TEXT PRIMARY KEY,
    channel        TEXT NOT NULL,
    sender_id      TEXT NOT NULL,
    display_name   TEXT,                    -- "@nuovo_tizio" a scopo umano
    role           TEXT NOT NULL,           -- admin | famiglia | ospite | revoked
    approved_by    TEXT NOT NULL,
    approved_at    DATETIME NOT NULL,
    expires_at     DATETIME,                -- NULL = no expiry
    signature      BLOB NOT NULL,
    UNIQUE(channel, sender_id)
);

CREATE TABLE pairing_requests (
    code           TEXT PRIMARY KEY,
    channel        TEXT NOT NULL,
    sender_id      TEXT NOT NULL,
    requested_at   DATETIME NOT NULL,
    expires_at     DATETIME NOT NULL,
    status         TEXT NOT NULL,           -- pending | approved | denied | expired
    resolved_at    DATETIME,
    resolved_by    TEXT
);

CREATE INDEX idx_pairings_sender ON pairings(channel, sender_id);
CREATE INDEX idx_requests_status ON pairing_requests(status, expires_at);

8. Contratto Python

from typing import Protocol, Literal
from dataclasses import dataclass

@dataclass
class Pairing:
    pairing_id: str
    channel: str
    sender_id: str
    display_name: str | None
    role: Literal["admin", "famiglia", "ospite", "revoked"]
    approved_by: str
    approved_at: datetime
    expires_at: datetime | None
    signature: bytes

@dataclass
class PairingRequest:
    code: str
    channel: str
    sender_id: str
    requested_at: datetime
    expires_at: datetime
    status: Literal["pending", "approved", "denied", "expired"]

class PairingService(Protocol):
    async def resolve_sender(
        self, channel: str, sender_id: str,
    ) -> Pairing | None:
        """Dato un sender, ritorna il pairing attivo o None."""
        ...

    async def initiate(
        self, channel: str, sender_id: str, display_name: str,
    ) -> PairingRequest:
        """Sender sconosciuto: genera codice, notifica admin."""
        ...

    async def approve(
        self, code: str, role: str, approved_by: str,
    ) -> Pairing: ...

    async def deny(self, code: str, reason: str) -> None: ...

    async def revoke(
        self, channel: str, sender_id: str, reason: str,
    ) -> None: ...

    async def autonomy_for_role(self, role: str) -> str:
        """Ritorna autonomy level default per ruolo."""
        ...

    async def expire_stale(self) -> int:
        """Job periodico: marca come expired le richieste scadute."""
        ...

9. Alternative considerate

10. Test di conformità

11. Riferimenti

Continua a leggere

myclaw — pairing v1.0 — 2026-04-22
Primo doc di fase 3. Prossimo: constitution.html.