# Git History - OpenRouter API Key Monitor

Documentazione dei commit con contesto e motivazione.

---

## 2026-04-07: User Authentication Phase (T17-T22)

### feat(schemas): T17 add Pydantic auth schemas
**Commit:** 02473bc

**Contesto:**
Implementazione degli schemas Pydantic per l'autenticazione utente.

**Motivazione:**
- Separazione chiara tra dati di input (register/login) e output (response)
- Validazione centralizzata delle password con validate_password_strength()
- Supporto ORM mode per conversione automatica da modelli SQLAlchemy

**Dettagli implementativi:**
- UserRegister: email (EmailStr), password (min 12, validazione strength), password_confirm
- UserLogin: email, password
- UserResponse: id, email, created_at, is_active (from_attributes=True)
- TokenResponse: access_token, token_type, expires_in
- TokenData: user_id (Union[str, int]), exp

---

### feat(auth): T18 implement user registration endpoint
**Commit:** 714bde6

**Contesto:**
Endpoint per la registrazione di nuovi utenti.

**Motivazione:**
- Verifica email unica prima della creazione
- Hashing sicuro delle password con bcrypt
- Risposta che esclude dati sensibili

**Dettagli implementativi:**
- POST /api/auth/register
- Verifica esistenza email nel DB
- hash_password() per crittografare la password
- Ritorna UserResponse con status 201
- Errori: 400 per email duplicata, 422 per validazione fallita

---

### feat(auth): T19 implement user login endpoint
**Commit:** 4633de5

**Contesto:**
Endpoint per l'autenticazione e generazione JWT.

**Motivazione:**
- Verifica credenziali senza esporre dettagli specifici degli errori
- Generazione token JWT con scadenza configurabile
- Risposta standard OAuth2-like

**Dettagli implementativi:**
- POST /api/auth/login
- Ricerca utente per email
- verify_password() per confronto sicuro
- create_access_token(data={"sub": str(user.id)})
- Ritorna TokenResponse con status 200
- Errori: 401 per credenziali invalide

---

### feat(auth): T20 implement user logout endpoint
**Commit:** b00dae2

**Contesto:**
Endpoint per il logout formale (JWT stateless).

**Motivazione:**
- JWT sono stateless, il logout avviene lato client
- Endpoint utile per logging e future implementazioni (token blacklist)
- Richiede autenticazione per coerenza

**Dettagli implementativi:**
- POST /api/auth/logout
- Requiere current_user: User = Depends(get_current_user)
- Ritorna {"message": "Successfully logged out"}

---

### feat(deps): T21 implement get_current_user dependency
**Commit:** 1fe5e1b

**Contesto:**
Dipendenza FastAPI per estrarre utente autenticato dal token JWT.

**Motivazione:**
- Riutilizzabile in tutti gli endpoint protetti
- Validazione completa del token (firma, scadenza, claims)
- Verifica utente esista e sia attivo

**Dettagli implementativi:**
- Usa HTTPBearer per estrarre token da header Authorization
- decode_access_token() per decodifica e validazione
- Estrazione user_id dal claim "sub"
- Recupero utente dal DB
- HTTPException 401 per qualsiasi errore di autenticazione

---

### test(auth): T22 add comprehensive auth endpoint tests
**Commit:** 4dea358

**Contesto:**
Test suite completa per l'autenticazione.

**Motivazione:**
- Coverage >= 90% obbligatorio
- Test di casi limite e errori
- Isolamento dei test con database in-memory

**Dettagli implementativi:**
- TestClient di FastAPI con override get_db
- Fixture: test_user, auth_token, authorized_client
- Test schemas: 19 test per validazione
- Test router: 15 test per endpoint
- Coverage finale: 98.23%

---

## Riepilogo Fase Authentication

| Task | Commit | Test | Coverage |
|------|--------|------|----------|
| T17 | 02473bc | 19 | 100% |
| T18 | 714bde6 | 5 | 100% |
| T19 | 4633de5 | 4 | 100% |
| T20 | b00dae2 | 3 | 100% |
| T21 | 1fe5e1b | 3 | 87% |
| T22 | 4dea358 | - | - |
| **Totale** | 6 commits | 34 | **98.23%** |

**Prossima fase:** Gestione API Keys (T23-T29)

---

## 2026-04-07: API Token Management Phase (T41-T43)

### feat(tokens): T41-T43 implement API token management endpoints
**Commit:** 5e89674

**Contesto:**
Implementazione della gestione token API per l'accesso programmatico alla public API.

**Motivazione:**
- Gli utenti necessitano di token API per accedere alla public API (/api/v1/*)
- Sicurezza critica: token plaintext mostrato SOLO alla creazione
- Limite di token per utente per prevenire abuse
- Soft delete per audit trail

**Dettagli implementativi:**

**T41 - POST /api/tokens:**
- Auth JWT required
- Body: ApiTokenCreate (name: 1-100 chars)
- Verifica limite: MAX_API_TOKENS_PER_USER (default 5)
- Genera token con generate_api_token() → (plaintext, hash)
- Salva SOLO hash SHA-256 nel DB
- Ritorna: ApiTokenCreateResponse con token PLAINTEXT (solo questa volta!)
- Errori: 400 se limite raggiunto, 422 se nome invalido

**T42 - GET /api/tokens:**
- Auth JWT required
- Ritorna: List[ApiTokenResponse] (NO token values!)
- Solo token attivi (is_active=True)
- Ordinamento: created_at DESC
- Filtraggio per user_id (sicurezza: utente vede solo i propri)

**T43 - DELETE /api/tokens/{id}:**
- Auth JWT required
- Verifica ownership (403 se token di altro utente)
- Soft delete: set is_active = False
- Ritorna: 204 No Content
- Token revocato non funziona più su API pubblica (401)
- Errori: 404 se token non trovato, 403 se non autorizzato

**Sicurezza implementata:**
- ✅ Token plaintext mai loggato
- ✅ Solo hash SHA-256 nel database
- ✅ Token values mai inclusi in risposte GET
- ✅ Verifica ownership su ogni operazione
- ✅ Soft delete per audit trail

**Test:**
- 24 test totali
- 100% coverage su routers/tokens.py
- Test sicurezza critici: NO token values in GET, revoked token fails on public API

---

## Riepilogo Fase API Token Management

| Task | Descrizione | Test | Stato |
|------|-------------|------|-------|
| T41 | POST /api/tokens (generate) | 8 | ✅ Completato |
| T42 | GET /api/tokens (list) | 7 | ✅ Completato |
| T43 | DELETE /api/tokens/{id} (revoke) | 9 | ✅ Completato |
| **Totale** | | **24** | **100% coverage** |

**MVP Fase 1 completato al 52%!** 🎉