openrouter-watcher/README.md

OpenRouter API Key Monitor

Applicazione web multi-utente per monitorare l'utilizzo delle API key della piattaforma OpenRouter.

🚀 Caratteristiche

• 🔐 Autenticazione Sicura: Registrazione e login con JWT
• 🔑 Gestione API Key: CRUD completo con cifratura AES-256
• 📊 Dashboard Statistiche: Visualizzazione utilizzo, costi, modelli
• 🔓 API Pubblica: Accesso programmatico con token API
• 📈 Monitoraggio: Tracciamento richieste, token, costi

📋 Requisiti

• Python 3.11+
• SQLite (incluso)
• Docker (opzionale)

🛠️ Installazione

Installazione Locale

# Clona il repository
git clone https://github.com/username/openrouter-watcher.git
cd openrouter-watcher

# Crea virtual environment
python3 -m venv .venv
source .venv/bin/activate  # Linux/Mac
# oppure: .venv\Scripts\activate  # Windows

# Installa dipendenze
pip install -r requirements.txt

# Configura variabili d'ambiente
cp .env.example .env
# Modifica .env con le tue configurazioni

# Esegui migrazioni database
alembic upgrade head

# Avvia applicazione
uvicorn src.openrouter_monitor.main:app --reload

Installazione con Docker

# Avvia con Docker Compose
docker-compose up -d

# L'applicazione sarà disponibile su http://localhost:8000

🔧 Configurazione

Crea un file .env con le seguenti variabili:

# Database
DATABASE_URL=sqlite:///./data/app.db

# Sicurezza (genera con: openssl rand -hex 32)
SECRET_KEY=your-super-secret-jwt-key-min-32-chars
ENCRYPTION_KEY=your-32-byte-encryption-key-here

# OpenRouter
OPENROUTER_API_URL=https://openrouter.ai/api/v1

# Limiti
MAX_API_KEYS_PER_USER=10
MAX_API_TOKENS_PER_USER=5
RATE_LIMIT_REQUESTS=100
RATE_LIMIT_WINDOW=3600

# JWT
JWT_EXPIRATION_HOURS=24

📚 API Endpoints

Autenticazione (JWT)

Metodo	Endpoint	Descrizione
POST	/api/auth/register	Registrazione utente
POST	/api/auth/login	Login utente
POST	/api/auth/logout	Logout utente

Gestione API Keys OpenRouter

Metodo	Endpoint	Descrizione
POST	/api/keys	Aggiungi API key
GET	/api/keys	Lista API keys
PUT	/api/keys/{id}	Aggiorna API key
DELETE	/api/keys/{id}	Elimina API key

Statistiche

Metodo	Endpoint	Descrizione
GET	/api/stats/dashboard	Dashboard statistiche
GET	/api/usage	Dettaglio utilizzo

Gestione Token API

Metodo	Endpoint	Descrizione
POST	/api/tokens	Genera token API
GET	/api/tokens	Lista token
DELETE	/api/tokens/{id}	Revoca token

API Pubblica (Autenticazione con Token API)

Metodo	Endpoint	Descrizione
GET	/api/v1/stats	Statistiche aggregate
GET	/api/v1/usage	Dettaglio utilizzo
GET	/api/v1/keys	Lista API keys con stats

🧪 Test

# Esegui tutti i test
pytest tests/unit/ -v

# Con coverage
pytest tests/unit/ -v --cov=src/openrouter_monitor

# Test specifici
pytest tests/unit/routers/test_auth.py -v
pytest tests/unit/routers/test_api_keys.py -v
pytest tests/unit/routers/test_public_api.py -v

📁 Struttura Progetto

openrouter-watcher/
├── src/openrouter_monitor/    # Codice sorgente
│   ├── schemas/              # Pydantic schemas
│   ├── models/               # SQLAlchemy models
│   ├── routers/              # FastAPI routers
│   ├── services/             # Business logic
│   ├── dependencies/         # FastAPI dependencies
│   └── main.py               # Entry point
├── tests/                     # Test suite
├── docs/                      # Documentazione
├── export/                    # Specifiche e progresso
└── prompt/                    # Prompt per AI agents

🔒 Sicurezza

• Cifratura: API keys cifrate con AES-256-GCM
• Password: Hash con bcrypt (12 rounds)
• Token JWT: Firma HMAC-SHA256
• Token API: Hash SHA-256 nel database
• Rate Limiting: 100 richieste/ora per token

📄 Licenza

MIT License

🤝 Contributing

Contributi sono benvenuti! Segui le linee guida in .opencode/WORKFLOW.md.

📞 Supporto

Per domande o problemi, apri un issue su GitHub.