# Requirements: ClientHub v2.3 Email & Accesso

**Defined:** 2026-06-21
**Core Value:** Il cliente apre il link e vede esattamente a che punto è il suo progetto, cosa deve ancora succedere e cosa ha già approvato — senza dover scrivere email per chiedere aggiornamenti.

## v2.3 Requirements

### Email OTP Gate (AUTH-OTP-01)

Portale cliente blindato da email OTP. Nuovo `client_emails` table (whitelist) + `otp_codes` table (codice, email, expires_at, consumed). Resend come provider email. Sessione **90 giorni** con cookie dopo verifica, revocabile dall'admin.

- [x] **OTP-01**: Admin può aggiungere e rimuovere email dalla whitelist di ogni cliente nell'admin UI
- [x] **OTP-02**: Cliente senza sessione OTP vede una schermata "inserisci email" invece della dashboard
- [x] **OTP-03**: Sistema invia OTP via Resend solo se l'email inserita è nella whitelist di quel cliente
- [x] **OTP-04**: Cliente inserisce il codice OTP ricevuto e ottiene sessione autenticata (cookie **90 giorni**)
- [x] **OTP-05**: Codici OTP scadono dopo 15 minuti dall'invio
- [x] **OTP-06**: Endpoint OTP è rate-limited per prevenire brute force
- [x] **OTP-07**: Messaggi di errore OTP non rivelano se l'email è in whitelist o no (no enumeration)
- [x] **OTP-08**: Admin può revocare in blocco tutte le sessioni attive di un cliente

> **[2026-07-28] Modifiche alla spec del 2026-06-21**, decise in sessione:
> - Sessione **90 giorni** invece di 30 (rientro più fluido), compensata da OTP-08.
> - **SEND-01/SEND-02 spostati al backlog v2.4**: il preventivo si invia a mano, l'automazione non serve ora. Phase 23 si è ridotta alla sola infrastruttura Resend, che l'OTP usa comunque.
> - **Il gate NON sta nel layout** ma in cima a ogni page sotto `/client/[token]/`. Nell'App Router il segmento `page` viene renderizzato in parallelo al layout: gattare nel layout nascondeva la dashboard a schermo ma lasciava fasi, task e pagamenti nel payload RSC dell'HTML (verificato: 46.907 byte con i dati → 17.594 dopo il fix). Helper: `src/lib/client-gate.ts`.

## v2.4+ Backlog

### Conversione Commerciale

- **PROP-03**: Stripe Payment Link su deck pubblico `/preventivo/[slug]`
- **PROP-04**: Auto-provisioning cliente/progetto/fasi al "Vinto" nel CRM
- **SEND-01/SEND-02**: invio del link `/preventivo/[slug]` via email dall'admin UI — *rinviato da v2.3 il 2026-07-28, l'invio si fa a mano. L'infrastruttura Resend (`src/lib/mailer.ts`) è già pronta, manca solo l'azione e il pulsante.*

### Post-Vendita

- **Phase 13**: Gestione servizi attivi/ricorrenti post-vendita nel portale cliente (congelata da v2.1)

## Out of Scope

| Feature | Reason |
|---------|--------|
| Self-registration cliente | Solo whitelist admin-gestita — nessun accesso senza approvazione esplicita |
| Magic link senza OTP | OTP è più sicuro e già deciso come design; magic link = scope creep |
| Email marketing / newsletter | Non pertinente al portale |
| Multi-admin | Ancora single admin per ora |

## Traceability

| Requirement | Phase | Status |
|-------------|-------|--------|
| OTP-01 | Phase 24 | ✅ Done (2026-07-28) |
| OTP-02 | Phase 25 | ✅ Done (2026-07-28) |
| OTP-03 | Phase 25 | ✅ Done (2026-07-28) |
| OTP-04 | Phase 25 | ✅ Done (2026-07-28) |
| OTP-05 | Phase 25 | ✅ Done (2026-07-28) |
| OTP-06 | Phase 25 | ✅ Done (2026-07-28) |
| OTP-07 | Phase 25 | ✅ Done (2026-07-28) |
| OTP-08 | Phase 24 | ✅ Done (2026-07-28) |
| SEND-01 | — | ⏭️ Rinviato a v2.4 |
| SEND-02 | — | ⏭️ Rinviato a v2.4 |

**Coverage:**
- v2.3 requirements: 8 in scope (OTP-01…08) + 2 rinviati
- Implementati: 8/8 ✓ — verificati con 9 test E2E in locale contro il DB di produzione
- **Non ancora in produzione**: il codice è scritto e testato ma NON pushato. Vedi i blocchi in `STATE.md`.

---
*Requirements defined: 2026-06-21*
*Last updated: 2026-07-28 — sessione 90gg, OTP-08 aggiunto, SEND-01/02 rinviati, OTP-01…08 implementati*