Registration (case-insensitive unique names, 8-256 char passwords, no email), sign-in with a generic error and a fresh session, internal-only ?next=, POST-only sign-out, password change that closes the other sessions. The failed-login backoff, the registration quota and the password-change guard live in the database so every web process shares them; the client IP is the last X-Forwarded-For hop. One responsive stylesheet with light/dark theme, labelled fields, alerts and no inline scripts or styles; Italian error pages and a readable CSRF failure. Mutation checks: open redirects, uncounted failures and a missing CSRF middleware are all caught. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
190 lines
14 KiB
Markdown
190 lines
14 KiB
Markdown
# Sito, web app e console operativa
|
||
|
||
Prefisso: `WEB`. Origine: [../TODO.md](../TODO.md). Scelte: [ADR-54](adr/ADR-54-django-unico-framework-web-tre-aree.md)
|
||
(framework e aree), [ADR-56](adr/ADR-56-staff-account-individuali-permessi-mfa-dopo-pilota.md)
|
||
(staff), [ADR-57](adr/ADR-57-due-pause-distinte-dopo-round-e-incidente.md) (pause),
|
||
[ADR-60](adr/ADR-60-pilota-solo-italiano.md) (lingua).
|
||
|
||
I requisiti sono `*Stato:* da implementare` salvo dove indicato diversamente; la
|
||
sequenza è in [../roadmap.md](../roadmap.md). Il vecchio sito è `index.html` con
|
||
backend FastAPI (vedi [architettura.md](architettura.md)).
|
||
|
||
## 1 · Struttura
|
||
|
||
- **[WEB-01]** Un solo dominio e un solo progetto Django servono tre aree:
|
||
pubblica, giocatore e staff, con uno stile condiviso:
|
||
|
||
| Percorso | Accesso | Funzione |
|
||
|---|---|---|
|
||
| `/` | pubblico | stato del round, quota, montepremi confermato, chiusura, «Partecipa» |
|
||
| `/guida/`, `/regole/` | pubblico | funzionamento, custodia, conferme, commissioni, vincita, prelievo |
|
||
| `/risultati/`, `/risultati/<round_id>/` | pubblico | archivio estrazioni, esito, prova, stato del pagamento |
|
||
| `/accedi/`, `/registrati/` | pubblico | accesso e registrazione, con ritorno alla destinazione interna |
|
||
| `/app/` | giocatore | round corrente, disponibilità, propria partecipazione |
|
||
| `/app/portafoglio/` | giocatore | saldo spendibile, fondi in conferma, indirizzo con QR, prelievo |
|
||
| `/app/movimenti/` | giocatore | storico di depositi, puntate, vincite, prelievi |
|
||
| `/app/profilo/` | giocatore | impostazioni, password, segnalazioni, logout |
|
||
| `/ops/` | staff | supervisione e azioni operative autorizzate |
|
||
| `/admin/` | staff con permessi sui modelli | utenti e segnalazioni; record di gioco in sola lettura |
|
||
|
||
*Stato:* scheletro (A1): progetto Django, `/` segnaposto, `/admin/` ·
|
||
*Codice:* `config/urls.py`, `apps/web/urls.py` · *Test:* `tests/django/test_scaffold.py::test_home_answers_on_localhost`
|
||
- **[WEB-02]** L'autenticazione usa le sessioni Django; ogni scrittura è
|
||
protetta da CSRF e il cookie di sessione ha gli attributi `Secure`,
|
||
`HttpOnly` e `SameSite`.
|
||
*Stato:* implementato (A5): sessione di 24 ore, cookie `Secure`/`HttpOnly`/`SameSite=Lax`, CSRF su ogni modulo con
|
||
pagina di errore leggibile ·
|
||
*Codice:* `config/settings.py`, `apps/web/views.py:csrf_failure` ·
|
||
*Test:* `tests/django/test_accounts.py::test_the_session_cookie_is_httponly_secure_and_samesite`, `test_a_form_without_the_csrf_token_is_refused`
|
||
- **[WEB-03]** Ogni richiesta dell'area giocatore legge o modifica soltanto i
|
||
dati dell'utente autenticato; un identificativo di un altro utente dà 404.
|
||
- **[WEB-04]** Importi e saldi si rappresentano in unità minime intere
|
||
([ADR-35](adr/ADR-35-aritmetica-satoshi-interi.md)); i parametri economici e
|
||
temporali del round sono fissati alla sua apertura ([ADR-10](adr/ADR-10-parametri-round-fotografati-all-apertura.md)).
|
||
*Stato:* colonne e vincoli implementati (A2, [DAT-76]…[DAT-78]); la copia all'apertura con A4 ·
|
||
*Test:* `tests/django/test_models.py::test_amounts_are_integers_only`
|
||
- **[WEB-05]** I dati che cambiano (stato del round, saldo, esito) si
|
||
aggiornano con richieste periodiche mirate e si recuperano al rientro nella
|
||
pagina; ricaricare non perde lo stato salvato.
|
||
- **[WEB-06]** Le pagine sono utilizzabili da smartphone e da desktop e
|
||
navigabili da tastiera, con stati distinti di errore, attesa e conferma.
|
||
*Stato:* base implementata (A5): layout fluido da 400 px, foglio di stile unico con tema chiaro/scuro, collegamento «Vai al
|
||
contenuto», focus sempre visibile, etichette su ogni campo, errori annunciati (`role="alert"`), nessuno script né stile
|
||
inline, pagine d'errore in italiano; la verifica su telefono e desktop con le schermate finali è l'A10 ·
|
||
*Codice:* `apps/web/templates/web/base.html`, `apps/web/static/web/site.css` ·
|
||
*Test:* `tests/django/test_accounts.py::test_every_page_is_responsive_and_keyboard_friendly`, `test_every_input_has_its_label`, `test_pages_use_no_inline_scripts_or_styles`
|
||
|
||
- **[WEB-07]** Il sito si avvia e si naviga in locale su `http://localhost`
|
||
(stesso `docker-compose.yml` di sempre, `SITE_ADDRESS` non impostato) con
|
||
regtest e ledger simulato, senza dominio né configurazioni esterne. Il
|
||
dominio definitivo si aggiunge solo con la configurazione (`SITE_ADDRESS`,
|
||
`ALLOWED_HOSTS`, `CSRF_TRUSTED_ORIGINS`), senza modifiche al codice, e i
|
||
cookie `Secure` valgono solo dove c'è HTTPS ([WEB-02]).
|
||
*Stato:* implementato (A1) ·
|
||
*Codice:* `config/settings.py`, `docker-compose.yml`, `Caddyfile` ·
|
||
*Test:* `tests/django/test_scaffold.py::test_domain_comes_from_configuration_only`, `test_unknown_host_is_refused`
|
||
|
||
## 2 · Area pubblica
|
||
|
||
- **[WEB-10]** `/` mostra quota, montepremi **confermato** e chiusura, con
|
||
l'ora del server come riferimento, e uno fra gli stati: nessun round,
|
||
puntate aperte, in chiusura, estrazione in corso, pagamento in attesa,
|
||
manutenzione.
|
||
- **[WEB-11]** «Partecipa» porta a `/app/`; se serve il login, dopo
|
||
l'accesso riporta alla schermata di gioco. Il pulsante apre il flusso: la
|
||
puntata richiede una conferma esplicita.
|
||
*Stato:* il ritorno alla destinazione interna è implementato (A5, [WEB-52]); il pulsante con l'A6.
|
||
- **[WEB-12]** `/risultati/` pubblica esito e prova dell'estrazione,
|
||
riproducibile con i dati del protocollo ([RND-14]…[RND-20]), senza
|
||
username né dati dell'account. Il pagamento risulta confermato solo quando lo è.
|
||
- **[WEB-13]** Guida e regole usano gli stessi termini dell'area giocatore
|
||
(quota, ripartizione 70/30, commissioni, attesa delle conferme) e non
|
||
promettono l'accredito immediato.
|
||
|
||
## 3 · Area giocatore
|
||
|
||
- **[WEB-20]** «Gioca», «Portafoglio» e «Movimenti» sono schermate separate;
|
||
nel flusso principale hanno priorità quota, stato del round e puntata dell'utente.
|
||
- **[WEB-21]** Saldo spendibile e fondi in conferma sono distinti. Il deposito
|
||
mostra rete, indirizzo, QR, copia e stato delle conferme.
|
||
- **[WEB-22]** Prima di inviare una puntata si mostrano round e importo; il
|
||
server valida disponibilità, quota, limiti e stato del round. Dopo l'invio
|
||
si mostra lo stato effettivo (attesa, conferma, rifiuto o esclusione).
|
||
*Stato:* validazione e stati implementati nel ledger (A3: round, scadenza, quota del round, limiti, fondi,
|
||
`round_closing`, `already_betting`, `round_full`, `bets_suspended`, `balance_pending_confirmation`, rifiuto ed esclusione);
|
||
la schermata con l'A7 ·
|
||
*Codice:* `apps/lottery/ledger.py:SimulatedLedger.place_bet` · *Test:* `tests/django/test_ledger.py`
|
||
- **[WEB-23]** Un doppio invio della stessa richiesta produce una sola
|
||
operazione logica (chiave di idempotenza associata alla richiesta).
|
||
*Stato:* implementato nel ledger (A3, [ARC-76]); il modulo di invio con l'A7 ·
|
||
*Test:* `tests/django/test_ledger.py::test_the_same_bet_request_is_one_bet`
|
||
- **[WEB-24]** Il prelievo mostra, prima della conferma, indirizzo, importo
|
||
richiesto, commissione e importo netto previsto. Lo storico distingue lo stato
|
||
dell'operazione dal TXID corrente e lo collega all'explorer quando disponibile.
|
||
|
||
## 4 · Console operativa
|
||
|
||
- **[WEB-30]** Ogni operatore ha un account staff individuale; `/ops/` e
|
||
`/admin/` richiedono i permessi espliciti, verificati nelle viste e nelle azioni.
|
||
- **[WEB-31]** `/ops/` mostra round in corso, prossima scadenza, salute di
|
||
Electrum e del worker, operazioni in ritardo, ultima riconciliazione e il
|
||
motivo di eventuali pause.
|
||
- **[WEB-32]** Django Admin gestisce utenti e segnalazioni; round chiusi,
|
||
transazioni e audit sono in sola lettura. Le azioni operative passano dai
|
||
servizi della lotteria e registrano attore, data, azione, motivo ed esito.
|
||
- **[WEB-33]** Il recupero delle chiavi non è esposto dal pannello web: è una
|
||
procedura dedicata fuori dal web.
|
||
- **[WEB-34]** La MFA TOTP e il recupero dell'accesso sono requisiti di uscita
|
||
della Fase C, non del pilota ([ADR-56](adr/ADR-56-staff-account-individuali-permessi-mfa-dopo-pilota.md)).
|
||
Il token `ADMIN_TOKEN` sparisce al passaggio alla nuova area.
|
||
|
||
## 5 · Pause
|
||
|
||
- **[WEB-40]** «Pausa dopo il round in corso»: il round attivo continua fino
|
||
al pagamento, il successivo resta sospeso.
|
||
- **[WEB-41]** «Sospendi nuove puntate»: comando distinto per gli incidenti;
|
||
nessuna nuova puntata, ma le operazioni già inviate restano monitorate.
|
||
- **[WEB-42]** La sospensione dei prelievi è un comando separato dalle altre due.
|
||
- **[WEB-43]** Pausa, ripresa e modifiche critiche richiedono conferma e
|
||
motivazione; la console mostra quali operazioni continuano e quali verifiche
|
||
servono prima della ripresa. Le pause automatiche si riesaminano dal servizio applicativo.
|
||
- **[WEB-44]** Ogni comando operativo è negato a un giocatore e a uno staff
|
||
senza il permesso specifico, si riflette sul sito con l'effetto previsto e
|
||
compare nell'audit.
|
||
|
||
## 6 · Avvio in locale
|
||
|
||
Per navigare il sito su `https://localhost` (certificato autofirmato: l'avviso del browser alla prima visita è atteso):
|
||
|
||
```bash
|
||
mkdir -p data/db
|
||
cp .env.example .env # poi impostare DJANGO_SECRET_KEY (almeno 50 caratteri):
|
||
python3 -c "import secrets; print(secrets.token_urlsafe(64))"
|
||
docker compose up -d --build
|
||
```
|
||
|
||
Servizi: `web` (Django + gunicorn, applica le migrazioni), `worker` ([ARC-71]) e `caddy`.
|
||
Con un dominio reale basta `SITE_ADDRESS=lottery.example.com docker compose up -d`
|
||
([WEB-07]). Il vecchio `docs/setup.md` e `docs/running-the-server.md` descrivono lo stack
|
||
FastAPI, che non è più nel compose.
|
||
|
||
## 7 · Accesso e account
|
||
|
||
- **[WEB-50]** **Registrazione.** `/registrati/` crea un account con nome utente di 3–32 caratteri `[A-Za-z0-9_.-]`, unico
|
||
**senza distinzione fra maiuscole e minuscole** e salvato come digitato ([ADR-38](adr/ADR-38-username-unico-spazio-nomi-senza-distinzione.md)),
|
||
e password di 8–256 caratteri da ripetere due volte ([SEC-17]). Non si raccoglie alcuna email, quindi non esiste un recupero
|
||
automatico ([ADR-37](adr/ADR-37-nessun-recupero-password-reset.md)). Alla fine l'utente è già connesso e la
|
||
registrazione è nell'audit (`user_registered`). La password è salvata con Argon2 ([ADR-36](adr/ADR-36-password-argon2-sessioni-jwt-hs256-24.md)).
|
||
*Stato:* implementato (A5) ·
|
||
*Codice:* `apps/accounts/views.py:register_view`, `apps/accounts/forms.py:RegisterForm`, `apps/accounts/validators.py` ·
|
||
*Test:* `tests/django/test_accounts.py::test_registering_creates_the_account_and_signs_in`, `test_a_name_that_differs_only_by_case_is_taken`, `test_password_length_limits`
|
||
- **[WEB-51]** **Accesso.** `/accedi/` ammette il nome utente in qualunque combinazione di maiuscole e minuscole e risponde
|
||
**allo stesso modo** a un nome inesistente e a una password sbagliata ([SEC-19]); al login la sessione riceve una chiave nuova;
|
||
un account disattivato non entra; un utente già connesso che apre `/accedi/` o `/registrati/` è rimandato avanti.
|
||
*Stato:* implementato (A5) ·
|
||
*Codice:* `apps/accounts/views.py:login_view`, `apps/accounts/backends.py:CaseInsensitiveBackend` ·
|
||
*Test:* `tests/django/test_accounts.py::test_unknown_name_and_wrong_password_look_the_same`, `test_signing_in_gives_a_fresh_session`, `test_login_ignores_the_case_of_the_name`
|
||
- **[WEB-52]** **Destinazione dopo l'accesso.** `?next=` (e il campo nascosto che lo porta attraverso un errore o il passaggio alla
|
||
registrazione) è rispettato **solo se è un percorso del sito**: un indirizzo esterno, `//host`, una barra rovesciata o uno schema
|
||
(`javascript:`) ricadono su `/app/`, così la pagina di accesso non può mandare altrove. `/app/` e `/app/profilo/` senza sessione
|
||
rimandano ad `/accedi/?next=…`.
|
||
*Stato:* implementato (A5) ·
|
||
*Codice:* `apps/accounts/views.py:safe_next` ·
|
||
*Test:* `tests/django/test_accounts.py::test_an_open_redirect_is_refused`, `test_an_internal_destination_is_honoured`, `test_the_destination_survives_a_wrong_password_and_the_trip_to_registration`
|
||
- **[WEB-53]** **Limiti ai tentativi, condivisi fra i processi.** Lo stato sta nel database (`ThrottleEvent`), non in memoria
|
||
([ARC-72]). *Accesso:* dopo 5 errori sullo stesso nome (20 sullo stesso indirizzo) ogni tentativo deve attendere
|
||
`2 s · 2^(errori − soglia)`, fino a 300 s dall'ultimo errore; la serie finisce dopo 900 s di quiete; un accesso riuscito azzera il
|
||
nome ma **non** l'indirizzo; durante l'attesa non si guarda nemmeno la password (risposta `429` con `Retry-After`).
|
||
*Registrazione:* al massimo 5 account all'ora per indirizzo, contando gli account creati e non i tentativi. *Cambio password:*
|
||
5 errori sulla password attuale per utente, poi attesa ([SEC-54]). L'indirizzo del cliente è l'**ultimo** elemento di
|
||
`X-Forwarded-For`, quello scritto dal nostro proxy ([B-54]).
|
||
*Stato:* implementato (A5) ·
|
||
*Codice:* `apps/accounts/throttle.py`, `apps/accounts/client_ip.py` ·
|
||
*Test:* `tests/django/test_accounts.py::test_five_wrong_guesses_lock_the_name_for_a_while`, `test_the_wait_doubles_with_every_further_failure_and_is_capped`, `test_spraying_one_password_over_many_names_is_caught_by_the_address`, `test_one_address_can_register_five_accounts_an_hour`, `test_a_forged_forwarded_header_cannot_dodge_the_ip_controls`
|
||
- **[WEB-54]** **Uscita e cambio password.** L'uscita è solo `POST` (con CSRF) e chiude la sessione. Il cambio password chiede la password
|
||
attuale, chiude **tutte le altre sessioni** (una sessione è legata all'impronta della password con cui nasce, [B-34]), lascia
|
||
connessa quella corrente e scrive `password_changed` nell'audit. `/app/profilo/` mostra solo i dati dell'utente connesso ([WEB-03]).
|
||
*Stato:* implementato (A5); le segnalazioni del profilo non sono ancora previste ·
|
||
*Codice:* `apps/accounts/views.py:logout_view`, `apps/accounts/views.py:profile_view` ·
|
||
*Test:* `tests/django/test_accounts.py::test_a_password_change_signs_out_every_other_session`, `test_signing_out_ends_the_session_and_only_by_post`, `test_the_profile_shows_only_the_owner`
|