mantenimento-app 2.2.9 → 2.3.0

package/README.md

@@ -33,70 +33,133 @@ npm run dev
 3. Apri:
 
 ```text
-http://localhost:3001
+http://localhost:3000
 ```
 
-## Puntare GitHub Pages a un backend dev separato
+## Build frontend minificato
+
+```bash
+npm run build:frontend
+```
+
+Il server serve automaticamente `app.min.js` se presente, altrimenti `app.js`.
+
+## Avvio produzione locale
+
+```bash
+npm start
+```
+
+`npm start` esegue build frontend + avvio server.
 
-Il frontend gia supporta un endpoint backend esplicitamente configurato.
-Per usare `https://favagit.github.io/mantenimento-app/` contro un backend dev reale:
+## Endpoint backend
+- `POST /api/calculate`: calcolo modello mantenimento server-side; il payload transita su HTTPS/TLS in produzione e la risposta applica header `Cache-Control: no-store`
+- `GET /api/health`: health check
+
+Parametri server utili:
+- `CALCULATE_RATE_WINDOW_MS`: finestra del rate limit per `/api/calculate` (default `60000`)
+- `CALCULATE_RATE_MAX_REQUESTS`: massimo richieste per IP nella finestra (default `30`)
+- `ACCESS_LOG_ENABLED`: abilita log strutturati minimizzati, attivo di default in produzione
+- `ACCESS_LOG_SALT`: sale usato per anonimizzare il riferimento client nei log applicativi
+- payload JSON in ingresso limitato a `64kb`
+
+### URL login sicuro (token monouso)
+Per evitare credenziali in chiaro nel link, e disponibile un flusso `authToken` firmato server-side.
+
+Variabili ambiente backend richieste:
+- `AUTH_URL_LOGIN_SECRET`: segreto HMAC (lungo e casuale)
+- `AUTH_URL_LOGIN_ALLOWED_USER`: utenti consentiti (separati da virgola, es. `favagit,fabio.vacchino`)
+- `AUTH_URL_LOGIN_SUPABASE_URL`: URL progetto Supabase
+- `AUTH_URL_LOGIN_SUPABASE_ANON_KEY`: anon key Supabase
+- `AUTH_URL_LOGIN_SUPABASE_SERVICE_ROLE_KEY`: service-role key (necessaria per risolvere email automaticamente da `sub`)
+- `AUTH_URL_LOGIN_SUPABASE_EMAIL`: email account da autenticare via URL token
+- `AUTH_URL_LOGIN_SUPABASE_PASSWORD`: password account da autenticare via URL token
+- `AUTH_URL_LOGIN_SUPABASE_USERS_JSON`: mappa opzionale `sub -> {password}` (email risolta automaticamente da Supabase) oppure `sub -> {email,password}`
+- `AUTH_URL_LOGIN_MAX_TTL_SEC`: TTL massimo token (default `180`)
+- `AUTH_URL_LOGIN_BOOTSTRAP_KEY`: chiave per avviare autologin server-side senza shell
+- `AUTH_URL_LOGIN_FRONTEND_BASE`: URL frontend di destinazione (default `https://favagit.github.io/mantenimento-app/autologin.html`)
+- `API_ALLOWED_ORIGINS`: origini consentite per API cross-origin (es. `https://favagit.github.io`)
+
+Generazione token e link:
+
+```bash
+npm run auth:url-token -- --sub=favagit --ttl=120 --baseUrl=https://favagit.github.io/mantenimento-app/
+```
 
-1. Pubblica il backend dev su un host HTTPS raggiungibile pubblicamente.
-	Esempio: `https://dev-api.example.com`
-2. Nel backend dev abilita CORS verso GitHub Pages:
+Entry point dedicato per URL autologin:
 
-```env
-CORS_ALLOWED_ORIGINS=https://favagit.github.io
+```text
+https://favagit.github.io/mantenimento-app/autologin.html?authToken=...
 ```
 
-3. Apri GitHub Pages con l'override runtime dell'API base:
+La pagina `autologin.html` reindirizza automaticamente su `index` aggiungendo `autologin=1`.
+Supporta anche token nel fragment/hash (es. `.../autologin.html#authToken=...`) per ridurre esposizione nei log intermedi.
+
+Il comando stampa un link del tipo:
 
 ```text
-https://favagit.github.io/mantenimento-app/?apiBase=https://dev-api.example.com
+https://favagit.github.io/mantenimento-app/?autologin=1&authToken=...
 ```
 
-Per usare anche il frontend del branch dev con un link unico:
+Avvio completamente automatico lato backend (senza generare token da shell):
 
 ```text
-https://favagit.github.io/mantenimento-app/?frontend=dev&env=dev
+https://mantenimento-app.onrender.com/api/auth/url-login/start?k=<BOOTSTRAP_KEY>&sub=favagit
 ```
 
-`frontend=dev` apre la preview frontend del branch configurata in `supabase-config.js`,
-mentre `env=dev` seleziona il backend dev.
+Il backend genera token monouso in automatico e reindirizza al frontend.
+Se `AUTH_URL_LOGIN_SUPABASE_USERS_JSON` e configurato, il valore `sub` determina anche quale account Supabase viene autenticato.
 
-L'override viene memorizzato in `localStorage`, quindi resta attivo anche ai refresh successivi.
-Per tornare al backend di default:
+Esempio pratico (solo password, email auto-risolta):
 
 ```text
-https://favagit.github.io/mantenimento-app/?apiBase=reset
+AUTH_URL_LOGIN_SUPABASE_USERS_JSON={"favagit":{"password":"<PASS_FAVAGIT>"},"fabio.vacchino":{"password":"<PASS_FABIO>"}}
 ```
 
-## Build frontend minificato
+Per ottenere il link in JSON invece del redirect:
 
-```bash
-npm run build:frontend
+```text
+https://mantenimento-app.onrender.com/api/auth/url-login/start?k=<BOOTSTRAP_KEY>&sub=favagit&format=json
 ```
 
-Il server serve automaticamente `app.min.js` se presente, altrimenti `app.js`.
+Note sicurezza:
+- Il token e monouso, con scadenza breve e firma HMAC.
+- I parametri sensibili vengono rimossi dalla barra URL subito dopo la lettura.
+- Il login via `authPass`/`authPass64` e disabilitato per hardening.
 
-## Avvio produzione locale
+### Script SQL donor (globale server-side)
+Per assegnare/rimuovere privilegi donor in modo globale su Supabase:
+
+- `scripts/sql/grant-donor.sql`
+- `scripts/sql/revoke-donor.sql`
+
+Esegui gli script da Supabase SQL Editor (modificando eventualmente la lista utenti nel `WHERE`).
+
+### Gestione donor da CLI (senza SQL Editor)
+In alternativa puoi gestire i donor direttamente da riga di comando usando l'Admin API di Supabase.
+
+Variabili ambiente richieste:
+- `DONOR_ADMIN_SUPABASE_URL` (es. `https://<project>.supabase.co`)
+- `DONOR_ADMIN_SUPABASE_SERVICE_ROLE_KEY` (service-role key)
+
+Esempi:
 
 ```bash
-npm start
+npm run donor:grant -- --users=favagit,fabio.vacchino
+npm run donor:revoke -- --users=fabio.vacchino
 ```
 
-`npm start` esegue build frontend + avvio server.
+Per test senza scrivere modifiche:
 
-## Endpoint backend
-- `POST /api/calculate`: calcolo modello mantenimento server-side; il payload transita su HTTPS/TLS in produzione e la risposta applica header `Cache-Control: no-store`
-- `GET /api/health`: health check
+```bash
+npm run donor:grant -- --users=favagit --dry-run
+```
 
-Parametri server utili:
-- `CALCULATE_RATE_WINDOW_MS`: finestra del rate limit per `/api/calculate` (default `60000`)
-- `CALCULATE_RATE_MAX_REQUESTS`: massimo richieste per IP nella finestra (default `30`)
-- `ACCESS_LOG_ENABLED`: abilita log strutturati minimizzati, attivo di default in produzione
-- `ACCESS_LOG_SALT`: sale usato per anonimizzare il riferimento client nei log applicativi
-- payload JSON in ingresso limitato a `64kb`
+Supporta anche email complete:
+
+```bash
+npm run donor:grant -- --emails=fabio.vacchino@gmail.com
+```
 
 ## KeyLock multi-device (Supabase)
 Il login cloud resta lato frontend e usa `supabase-config.js` (chiave anon pubblica).