#23 feat: API key auth opzionale + sanitizzazione errori + hardening Docker

[Anonymous]

Originally created by: zornade

Contesto

Diversi fork e operatori in produzione richiedono di esporre visura-api come servizio HTTP autenticato. Attualmente:

• gli endpoint /visura, /visura/{id}, /visura/intestati, /sezioni/extract, /shutdown sono pubblici se la porta 8000 è esposta
• gli errori 500 propagano direttamente lo stack trace al client (detail=str(e)), in violazione di OWASP A05/A09
• il Dockerfile esegue playwright install come root prima di scendere a appuser, lasciando residui di permessi non necessari
• il docker-compose.yaml di default monta ./:/app in bind, sovrascrivendo il codice copiato nell'immagine — utile in dev, problematico in prod

Proposta

Importare il pattern già implementato in mycochang/visura-api@c8dfd0b (AGPL-3.0, compatibile upstream):

1. API Key opzionale via header X-API-Key: si attiva solo se la env var API_KEY è definita (retrocompatibile: vuota → endpoint pubblici come ora). Applicata via Depends(verify_api_key) su tutti gli endpoint mutativi.
2. Sanitizzazione errori 500: detail="Errore interno del server. Consulta i log per i dettagli." lato client, logger.error(..., exc_info=True) lato server.
3. Dockerfile: playwright install solo come appuser, niente residui root; riordino delle ENV per chiarezza.
4. docker-compose: rimosso il bind mount ./:/app di default (resta solo il volume per logs/).

Compatibilità

• Tutte le modifiche sono retrocompatibili: client esistenti continuano a funzionare senza API_KEY configurata.
• L'utente dev che usa docker-compose per hot-reload può ripristinare il bind mount tramite docker-compose.override.yaml.

Lavoro a monte

Patch già scritta nel fork sopra (autore @mycochang, AGPL-3.0). Da adattare al main corrente (17 commit behind, possibili conflitti minori su main.py).

Test

• aggiungere test che verifichi: senza API_KEY env, /visura risponde 422/500 (input invalido) e mai 403; con API_KEY set, /visura senza header → 403.
• aggiungere test che verifichi che detail di un 500 non contenga né Traceback né nome del file Python interno.

Riferimenti

• mycochang fork branch: feat/api-hardening HEAD c8dfd0b
• Roadmap parente: [#15]