# Sicurezza — guida dettagliata dei moduli

Tutti i moduli sono **attivabili/disattivabili solo dal super-admin** in:

**Telegram → bot in privato → `/settings` → 🔐 Sicurezza**

Gli admin aggiunti *vedono* lo stato, ma se toccano un toggle ricevono "Solo super-admin".

## Com'è fatto il menu

La parte alta del messaggio mostra lo stato ON/OFF dei moduli (con valori di attesa, probation, retention e un riepilogo anti-spam). Sotto:

- **🛡 Anti-spam** — apre il sottomenu dedicato (anti-flood + soglia msg/finestra, no forward, scam, strike, scorciatoie a 🔗 Link e ⚠️ Warn)
- griglia di pulsanti con **icone**, uno per modulo: un tocco inverte ON↔OFF
- **⏳ Attesa −5s / +5s** — secondi dell'attesa minima
- **⏳ Probation −15m / +15m** — minuti del periodo di prova
- **⭐ VIP**, **🚩 Report lista**, **📜 Audit** — gestioni e log
- **🔄 Riverifica tutti** — riverifica massiva (con conferma)
- **📝 Vedi note** — testo `quality_notes` corrente
- **Indietro** — torna al pannello principale

---

# I moduli, uno per uno

## 🔢 Captcha

**Cosa fa:** prima di chiedere la videobolla, il bot invia in privato una semplice domanda matematica (es. "Quanto fa 3+5?") con 4 pulsanti numerici.

**Come funziona:** l'utente deve toccare la risposta giusta; solo allora riceve le istruzioni per la videobolla. Risposta sbagliata → nuovo tentativo con nuova domanda.

**Quando usarlo:** se il gruppo riceve bot di spam automatici. I bot banali non sanno premere il pulsante corretto.

## ⏱ Attesa minima

**Cosa fa:** impone N secondi di attesa tra l'ingresso nel gruppo e l'invio della videobolla.

**Come funziona:** se l'utente invia il video troppo presto, il bot risponde "Attendi ancora Xs" e non lo accetta. Regoli i secondi con i pulsanti **Attesa −5s / +5s** (il valore corrente è visibile nella riga "Attesa minima").

**Quando usarlo:** contro gli script che entrano e inviano subito un video preregistrato. 10–20 secondi bastano quasi sempre.

## 🆕 Flag account nuovi

**Cosa fa:** segnala nella notifica agli admin quando l'account sembra creato di recente.

**Come funziona:** euristica basata sull'ID Telegram (gli ID vengono assegnati in modo crescente, quindi un ID molto alto suggerisce un account recente). **Non** è un dato ufficiale Telegram: è solo un indizio, non un blocco.

**Quando usarlo:** sempre utile, non ha effetti negativi: aggiunge solo informazione alla review.

## 👮 Forza manuale nuovi

**Cosa fa:** se l'account è segnalato come "nuovo" (vedi sopra), la sua verifica va **sempre a review umana**, anche se la modalità globale è Automatica o Ibrida.

**Quando usarlo:** insieme a "Flag account nuovi", se vuoi la comodità dell'approvazione automatica per gli account normali ma controllo umano su quelli sospetti.

## @ Richiedi username

**Cosa fa:** rifiuta di avviare la verifica se l'utente non ha impostato uno @username Telegram.

**Come funziona:** il bot spiega all'utente come impostarlo (Impostazioni → Username) e lo invita a riprovare con `/start`.

**Quando usarlo:** è una misura aggressiva (molti utenti legittimi non hanno username). Attivala solo se il tuo gruppo lo richiede esplicitamente.

## 🎥 Una sola videobolla

**Cosa fa:** mentre una videobolla è già in coda di review, l'utente non può inviarne altre.

**Come funziona:** i reinvii vengono ignorati con un messaggio "La tua videobolla è già in valutazione".

**Quando usarlo:** sempre consigliato ON: evita che gli admin ricevano 5 copie dello stesso utente.

## 🧪 Probation (periodo di prova)

**Cosa fa:** dopo l'approvazione, l'utente per N minuti può scrivere **solo testo**: i suoi media (foto, video, sticker, documenti) e messaggi con link vengono cancellati.

**Come funziona:** alla scadenza il bot invia un DM "periodo di prova terminato" e i permessi tornano normali. Regoli la durata con **Probation −15m / +15m**.

**Quando usarlo:** contro chi si verifica onestamente e poi spamma subito. 30–60 minuti è un buon valore.

## 🛡 Anti-spam (pannello)

In `/settings` → 🔐 Sicurezza → **🛡 Anti-spam** trovi raggruppati:

| Controllo | Funzione |
|-----------|----------|
| 🌊 Anti-flood | Cancella messaggi troppo frequenti |
| Msg ± / Finestra ± | Soglia (es. 5 msg in 8 secondi) |
| ↪️ No forward | Blocca messaggi inoltrati |
| 🚫 Scam list / domains | Domini scam da cancellare |
| ⚠️ Strike | Collegamento alla scala penalità |
| 🔗 Link | Scorciatoia al filtro link |

---

## 🌊 Anti-flood

**Cosa fa:** se un utente invia troppi messaggi in pochi secondi, i messaggi in eccesso vengono cancellati.

**Come funziona:** il bot conta i messaggi recenti per utente; superata la soglia, cancella. Se anche gli **Strike** sono ON, il flood assegna uno strike.

**Quando usarlo:** gruppi grandi o con episodi di spam a raffica.

## ⚠️ Strike (penalità progressive)

**Cosa fa:** sistema di penalità automatiche a escalation.

**Come funziona:**

| Strike | Conseguenza |
|--------|-------------|
| 1° | Avviso nel gruppo |
| 2° | Mute temporaneo |
| 3° | Kick (espulsione, può rientrare) |
| 4°+ | Ban + inserimento in blacklist |

Gli strike vengono assegnati dalle violazioni automatiche (es. anti-flood).

**Quando usarlo:** insieme ad anti-flood, se vuoi che i recidivi vengano gestiti senza intervento admin.

## ↪️ Blocca forward

**Cosa fa:** cancella i messaggi **inoltrati** da altri chat/canali, inviati dai non-admin.

**Quando usarlo:** contro lo scam "inoltra da canale truffa". Attenzione: blocca anche inoltri legittimi, valuta in base al tuo gruppo.

## 🗄 Retention (pulizia dati)

**Cosa fa:** dopo N giorni cancella dal database i riferimenti (`file_id`) delle videobolle vecchie.

**Come funziona:** il bot non salva mai i file video sul server, solo gli ID Telegram; la retention rimuove anche quelli, per privacy. Il valore in giorni è visibile nella riga "Retention".

**Quando usarlo:** consigliato ON con 30 giorni, per non conservare riferimenti a video di persone più a lungo del necessario.

## 📜 Audit log

**Cosa fa:** registra le azioni amministrative (toggle attivati, setgroup, admin/VIP/blacklist aggiunti, riverifiche…), con chi le ha fatte e quando.

**Come vederlo:** pulsante **Audit** nel menu Sicurezza (solo super-admin) → ultime voci registrate.

**Quando usarlo:** sempre ON se ci sono più super-admin, per sapere "chi ha acceso cosa".

## ⭐ VIP skip

**Cosa fa:** gli utenti nella lista VIP **saltano completamente la verifica**: non vengono mutati, non ricevono captcha né richieste di videobolla, e vengono saltati anche dalla riverifica massiva.

**Come si gestisce:**

1. Menu Sicurezza → pulsante **VIP**
2. Invia l'ID numerico o inoltra un messaggio dell'utente
3. Per rimuovere: `/unvip ID` in privato

Il toggle **VIP skip** deve essere ON perché la lista abbia effetto.

## 🚪 Join request

**Cosa fa:** supporta i gruppi con "Approva nuovi membri" attivo: quando qualcuno chiede di entrare, il bot **approva la richiesta** e avvia subito mute + verifica.

**Come attivarlo:**

1. Nel gruppo Telegram: Impostazioni → Tipo di gruppo/Permessi → **Approva nuovi membri**
2. Il bot deve avere il permesso admin per gestire le richieste di ingresso
3. Attiva **Join request** in Sicurezza

**Quando usarlo:** solo se il gruppo usa le richieste di ingresso; altrimenti lascialo OFF.

## 🚫 Scam list (domini truffa)

**Cosa fa:** cancella i messaggi del gruppo che contengono domini o pattern presenti nella lista scam.

**Come si gestisce:**

1. Menu Sicurezza → pulsante **Scam domains**
2. Invia un pezzo di dominio/URL: `evil.xyz`, `t.me/scamchannel`…
3. Per rimuovere: `/unscam ID` in privato

È complementare al **filtro link** (sezione 🔗 del pannello): il filtro link blocca *categorie* (inviti, canali, URL esterni), la scam list blocca *domini specifici* anche se il resto del filtro è spento.

## 📣 Report

**Cosa fa:** attiva il comando `/report` nel gruppo, con cui i membri segnalano messaggi sospetti.

**Come funziona per l'utente:** risponde al messaggio incriminato e scrive `/report motivo` (es. `/report spam phishing`). Il comando viene cancellato dal gruppo per discrezione.

**Come funziona per gli admin:** tutti gli admin ricevono in privato la segnalazione con autore, segnalato e motivo. Lo storico è nel pulsante **Report lista** del menu Sicurezza.

## 🛡 Reviewer ban

**Cosa fa:** permette agli **admin aggiunti** (non super-admin) di gestire la blacklist (aggiungere/rimuovere utenti).

**Default:** OFF — di norma solo il super-admin tocca la blacklist. Attivalo solo se ti fidi dei reviewer.

## 📌 Note qualità

**Cosa fa:** mostra la checklist di qualità in due punti:

- **all'utente**, insieme alle istruzioni (così sa cosa evitare prima di registrare)
- **agli admin**, nella notifica di review (promemoria dei criteri di rifiuto)

Il testo è nel setting `quality_notes` (visibile con **Vedi note**). Default:

```
📌 Note qualità videobolla:
• Troppo scuro / controluce → spesso rifiutato
• Sfocato / volto non riconoscibile → rifiutato
• Solo soffitto / muro / mano → rifiutato
• Mute / senza presentazione → può essere rifiutato
• Video riciclati / da terzi → ban
• Durata fuori range → non accettata dal bot
```

> Il bot **non analizza automaticamente** luminosità o sfocatura (servirebbe un sistema di visione AI). Le note guidano utenti e admin nella review umana.

---

## 🔄 Riverifica massiva

Da **Sicurezza → 🔄 Riverifica tutti**, il super-admin può richiedere di nuovo la videobolla a tutti gli utenti approvati conosciuti dal bot.

Prima di procedere il bot mostra:

- il numero di utenti coinvolti
- l'avviso sull'effetto (nuovo mute + nuova verifica)
- i pulsanti **✅ Sì, riverifica / ❌ Annulla**

Dopo la conferma, per ogni utente:

1. chiude l'eventuale verifica aperta e ne crea una nuova (lo storico resta)
2. lo muta nuovamente nel gruppo
3. gli invia un avviso in privato
4. avvia il captcha se attivo, altrimenti invia direttamente le istruzioni

Al termine ricevi un riepilogo: quanti riverificati, quanti saltati, quanti errori.

**Saltati automaticamente:** admin, utenti in blacklist, VIP (se VIP skip è ON).
Se Telegram fallisce su un singolo utente (mute o DM), il processo continua sugli altri.

> Limite Telegram: la Bot API non permette di scaricare l'elenco completo dei membri del gruppo. La funzione coinvolge quindi solo gli utenti approvati già presenti in `storage/bot.sqlite`, non eventuali membri mai registrati dal bot.

---

## Ordine consigliato di attivazione

1. Note qualità ON
2. Una sola videobolla ON
3. Captcha (se hai bot spam)
4. Attesa minima 10–20s
5. Anti-flood + strike (gruppi rumorosi)
6. Filtro link (sezione 🔗) + eventualmente scam list
7. Probation 30–60 min
8. Retention 30 giorni
9. Join request solo se il gruppo lo richiede

Attiva tutto insieme solo se hai già testato con un account secondario.

---

## Nuove protezioni e automazioni avanzate

Queste funzioni sono operative tramite settings SQLite e comandi admin.

| Setting | Default | Funzione |
|---------|---------|----------|
| `retry_after_reject_enabled` | `1` | Permette retry dopo un rifiuto “soft” |
| `retry_after_reject_hours` | `24` | Finestra ore per ritentare dopo rifiuto |
| `max_reverify_per_day` | `2` | Limite logico per future riverifiche ripetute |
| `reminders_enabled` | `1` | Promemoria a metà timeout e poco prima della scadenza |
| `alerts_enabled` | `1` | Alert agli admin su picchi di ingressi/verifiche |
| `alert_join_threshold_hour` | `10` | Soglia verifiche avviate in 1 ora prima dell'alert |
| `verification_hours_enabled` | `0` | Se ON, verifica disponibile solo in una fascia oraria |
| `verification_hours_start` | `09:00` | Inizio fascia verifica |
| `verification_hours_end` | `22:00` | Fine fascia verifica |
| `auto_vip_enabled` | `0` | Promuove a VIP utenti storici senza strike/blacklist |
| `auto_vip_days` | `180` | Giorni minimi da approvazione per auto VIP |
| `webhook_notify_enabled` | `0` | Invia eventi JSON a endpoint esterno |
| `webhook_notify_url` | vuoto | URL endpoint Slack/Discord/email bridge/custom |
| `web_panel_key` | random | Chiave per `admin_view.php` read-only |

### Reminder

Il bot controlla le verifiche in `awaiting_video` a ogni update. Se l’utente non ha ancora inviato la videobolla:

- a circa metà timeout invia un primo promemoria;
- al 90% del timeout invia l’ultimo avviso.

La tabella `verification_reminders` evita doppioni.

### Alert picchi

Se in 1 ora vengono avviate più verifiche della soglia `alert_join_threshold_hour`, tutti gli admin ricevono un alert. Il bot invia al massimo un alert per ora.

### Orari verifica

Con `verification_hours_enabled = 1`, il bot non avvia nuove verifiche fuori dalla fascia `verification_hours_start`–`verification_hours_end`. L’utente riceve un DM che invita a riprovare più tardi.

### Auto VIP

Se `auto_vip_enabled = 1`, il bot promuove automaticamente a VIP gli utenti:

- approvati da almeno `auto_vip_days`;
- senza strike;
- non in blacklist.

### Webhook esterno

Con `webhook_notify_enabled = 1` e `webhook_notify_url` valorizzato, il bot invia JSON sugli eventi principali:

```json
{
  "type": "join",
  "user_id": 123,
  "chat_id": -100123,
  "detail": "nome gruppo",
  "created_at": "..."
}
```

Usalo per collegare Slack, Discord, email, Zapier, Make, n8n o un tuo endpoint.

### Pannello web read-only

File: `admin_view.php`

URL:

```text
https://TUO-DOMINIO/bot/admin_view.php?key=WEB_PANEL_KEY
```

Mostra:

- contatori verifiche;
- pending review;
- report;
- event log.

Non modifica nulla. Se la chiave viene esposta, cambia `web_panel_key` nel database.