# Prompt: Security Services Implementation (T12-T16)

## 🎯 OBIETTIVO

Implementare la fase **Security Services** del progetto OpenRouter API Key Monitor seguendo rigorosamente TDD (Test-Driven Development).

**Task da completare:** T12, T13, T14, T15, T16

---

## 📋 CONTESTO

- **Repository:** `/home/google/Sources/LucaSacchiNet/openrouter-watcher`
- **Specifiche:** `/home/google/Sources/LucaSacchiNet/openrouter-watcher/export/architecture.md` (sezione 6)
- **Kanban:** `/home/google/Sources/LucaSacchiNet/openrouter-watcher/export/kanban.md`
- **Stato Attuale:** Database & Models completati (T01-T11), 132 test passanti
- **Progresso:** 15% (11/74 task)

---

## 🔐 SPECIFICHE SICUREZZA (Da architecture.md)

### Algoritmi di Sicurezza

| Dato | Algoritmo | Implementazione |
|------|-----------|-----------------|
| **API Keys** | AES-256-GCM | `cryptography.fernet` with custom key |
| **Passwords** | bcrypt | `passlib.hash.bcrypt` (12 rounds) |
| **API Tokens** | SHA-256 | Only hash stored, never plaintext |
| **JWT** | HS256 | `python-jose` with 256-bit secret |

---

## 🔧 TASK DETTAGLIATI

### T12: Implementare EncryptionService (AES-256-GCM)

**Requisiti:**
- Creare `src/openrouter_monitor/services/encryption.py`
- Implementare classe `EncryptionService`
- Usare `cryptography.fernet` per AES-256-GCM
- Key derivation con PBKDF2HMAC (SHA256, 100000 iterations)
- Metodi: `encrypt(plaintext: str) -> str`, `decrypt(ciphertext: str) -> str`
- Gestire eccezioni con messaggi chiari

**Implementazione Riferimento:**
```python
from cryptography.fernet import Fernet
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
import base64
import os

class EncryptionService:
    def __init__(self, master_key: str):
        self._fernet = self._derive_key(master_key)
    
    def _derive_key(self, master_key: str) -> Fernet:
        kdf = PBKDF2HMAC(
            algorithm=hashes.SHA256(),
            length=32,
            salt=os.urandom(16),  # ATTENZIONE: salt deve essere fisso per decrittazione!
            iterations=100000,
        )
        key = base64.urlsafe_b64encode(kdf.derive(master_key.encode()))
        return Fernet(key)
```

**⚠️ NOTA CRITICA:** Il salt deve essere fisso (derivato da master_key) oppure salvato insieme al ciphertext, altrimenti la decrittazione fallisce. Usa approccio: `salt + ciphertext` oppure deriva salt deterministico da master_key.

**Test richiesti:**
- Test inizializzazione con master key valida
- Test encrypt/decrypt roundtrip
- Test ciphertext diverso da plaintext
- Test decrittazione fallisce con chiave sbagliata
- Test gestione eccezioni (InvalidToken)

---

### T13: Implementare Password Hashing (bcrypt)

**Requisiti:**
- Creare `src/openrouter_monitor/services/password.py`
- Usare `passlib.context.CryptContext` con bcrypt
- 12 rounds (default sicuro)
- Funzioni: `hash_password(password: str) -> str`, `verify_password(plain: str, hashed: str) -> bool`
- Validazione password: min 12 chars, uppercase, lowercase, digit, special char

**Implementazione Riferimento:**
```python
from passlib.context import CryptContext

pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")

def hash_password(password: str) -> str:
    return pwd_context.hash(password)

def verify_password(plain_password: str, hashed_password: str) -> bool:
    return pwd_context.verify(plain_password, hashed_password)
```

**Test richiesti:**
- Test hash_password genera hash diverso ogni volta
- Test verify_password ritorna True con password corretta
- Test verify_password ritorna False con password sbagliata
- Test validazione password strength
- Test hash è sempre valido per bcrypt

---

### T14: Implementare JWT Utilities

**Requisiti:**
- Creare `src/openrouter_monitor/services/jwt.py`
- Usare `python-jose` con algoritmo HS256
- Funzioni:
  - `create_access_token(data: dict, expires_delta: timedelta | None = None) -> str`
  - `decode_access_token(token: str) -> dict`
  - `verify_token(token: str) -> TokenData`
- JWT payload: `sub` (user_id), `exp` (expiration), `iat` (issued at)
- Gestire eccezioni: JWTError, ExpiredSignatureError
- Leggere SECRET_KEY da config

**Implementazione Riferimento:**
```python
from jose import JWTError, jwt
from datetime import datetime, timedelta

SECRET_KEY = settings.secret_key
ALGORITHM = "HS256"
ACCESS_TOKEN_EXPIRE_HOURS = 24

def create_access_token(data: dict, expires_delta: timedelta | None = None):
    to_encode = data.copy()
    expire = datetime.utcnow() + (expires_delta or timedelta(hours=ACCESS_TOKEN_EXPIRE_HOURS))
    to_encode.update({"exp": expire})
    return jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)

def decode_access_token(token: str) -> dict:
    return jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
```

**Test richiesti:**
- Test create_access_token genera token valido
- Test decode_access_token estrae payload corretto
- Test token scaduto ritorna errore
- Test token con firma invalida ritorna errore
- Test token con algoritmo sbagliato ritorna errore
- Test payload contiene exp, sub, iat

---

### T15: Implementare API Token Generation

**Requisiti:**
- Creare `src/openrouter_monitor/services/token.py`
- Implementare `generate_api_token() -> tuple[str, str]`
- Token format: `or_api_` + 48 chars random (url-safe base64)
- Hash: SHA-256 dell'intero token
- Solo l'hash viene salvato nel DB (api_tokens.token_hash)
- Il plaintext viene mostrato una sola volta al momento della creazione
- Funzione `verify_api_token(plaintext: str, token_hash: str) -> bool`

**Implementazione Riferimento:**
```python
import secrets
import hashlib

def generate_api_token() -> tuple[str, str]:
    token = "or_api_" + secrets.token_urlsafe(48)  # ~64 chars total
    token_hash = hashlib.sha256(token.encode()).hexdigest()
    return token, token_hash

def verify_api_token(plaintext: str, token_hash: str) -> bool:
    computed_hash = hashlib.sha256(plaintext.encode()).hexdigest()
    return secrets.compare_digest(computed_hash, token_hash)
```

**Test richiesti:**
- Test generate_api_token ritorna (plaintext, hash)
- Test token inizia con "or_api_"
- Test hash è SHA-256 valido (64 hex chars)
- Test verify_api_token True con token valido
- Test verify_api_token False con token invalido
- Test timing attack resistance (compare_digest)

---

### T16: Scrivere Test per Servizi di Sicurezza

**Requisiti:**
- Creare test completi per tutti i servizi:
  - `tests/unit/services/test_encryption.py`
  - `tests/unit/services/test_password.py`
  - `tests/unit/services/test_jwt.py`
  - `tests/unit/services/test_token.py`
- Coverage >= 90% per ogni servizio
- Test casi limite e errori
- Test integrazione tra servizi (es. encrypt + save + decrypt)

**Test richiesti per ogni servizio:**
- Unit test per ogni funzione pubblica
- Test casi successo
- Test casi errore (eccezioni)
- Test edge cases (stringhe vuote, caratteri speciali, unicode)

---

## 🔄 WORKFLOW TDD OBBLIGATORIO

Per OGNI task (T12-T16):

```
┌─────────────────────────────────────────┐
│  1. RED - Scrivi il test che fallisce   │
│     • Test prima del codice             │
│     • Pattern AAA (Arrange-Act-Assert)  │
│     • Nomi descrittivi                  │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│  2. GREEN - Implementa codice minimo    │
│     • Solo codice necessario per test   │
│     • Nessun refactoring ancora         │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│  3. REFACTOR - Migliora il codice       │
│     • Pulisci duplicazioni              │
│     • Migliora nomi variabili           │
│     • Test rimangono verdi              │
└─────────────────────────────────────────┘
```

---

## 📁 STRUTTURA FILE DA CREARE

```
src/openrouter_monitor/
└── services/
    ├── __init__.py               # Esporta tutti i servizi
    ├── encryption.py             # T12 - AES-256-GCM
    ├── password.py               # T13 - bcrypt
    ├── jwt.py                    # T14 - JWT utilities
    └── token.py                  # T15 - API token generation

tests/unit/services/
├── __init__.py
├── test_encryption.py            # T12 + T16
├── test_password.py              # T13 + T16
├── test_jwt.py                   # T14 + T16
└── test_token.py                 # T15 + T16
```

---

## 🧪 REQUISITI TEST

### Pattern AAA (Arrange-Act-Assert)

```python
@pytest.mark.unit
def test_encrypt_decrypt_roundtrip_returns_original():
    # Arrange
    service = EncryptionService("test-key-32-chars-long!!")
    plaintext = "sensitive-api-key-12345"
    
    # Act
    encrypted = service.encrypt(plaintext)
    decrypted = service.decrypt(encrypted)
    
    # Assert
    assert decrypted == plaintext
    assert encrypted != plaintext
```

### Marker Pytest

```python
@pytest.mark.unit              # Logica pura
@pytest.mark.security          # Test sicurezza
@pytest.mark.slow              # Test lenti (bcrypt)
```

### Fixtures Condivise (in conftest.py)

```python
@pytest.fixture
def encryption_service():
    return EncryptionService("test-encryption-key-32bytes")

@pytest.fixture
def sample_password():
    return "SecurePass123!@#"

@pytest.fixture
def jwt_secret():
    return "jwt-secret-key-32-chars-long!!"
```

---

## 🛡️ VINCOLI TECNICI

### EncryptionService Requirements

```python
class EncryptionService:
    """AES-256-GCM encryption for sensitive data (API keys)."""
    
    def __init__(self, master_key: str):
        """Initialize with master key (min 32 chars recommended)."""
        
    def encrypt(self, plaintext: str) -> str:
        """Encrypt plaintext, return base64-encoded ciphertext."""
        
    def decrypt(self, ciphertext: str) -> str:
        """Decrypt ciphertext, return plaintext."""
        
    def _derive_key(self, master_key: str) -> Fernet:
        """Derive Fernet key from master key."""
```

### Password Service Requirements

```python
from passlib.context import CryptContext

pwd_context = CryptContext(
    schemes=["bcrypt"],
    deprecated="auto",
    bcrypt__rounds=12  # Esplicito per chiarezza
)

def hash_password(password: str) -> str:
    """Hash password with bcrypt (12 rounds)."""
    
def verify_password(plain_password: str, hashed_password: str) -> bool:
    """Verify password against hash."""
    
def validate_password_strength(password: str) -> bool:
    """Validate password complexity. Min 12 chars, upper, lower, digit, special."""
```

### JWT Service Requirements

```python
from jose import jwt, JWTError
from datetime import datetime, timedelta

def create_access_token(
    data: dict,
    expires_delta: timedelta | None = None
) -> str:
    """Create JWT access token."""
    
def decode_access_token(token: str) -> dict:
    """Decode and validate JWT token."""
    
def verify_token(token: str) -> TokenData:
    """Verify token and return TokenData."""
```

### API Token Service Requirements

```python
import secrets
import hashlib

def generate_api_token() -> tuple[str, str]:
    """Generate API token. Returns (plaintext, hash)."""
    
def verify_api_token(plaintext: str, token_hash: str) -> bool:
    """Verify API token against hash (timing-safe)."""
    
def hash_token(plaintext: str) -> str:
    """Hash token with SHA-256."""
```

---

## 📊 AGGIORNAMENTO PROGRESS

Dopo ogni task completato, aggiorna:
`/home/google/Sources/LucaSacchiNet/openrouter-watcher/export/progress.md`

Esempio:
```markdown
### 🔐 Security Services (T12-T16)

- [x] T12: EncryptionService (AES-256) - Completato [timestamp]
- [x] T13: Password Hashing (bcrypt) - Completato [timestamp]
- [ ] T14: JWT Utilities - In progress
- [ ] T15: API Token Generation
- [ ] T16: Security Tests

**Progresso sezione:** 40% (2/5 task)
**Progresso totale:** 18% (13/74 task)
```

---

## ✅ CRITERI DI ACCETTAZIONE

- [ ] T12: EncryptionService funzionante con AES-256-GCM
- [ ] T13: Password hashing con bcrypt (12 rounds) + validation
- [ ] T14: JWT utilities con create/decode/verify
- [ ] T15: API token generation con SHA-256 hash
- [ ] T16: Test completi per tutti i servizi (coverage >= 90%)
- [ ] Tutti i test passano (`pytest tests/unit/services/`)
- [ ] Nessuna password/token in plaintext nei log
- [ ] 5 commit atomici (uno per task)
- [ ] progress.md aggiornato con tutti i task completati

---

## 🚀 COMANDO DI VERIFICA

Al termine, esegui:
```bash
cd /home/google/Sources/LucaSacchiNet/openrouter-watcher
pytest tests/unit/services/ -v --cov=src/openrouter_monitor/services

# Verifica coverage >= 90%
pytest tests/unit/services/ --cov-report=term-missing
```

---

## 🔒 CONSIDERAZIONI SICUREZZA

### Do's ✅
- Usare `secrets` module per token random
- Usare `secrets.compare_digest` per confronti timing-safe
- Usare bcrypt con 12+ rounds
- Validare sempre input prima di processare
- Gestire eccezioni senza leakare informazioni sensibili
- Loggare operazioni di sicurezza (non dati sensibili)

### Don'ts ❌
- MAI loggare password o token in plaintext
- MAI usare RNG non crittografico (`random` module)
- MAI hardcodare chiavi segrete
- MAI ignorare eccezioni di decrittazione
- MAI confrontare hash con `==` (usa compare_digest)

---

## 📝 NOTE

- Usa SEMPRE path assoluti: `/home/google/Sources/LucaSacchiNet/openrouter-watcher/`
- Segui le convenzioni in `.opencode/agents/tdd-developer.md`
- Task devono essere verificabili in < 2 ore ciascuno
- Documenta bug complessi in `/docs/bug_ledger.md`
- Usa conventional commits: `feat(security): T12 implement AES-256 encryption service`

**AGENTE:** @tdd-developer  
**INIZIA CON:** T12 - EncryptionService