Files

T

davide f27fe6243c Harden session handling, add password reset/change, and firm up round polling

Session hardening: / and /admin now respond with Cache-Control: no-store, and
both pages re-derive their auth state on pageshow (event.persisted) as a
safety net against bfcache showing a stale logged-in/out view across
back/forward navigation. The user page also syncs logout across tabs via the
storage event, since localStorage is shared but in-memory JS state isn't.

Password recovery: admin gets a "Reset" button per user (POST
/admin/users/{id}/reset-password) that generates and sets a new password,
shown once — passwords are Argon2-hashed and can never be recovered, only
replaced. Users get self-service password change (POST
/users/me/change-password, requires the current password) under a new
Profilo tab, alongside read-only account info (username, address, balance,
join date).

Round display robustness: the user dashboard now refreshes immediately on
tab visibility change (background tabs get their timers throttled hard),
shows an explicit "connessione persa" state after repeated failed polls
instead of silently freezing on stale data, and polls faster both right when
the countdown hits zero and through the gap where the round is past its
deadline but still waiting for in-flight bets to confirm before the server
actually closes it.

2026-07-22 12:00:09 +02:00

8.5 KiB

Raw Blame History

Guida admin

Come gestire la configurazione operativa di PLM Lottery. Presuppone che il server sia già avviato — vedi running-the-server.md.

Accesso

Il pannello admin è su https://<host>/admin — non è collegato da nessun link nell'interfaccia utente (né in entrata né in uscita): ci si arriva solo conoscendo l'URL. La pagina mostra solo un campo token finché non accedi: non è protetta da login personale, ma da un token condiviso (ADMIN_TOKEN, definito in .env).

Incolla il valore di ADMIN_TOKEN e premi "Accedi" (o Invio): se il token è valido, si apre la dashboard con una navbar in alto e carica automaticamente tutte le sezioni — nessun bottone "Carica" separato. Il token resta in sessionStorage (si perde chiudendo la tab/il browser); "Esci" torna alla sola schermata di login.

Sezioni della dashboard

Parametri — configurazione operativa (vedi tabella sotto)
Utenti — elenco utenti, saldo, accesso alla chiave privata, reset password
Round — storico round: stato, vincitore, importi, txid di payout
Transazioni pendenti — bet/payout/prelievi non ancora confermati, candidati al fee-bump RBF
Audit log — eventi registrati dal sistema (config cambiata, bet, payout, accessi a chiavi private, ecc.)

Parametri

Tutti i parametri operativi/di business sono nella sezione "Parametri", salvati nel database — modificabili in qualsiasi momento, effetto immediato, nessun riavvio del server necessario. Non esiste alcuna variabile d'ambiente equivalente: .env contiene solo segreti e configurazione di infrastruttura (chiave master, JWT, Electrum, token admin), non parametri di business — quelli si toccano solo da qui.

Campo	Significato
Fee address	L'indirizzo PLM su cui finisce il 30% di ogni round (fee). Obbligatorio: i payout non partono se questo campo è vuoto.
Bet amount (PLM)	Il costo fisso d'ingresso per round.
Durata round (secondi)	Quanto resta aperto un round prima di chiudersi ed estrarre il vincitore.
Pausa tra un round e il successivo (secondi)	Cooldown dopo la chiusura di un round, prima che il successivo si apra — dà tempo ai giocatori di vedere l'esito.
Durata animazione estrazione (secondi)	Tempo minimo per cui la dashboard di ogni utente mostra l'animazione "Estrazione in corso" dopo la chiusura del round, prima di rivelare il vincitore. È solo un minimo: l'estrazione reale aspetta un blocco confermato (~2 minuti in media), quindi l'animazione può durare più a lungo di questo valore, mai meno.
Importo minimo deposito/prelievo (PLM)	Soglia minima per un prelievo (i depositi non hanno un controllo minimo lato server, solo un floor consigliato).
Fee rate di rete (sat/vB)	Fee per byte usata per costruire bet, payout e prelievi.
Timeout prima del fee-bump RBF (secondi)	Dopo quanto tempo senza conferma una transazione viene ritrasmessa con fee più alta.

Tutti gli importi in PLM vengono convertiti in sats (1 PLM = 100.000.000 sats) solo nella chiamata API — il backend lavora sempre in sats.

Su un'istanza nuova (mai avviata), questi campi partono con dei default hardcoded nel codice (RoundConfig in app/db/models.py: bet 10 PLM, round 10 minuti, cooldown 30s, animazione estrazione 20s, minimo 1 PLM, fee 1 sat/vB, RBF timeout 900s) — vanno comunque rivisti e confermati dal pannello prima del primo utilizzo reale.

Manutenzione (pausa/ripresa lotteria)

In cima alla sezione "Parametri" c'è una card "Manutenzione" con un pulsante per fermare l'apertura di nuovi round — utile per intervenire sul server (aggiornamenti, riavvii) senza lasciare gli utenti a metà di un round o sorprenderli con un'interruzione improvvisa.

"Interrompi dopo questo round": il round eventualmente in corso viene completato normalmente — chiude, estrae il vincitore da un blocco confermato, e paga il 70/30 come sempre. Solo l'apertura del round successivo viene sospesa. Gli utenti vedono un avviso di manutenzione sulla loro dashboard (e sulla home, anche da sloggati) finché la lotteria resta in pausa.
"Riprendi lotteria": annulla la pausa — al prossimo giro dello scheduler (ogni 5 secondi) un nuovo round si apre normalmente (rispettando comunque il cooldown se il precedente si è appena chiuso).

Ogni pausa/ripresa viene registrata nell'audit log (lottery_paused / lottery_resumed), ma — come per il resto del pannello — non registra quale operatore l'ha premuta (token condiviso, vedi limiti noti in CLAUDE.md).

Chi paga il fee-bump RBF? Quando una bet, un payout o un prelievo resta troppo a lungo senza conferma (oltre il "Timeout prima del fee-bump RBF"), il sistema lo ritrasmette con una fee più alta. Il costo aggiuntivo lo assorbe sempre chi ha originato la transazione, non il destinatario: per bet e prelievi è l'utente stesso (gli torna un resto più piccolo), per i payout è il pool (il resto che torna all'indirizzo pool si riduce) — la quota del vincitore e quella delle fee, già fissate, non vengono mai toccate. Se non c'è un resto abbastanza grande da assorbire l'aumento, il bump fallisce e resta un intervento manuale (vedi "Limiti noti").

Round

La sezione "Round" mostra lo storico (GET /admin/rounds, ultimi 50 per default): id, stato, orario di apertura, vincitore (username), importo del pool, importo vinto, importo di fee, txid del payout — tutti in PLM salvo il txid.

Transazioni pendenti

GET /admin/pending-transactions elenca bet, payout e prelievi ancora senza conferma: tipo, stato, txid corrente, fee rate usata, numero di tentativi (si incrementa a ogni bump RBF) e orario dell'ultima trasmissione. Una riga che resta qui a lungo, con attempt_count che sale, indica una transazione in difficoltà — vedi "Limiti noti" sul fallback RBF.

Audit log

GET /admin/audit-log elenca gli ultimi 200 eventi registrati dal sistema (tipo evento, payload JSON, utente/round coinvolti, timestamp): bet piazzate, payout inviati, round chiusi, configurazione modificata, accessi alle chiavi private, ecc. È il primo posto da controllare per ricostruire cosa è successo dopo un problema.

Alternative all'interfaccia grafica

Le stesse operazioni si possono fare da terminale o da Swagger UI (https://<host>/docs, sezione admin), sempre passando ADMIN_TOKEN nell'header X-Admin-Token:

# leggere la configurazione
curl https://<host>/admin/config -H "X-Admin-Token: <ADMIN_TOKEN>"

# aggiornarla (importi in sats: 10 PLM = 1000000000; solo i campi passati vengono cambiati)
curl -X PUT https://<host>/admin/config \
  -H "X-Admin-Token: <ADMIN_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"fee_address": "plm1q...", "bet_amount_sats": 1000000000, "round_duration_seconds": 600}'

Utenti, chiave privata e reset password

La card "Utenti" elenca id, username, indirizzo e saldo di ogni utente registrato. Il bottone "Mostra" su ogni riga rivela la chiave privata (WIF) di quell'utente, dietro conferma esplicita — serve per interventi manuali (es. restituire fondi bloccati). Ogni visualizzazione viene registrata nell'audit log (admin_privkey_accessed). Questo non introduce una nuova falla: il server è già custodial, la chiave master da cui derivano tutte le chiavi utente vive sul server — questo pannello espone solo qualcosa che l'operatore può già fare via script.

Il bottone "Reset" nella colonna "Password" genera una nuova password casuale per l'utente e sovrascrive quella esistente — mostrata una sola volta nel pannello, così puoi comunicarla a chi ti ha chiesto aiuto perché l'ha dimenticata. Non è un "recupero": le password sono salvate solo come hash Argon2 (app/auth/security.py), quindi quella vecchia non è mai recuperabile né per l'admin né per il codice stesso — l'unica opzione è sempre sostituirla con una nuova. Anche questa azione è audit-loggata (admin_password_reset) e non esiste alcun flusso self-service equivalente per l'utente: solo un admin col token può farlo.

Limiti noti

Il token è unico e condiviso: non c'è identità per singolo admin né audit di chi ha cambiato cosa (oltre alla tabella audit_log generica).
Nessun rate limiting sugli endpoint admin (né su registrazione/bet/ prelievo utente).
Se un payout fallisce (es. Electrum disconnesso, UTXO insufficienti), il round resta bloccato in paying_out senza retry automatico — richiede intervento manuale.

Per l'elenco completo dei gap noti vedi la sezione "Known gaps / TODO" in CLAUDE.md.

8.5 KiB Raw Blame History