add developer documentation and custom rate limiter with banning

Add a comprehensive guide for developers transitioning from Node/PHP and implement a new middleware to handle IP-based rate limiting with temporary banning functionality. Also refactors configuration loading to use a singleton pattern for better resource management.
2026-03-23 19:10:29 +01:00
parent be53f2ab47
commit 9cc0f3157c
6 changed files with 1064 additions and 1 deletions
--- a/DOCS.md
+++ b/DOCS.md
@@ -0,0 +1,896 @@
+# EMLy API — Documentazione per sviluppatori Node/PHP
+
+Questa guida spiega l'intera architettura dell'API **emly-api-go** assumendo che tu conosca Node.js (Express/Fastify) o PHP (Laravel/Slim), ma che non abbia mai scritto Go.
+
+---
+
+## Indice
+
+1. [Go per chi viene da Node/PHP](#1-go-per-chi-viene-da-nodephp)
+2. [Struttura del progetto](#2-struttura-del-progetto)
+3. [Setup e avvio](#3-setup-e-avvio)
+4. [go-chi: il router](#4-go-chi-il-router)
+5. [Middleware](#5-middleware)
+6. [Handler (i controller)](#6-handler-i-controller)
+7. [Modelli e database](#7-modelli-e-database)
+8. [Sistema di autenticazione](#8-sistema-di-autenticazione)
+9. [Migrazioni del database](#9-migrazioni-del-database)
+10. [Endpoints API completi](#10-endpoints-api-completi)
+11. [Come aggiungere un nuovo endpoint](#11-come-aggiungere-un-nuovo-endpoint)
+
+---
+
+## 1. Go per chi viene da Node/PHP
+
+### Analogie rapide
+
+| Concetto               | Node/Express          | PHP/Laravel         | Go (questo progetto)              |
+|------------------------|-----------------------|---------------------|-----------------------------------|
+| Entry point            | `index.js`            | `public/index.php`  | `main.go`                         |
+| Router                 | Express, Fastify      | Router Laravel      | `go-chi/chi`                      |
+| Middleware             | `app.use(...)`        | Middleware Laravel  | `r.Use(...)`                      |
+| Controller             | `req, res` function   | Controller class    | `http.HandlerFunc`                |
+| ORM / Query builder    | Sequelize, Knex       | Eloquent            | `sqlx` (query raw con struct)     |
+| `.env`                 | `dotenv`              | `vlucas/phpdotenv`  | `joho/godotenv`                   |
+| Tipi / interfacce      | TypeScript interfaces | PHP types           | `struct`                          |
+| `package.json`         | `package.json`        | `composer.json`     | `go.mod`                          |
+| Hot reload             | `nodemon`             | N/A                 | `air`                             |
+
+### Differenze chiave da tenere a mente
+
+**Go compila tutto in un singolo binario.** Non c'e' un runtime separato come Node. Il risultato di `go build` e' un `.exe` (o file ELF su Linux) che contiene tutto: il server, i template, le query SQL — tutto embedded.
+
+**Niente `null` implicito.** In Go ogni variabile ha sempre un valore di default (0, "", false, nil). Gli errori si gestiscono con valori di ritorno, non con eccezioni:
+
+```go
+// Node
+try {
+  const result = await db.query(sql)
+} catch (err) {
+  console.error(err)
+}
+
+// Go
+result, err := db.QueryContext(ctx, sql)
+if err != nil {
+    // gestisci l'errore
+    return
+}
+```
+
+**I package sono come i moduli ES.** Il nome del package in cima al file (es. `package handlers`) e' l'equivalente di un namespace. Le funzioni con la prima lettera maiuscola (`CreateBugReport`) sono pubbliche (exported); quelle minuscole (`jsonError`) sono private al package.
+
+**Le funzioni ritornano valori multipli.** In Go e' normale avere `(result, error)` come return type. Non ci sono Promise; il codice e' sincrono (il parallelismo si fa con goroutine, non usate direttamente in questo progetto).
+
+**I `struct` sono i "model".** Non ci sono classi in Go. Uno `struct` con tag `db:"..."` e `json:"..."` funziona sia da schema DB (come un Model Eloquent) che da DTO JSON.
+
+---
+
+## 2. Struttura del progetto
+
+```
+emly-api-go/
+├── main.go                          # Entry point: boot server, DB, middleware globali
+├── go.mod                           # Dipendenze (come package.json)
+├── .env                             # Variabili d'ambiente locali
+│
+└── internal/                        # Codice privato dell'applicazione
+    ├── config/
+    │   └── config.go                # Carica env vars in una struct Config
+    │
+    ├── database/
+    │   ├── database.go              # Apre la connessione MySQL (pool)
+    │   └── schema/
+    │       ├── migrator.go          # Sistema di migration condizionali
+    │       ├── init.sql             # Schema base (CREATE TABLE IF NOT EXISTS)
+    │       └── migrations/
+    │           ├── tasks.json       # Definisce le migration con condizioni
+    │           ├── 1_bug_reports.sql
+    │           └── 2_users.sql
+    │
+    ├── handlers/                    # I "controller" — una funzione per endpoint
+    │   ├── response.go              # Helper: jsonOK, jsonCreated, jsonError
+    │   ├── health.route.go          # GET /v1/health
+    │   ├── bug_report.route.go      # Tutti gli endpoint /bug-reports
+    │   ├── admin_auth.route.go      # Login, validate, logout
+    │   ├── admin_users.route.go     # CRUD utenti admin
+    │   └── templates/
+    │       └── report.txt.tmpl      # Template testo per il file ZIP
+    │
+    ├── middleware/
+    │   ├── apikey.go                # Verifica header X-API-Key
+    │   └── adminKey.go              # Verifica header X-Admin-Key
+    │
+    ├── models/                      # Struct che mappano le tabelle DB e i JSON
+    │   ├── bug_report.go
+    │   ├── bug_report_file.go
+    │   ├── user.go
+    │   ├── session.go
+    │   └── rate_limit_hwid.go
+    │
+    └── routes/
+        ├── routes.go                # Monta i sub-router sul router root
+        └── v1/
+            ├── v1.go                # Crea il router /v1 con middleware globale v1
+            ├── bug_reports.go       # Registra le rotte /bug-reports
+            └── admin.go             # Registra le rotte /admin
+```
+
+### Perche' `internal/`?
+
+In Go, tutto cio' che sta dentro `internal/` non puo' essere importato da progetti esterni. E' una convenzione per dire "questo codice e' implementazione privata, non una libreria pubblica". Equivale a non esportare un modulo in Node.
+
+---
+
+## 3. Setup e avvio
+
+### Prerequisiti
+
+- Go 1.21+
+- MySQL 8+
+- `air` per hot-reload in sviluppo: `go install github.com/air-verse/air@latest`
+
+### Configurazione `.env`
+
+Copia `.env.example` in `.env`:
+
+```env
+PORT=8080
+
+# DSN MySQL — DEVE includere parseTime=true&loc=UTC
+DB_DSN=root:secret@tcp(127.0.0.1:3306)/emly?parseTime=true&loc=UTC
+DATABASE_NAME=emly
+
+# Chiavi di autenticazione
+API_KEY=la-tua-api-key
+ADMIN_KEY=la-tua-admin-key
+
+# Pool di connessioni (opzionali, hanno default)
+DB_MAX_OPEN_CONNS=30
+DB_MAX_IDLE_CONNS=5
+DB_CONN_MAX_LIFETIME=5
+```
+
+### Comandi
+
+```bash
+# Sviluppo con hot-reload (come nodemon)
+air
+
+# Build binario di produzione
+go build -o ./build/emly-api.exe .
+
+# Avvio diretto senza build
+go run .
+
+# Test
+go test ./...
+go test ./internal/... -run NomeTest -v
+```
+
+### Cosa succede all'avvio
+
+1. Carica `.env` (se presente)
+2. Legge la config dalle env vars
+3. Apre il pool di connessioni MySQL
+4. Esegue le migrazioni (vedi sezione 9)
+5. Crea il router chi e registra tutti i middleware e le rotte
+6. Avvia il server HTTP su `PORT`
+
+---
+
+## 4. go-chi: il router
+
+`go-chi/chi` e' l'equivalente di Express.js per Go. E' un router HTTP leggero e componibile.
+
+### Analogia Express → Chi
+
+```javascript
+// Express
+const app = express()
+app.use(morgan('dev'))
+app.get('/users/:id', (req, res) => { ... })
+```
+
+```go
+// Chi
+r := chi.NewRouter()
+r.Use(middleware.Logger)
+r.Get("/users/{id}", func(w http.ResponseWriter, r *http.Request) { ... })
+```
+
+### Differenze nella sintassi dei parametri
+
+| Express       | Chi           |
+|---------------|---------------|
+| `/users/:id`  | `/users/{id}` |
+| `req.params.id` | `chi.URLParam(r, "id")` |
+| `req.query.page` | `r.URL.Query().Get("page")` |
+| `req.body`    | `r.Body` (letto con `json.NewDecoder`) |
+| `req.headers` | `r.Header.Get("X-API-Key")` |
+
+### API principali di chi
+
+#### `chi.NewRouter()`
+Crea un nuovo router. Equivale a `express()` o `new Slim\App()`.
+
+```go
+r := chi.NewRouter()
+```
+
+#### `r.Use(middleware)`
+Aggiunge un middleware globale al router (o al gruppo corrente). L'ordine conta: vengono eseguiti nell'ordine di registrazione.
+
+```go
+r.Use(middleware.Logger)    // loga ogni richiesta
+r.Use(middleware.Recoverer) // cattura i panic (come un try/catch globale)
+```
+
+#### Metodi HTTP: `r.Get`, `r.Post`, `r.Patch`, `r.Delete`
+
+```go
+r.Get("/health", handlers.Health(db))
+r.Post("/bug-reports/", handlers.CreateBugReport(db))
+r.Patch("/bug-reports/{id}/status", handlers.PatchBugReportStatus(db))
+r.Delete("/bug-reports/{id}", handlers.DeleteBugReportByID(db))
+```
+
+#### `r.Route(pattern, fn)` — Gruppo con prefisso
+
+Crea un sotto-gruppo con un prefisso comune. Equivale a `express.Router()` o ai route group di Laravel.
+
+```go
+// Tutte le rotte dentro la funzione avranno il prefisso /bug-reports
+r.Route("/bug-reports", func(r chi.Router) {
+    r.Get("/", handlers.GetAllBugReports(db))
+    r.Get("/{id}", handlers.GetBugReportByID(db))
+})
+```
+
+#### `r.Group(fn)` — Gruppo senza prefisso
+
+Crea un gruppo di rotte che condividono middleware, ma senza aggiungere un prefisso al path. Utile per applicare auth diversa a rotte dello stesso livello.
+
+```go
+r.Route("/bug-reports", func(r chi.Router) {
+
+    // Gruppo 1: solo API key
+    r.Group(func(r chi.Router) {
+        r.Use(apimw.APIKeyAuth(db))
+        r.Get("/count", handlers.GetReportsCount(db))
+        r.Post("/", handlers.CreateBugReport(db))
+    })
+
+    // Gruppo 2: API key + Admin key
+    r.Group(func(r chi.Router) {
+        r.Use(apimw.APIKeyAuth(db))
+        r.Use(apimw.AdminKeyAuth(db))
+        r.Get("/", handlers.GetAllBugReports(db))
+        r.Delete("/{id}", handlers.DeleteBugReportByID(db))
+    })
+})
+```
+
+#### `r.Mount(pattern, handler)` — Monta un sub-router
+
+Incolla un router separato su un prefisso. Permette di dividere le rotte in file diversi mantenendo tutto componibile. Equivale a `app.use('/v1', v1Router)` in Express.
+
+```go
+// routes.go
+r.Mount("/v1", v1.NewRouter(db))
+```
+
+#### `chi.URLParam(r, "name")` — Legge i parametri di percorso
+
+```go
+// Rotta: /bug-reports/{id}
+id := chi.URLParam(r, "id") // es. "42"
+```
+
+### Middleware built-in di chi (`go-chi/chi/v5/middleware`)
+
+Questi sono tutti usati in `main.go`:
+
+| Middleware               | Equivalente Node/Laravel              | Cosa fa                                                   |
+|--------------------------|---------------------------------------|-----------------------------------------------------------|
+| `middleware.RequestID`   | `express-request-id`                  | Aggiunge un UUID univoco `X-Request-Id` ad ogni richiesta |
+| `middleware.RealIP`      | `express-ip` / `TrustProxies`         | Legge l'IP reale da `X-Forwarded-For` o `X-Real-IP`       |
+| `middleware.Logger`      | `morgan`                              | Loga metodo, path, status, durata su stdout               |
+| `middleware.Recoverer`   | Express error handler / `rescue_from`  | Cattura i panic e ritorna 500 invece di crashare          |
+| `middleware.Timeout(30s)`| `connect-timeout`                     | Cancella la richiesta se supera i 30 secondi              |
+
+### Rate limiting (`go-chi/httprate`)
+
+```go
+// main.go — globale: max 100 req/min per IP
+r.Use(httprate.LimitByIP(100, time.Minute))
+
+// nelle rotte — per gruppo: max 30 req/min per IP
+r.Use(httprate.LimitByIP(30, time.Minute))
+```
+
+---
+
+## 5. Middleware
+
+In questo progetto i middleware custom si trovano in `internal/middleware/`. Un middleware in Go e' una funzione che prende un `http.Handler` e restituisce un `http.Handler`.
+
+**Concettualmente identico a Express:**
+
+```javascript
+// Express
+function apiKeyAuth(req, res, next) {
+    if (req.headers['x-api-key'] !== process.env.API_KEY) {
+        return res.status(401).json({ error: 'unauthorized' })
+    }
+    next()
+}
+```
+
+```go
+// Go/Chi
+func APIKeyAuth(_ *sqlx.DB) func(http.Handler) http.Handler {
+    // Questo blocco gira UNA VOLTA sola all'avvio (come costruttore)
+    allowed := map[string]struct{}{cfg.APIKey: {}}
+
+    return func(next http.Handler) http.Handler {
+        // Questo ritorna il middleware vero e proprio
+        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+            key := r.Header.Get("X-API-Key")
+            if _, ok := allowed[key]; !ok {
+                w.WriteHeader(http.StatusUnauthorized)
+                json.NewEncoder(w).Encode(map[string]string{"error": "unauthorized"})
+                return // equivale a NON chiamare next()
+            }
+            next.ServeHTTP(w, r) // equivale a next()
+        })
+    }
+}
+```
+
+### Middleware disponibili
+
+| Middleware       | Header richiesto  | Applicato a                                           |
+|------------------|-------------------|-------------------------------------------------------|
+| `APIKeyAuth`     | `X-API-Key`       | Tutti gli endpoint `/v1/api/bug-reports/*`            |
+| `AdminKeyAuth`   | `X-Admin-Key`     | Endpoint admin bug-reports + `/v1/api/admin/users/*`  |
+
+---
+
+## 6. Handler (i controller)
+
+Gli handler sono in `internal/handlers/`. Ogni file corrisponde a una risorsa (es. `bug_report.route.go`).
+
+### Pattern factory function
+
+Gli handler NON sono funzioni dirette. Sono **factory functions** che ricevono `*sqlx.DB` e restituiscono l'handler vero. Questo permette di iniettare la dipendenza del database senza variabili globali.
+
+```go
+// Definizione
+func CreateBugReport(db *sqlx.DB) http.HandlerFunc {
+    return func(w http.ResponseWriter, r *http.Request) {
+        // qui hai accesso a `db` tramite closure
+    }
+}
+
+// Utilizzo nel router
+r.Post("/", handlers.CreateBugReport(db))
+```
+
+**Analogo Node sarebbe:**
+
+```javascript
+function createBugReport(db) {
+    return async (req, res) => {
+        // uso db
+    }
+}
+app.post('/', createBugReport(db))
+```
+
+### Response helpers (`response.go`)
+
+Tre funzioni usate in tutti gli handler per rispondere in JSON:
+
+```go
+jsonOK(w, payload)        // HTTP 200 + JSON
+jsonCreated(w, payload)   // HTTP 201 + JSON
+jsonError(w, status, msg) // HTTP <status> + { "error": "msg" }
+```
+
+### Leggere il body JSON
+
+```go
+// In Go (come json.parse in Node)
+var body struct {
+    Username string `json:"username"`
+    Password string `json:"password"`
+}
+if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+    jsonError(w, http.StatusBadRequest, "invalid JSON: "+err.Error())
+    return
+}
+```
+
+### Leggere query string
+
+```go
+page := r.URL.Query().Get("page")   // ?page=2
+status := r.URL.Query().Get("status") // ?status=new
+```
+
+### Upload multipart (form-data)
+
+```go
+// Legge fino a 32MB in memoria
+r.ParseMultipartForm(32 << 20)
+
+name := r.FormValue("name")           // campo testo
+file, header, err := r.FormFile("screenshot") // file upload
+```
+
+---
+
+## 7. Modelli e database
+
+### I modelli (`internal/models/`)
+
+I modelli sono semplici struct con tag speciali. Non c'e' ORM: le query sono SQL raw.
+
+```go
+type BugReport struct {
+    ID          uint64          `db:"id"          json:"id"`
+    Name        string          `db:"name"        json:"name"`
+    Email       string          `db:"email"       json:"email"`
+    // json:"-" significa: NON includere mai questo campo nella risposta JSON
+    PasswordHash string         `db:"password_hash" json:"-"`
+}
+```
+
+- `db:"nome_colonna"` — mappa la colonna SQL al campo Go (usato da `sqlx`)
+- `json:"nome_campo"` — mappa il campo Go alla chiave JSON (usato da `encoding/json`)
+- `json:"-"` — campo nascosto nelle risposte JSON (es. `password_hash`, `data` dei file)
+- `json:"campo,omitempty"` — il campo viene omesso dal JSON se e' zero/nil
+
+### sqlx — Query database
+
+`sqlx` e' un wrapper sottile su `database/sql`. Non e' un ORM: si scrive SQL a mano e si mappa il risultato su struct.
+
+```go
+// Legge UNA riga in una struct (GetContext)
+// Equivale a: db.query('SELECT ... WHERE id = ?', [id]).then(rows => rows[0])
+var report models.BugReport
+err := db.GetContext(r.Context(), &report,
+    "SELECT * FROM bug_reports WHERE id = ?", id)
+if errors.Is(err, sql.ErrNoRows) {
+    // nessun risultato trovato
+}
+
+// Legge PIU' righe in uno slice (SelectContext)
+// Equivale a: db.query('SELECT ...').then(rows => rows)
+var reports []models.BugReport
+err := db.SelectContext(r.Context(), &reports,
+    "SELECT * FROM bug_reports ORDER BY created_at DESC")
+
+// Esegue INSERT/UPDATE/DELETE (ExecContext)
+result, err := db.ExecContext(r.Context(),
+    "INSERT INTO bug_reports (name, email) VALUES (?, ?)", name, email)
+reportID, _ := result.LastInsertId()
+rowsAffected, _ := result.RowsAffected()
+```
+
+**Perche' `r.Context()`?** Il context trasporta la deadline di timeout (30s impostata in `main.go`). Se la richiesta viene cancellata (timeout o client disconnect), la query SQL viene interrotta automaticamente. E' come `AbortController` in Node ma automatico.
+
+### Tipi custom (enum-like)
+
+Go non ha enum. Si usa un `type` su `string` con costanti:
+
+```go
+type BugReportStatus string
+
+const (
+    BugReportStatusNew      BugReportStatus = "new"
+    BugReportStatusInReview BugReportStatus = "in_review"
+    BugReportStatusResolved BugReportStatus = "resolved"
+    BugReportStatusClosed   BugReportStatus = "closed"
+)
+```
+
+---
+
+## 8. Sistema di autenticazione
+
+L'API ha **due livelli di autenticazione separati**, entrambi header-based (niente cookie, niente JWT per le rotte API).
+
+### Livello 1: API Key (`X-API-Key`)
+
+Usata da client esterni (es. l'applicazione desktop) per inviare bug report.
+
+```
+X-API-Key: la-tua-api-key
+```
+
+Il valore e' configurato in `.env` come `API_KEY`. Il middleware `APIKeyAuth` carica la chiave in una mappa all'avvio e fa un lookup O(1) ad ogni richiesta.
+
+### Livello 2: Admin Key (`X-Admin-Key`)
+
+Usata per accedere agli endpoint di sola lettura/scrittura amministrativa.
+
+```
+X-Admin-Key: la-tua-admin-key
+```
+
+Il valore e' configurato in `.env` come `ADMIN_KEY`.
+
+### Livello 3: Sessione utente (`X-Session-Token`)
+
+Gli endpoint `/v1/api/admin/auth/*` gestiscono login/logout di utenti admin con sessioni su database.
+
+**Flusso login:**
+
+```
+POST /v1/api/admin/auth/login
+Body: { "username": "...", "password": "..." }
+
+Response: {
+  "session_id": "<64-char hex token>",
+  "user": { "id": "...", "username": "...", "role": "admin", ... }
+}
+```
+
+**Flusso validate:**
+
+```
+GET /v1/api/admin/auth/validate
+Headers: X-Session-Token: <session_id>
+
+Response: { "success": true, "user": { ... } }
+```
+
+**Flusso logout:**
+
+```
+POST /v1/api/admin/auth/logout
+Headers: X-Session-Token: <session_id>
+```
+
+**Dettagli implementativi:**
+- Password hashed con **argon2id** (formato PHC, compatibile con `@node-rs/argon2`)
+- Sessioni salvate in tabella `session` con scadenza a **30 giorni**
+- Le sessioni scadute vengono eliminate automaticamente alla prima validazione fallita
+- UUID utenti generati con `crypto/rand` (UUID v4)
+- Session ID: 32 byte random, encoded come hex (64 caratteri)
+
+---
+
+## 9. Migrazioni del database
+
+Il sistema di migration e' custom e si trova in `internal/database/schema/`. Non usa librerie esterne come `golang-migrate`.
+
+### Come funziona
+
+All'avvio, `schema.Migrate(db, cfg.Database)` esegue questi passi:
+
+1. **Controlla se il database e' vuoto** — Se non ci sono tabelle, esegue `init.sql` che crea tutto lo schema base con `CREATE TABLE IF NOT EXISTS`.
+
+2. **Controlla le tabelle attese** — Se il DB non e' vuoto ma mancano tabelle, riesegue `init.sql`.
+
+3. **Esegue le migration condizionali** — Legge `migrations/tasks.json` e per ogni task valuta le condizioni. Un task viene eseguito solo se almeno una condizione e' vera.
+
+### `tasks.json` — Definizione migration
+
+```json
+{
+  "tasks": [
+    {
+      "id": "1_bug_reports",
+      "sql_file": "1_bug_reports.sql",
+      "description": "Add hostname, os_user columns and their indexes to bug_reports.",
+      "conditions": [
+        { "type": "column_not_exists", "table": "bug_reports", "column": "hostname" },
+        { "type": "column_not_exists", "table": "bug_reports", "column": "os_user" }
+      ]
+    }
+  ]
+}
+```
+
+### Tipi di condizione supportati
+
+| Tipo                | Esegui la migration se...                          |
+|---------------------|----------------------------------------------------|
+| `column_not_exists` | la colonna non esiste nella tabella                |
+| `column_exists`     | la colonna esiste nella tabella                    |
+| `index_not_exists`  | l'indice non esiste nella tabella                  |
+| `index_exists`      | l'indice esiste nella tabella                      |
+| `table_not_exists`  | la tabella non esiste nel database                 |
+| `table_exists`      | la tabella esiste nel database                     |
+
+### Come aggiungere una migration
+
+1. Crea il file SQL in `internal/database/schema/migrations/3_nome.sql`
+2. Aggiungi il task in `tasks.json` con le condizioni appropriate
+
+```json
+{
+  "id": "3_nome",
+  "sql_file": "3_nome.sql",
+  "description": "Descrizione della migration.",
+  "conditions": [
+    { "type": "column_not_exists", "table": "bug_reports", "column": "nuova_colonna" }
+  ]
+}
+```
+
+---
+
+## 10. Endpoints API completi
+
+Base URL: `http://localhost:8080`
+
+### Header di autenticazione
+
+| Header            | Richiesto per                                         |
+|-------------------|-------------------------------------------------------|
+| `X-API-Key`       | Tutti gli endpoint `/v1/api/bug-reports/*`            |
+| `X-Admin-Key`     | Endpoint admin bug-reports + `/v1/api/admin/users/*`  |
+| `X-Session-Token` | `/v1/api/admin/auth/validate` e `/logout`             |
+
+---
+
+### Pubblici
+
+#### `GET /`
+Ping. Ritorna il testo `emly-api-go`.
+
+#### `GET /v1/health`
+```json
+{ "status": "ok", "db": "ok" }
+```
+
+---
+
+### Bug Reports — Solo `X-API-Key`
+
+#### `POST /v1/api/bug-reports/`
+Crea un nuovo bug report. Content-Type: `multipart/form-data`.
+
+| Campo         | Tipo   | Obbligatorio | Descrizione                         |
+|---------------|--------|:------------:|-------------------------------------|
+| `name`        | string | si           | Nome del reporter                   |
+| `email`       | string | si           | Email del reporter                  |
+| `description` | string | si           | Descrizione del bug                 |
+| `hwid`        | string | no           | Hardware ID                         |
+| `hostname`    | string | no           | Nome macchina                       |
+| `os_user`     | string | no           | Utente OS                           |
+| `system_info` | string | no           | JSON serializzato con info sistema  |
+| `attachment`  | file   | no           | File allegato generico              |
+| `screenshot`  | file   | no           | Screenshot del bug                  |
+| `log`         | file   | no           | File di log                         |
+
+**Response 201:**
+```json
+{ "success": true, "report_id": 42, "message": "Bug report submitted successfully" }
+```
+
+#### `GET /v1/api/bug-reports/count`
+```json
+{ "count": 128 }
+```
+
+---
+
+### Bug Reports — `X-API-Key` + `X-Admin-Key`
+
+#### `GET /v1/api/bug-reports/`
+Lista paginata con filtri.
+
+| Query param | Default | Descrizione                                              |
+|-------------|---------|----------------------------------------------------------|
+| `page`      | 1       | Numero pagina                                            |
+| `page_size` | 20      | Risultati per pagina (max 100)                          |
+| `status`    | -       | Filtra per stato: `new`, `in_review`, `resolved`, `closed` |
+| `search`    | -       | Cerca in hostname, os_user, name, email                  |
+
+**Response 200:**
+```json
+{
+  "data": [ /* array di BugReportListItem */ ],
+  "total": 128,
+  "page": 1,
+  "page_size": 20,
+  "total_pages": 7
+}
+```
+
+#### `GET /v1/api/bug-reports/{id}`
+Dettaglio singolo report.
+
+#### `GET /v1/api/bug-reports/{id}/status`
+```json
+{ "status": "new" }
+```
+
+#### `PATCH /v1/api/bug-reports/{id}/status`
+Body: stringa raw (non JSON) con il nuovo stato.
+```
+in_review
+```
+
+#### `GET /v1/api/bug-reports/{id}/files`
+Lista dei file allegati al report (senza dati binari).
+
+#### `GET /v1/api/bug-reports/{id}/files/{file_id}`
+Scarica il file specifico. Response con `Content-Type` originale e `Content-Disposition: attachment`.
+
+#### `GET /v1/api/bug-reports/{id}/download`
+Scarica un file `.zip` contenente:
+- `report.txt` — report formattato dal template
+- `screenshot/nome.png`, `log/nome.log`, `attachment/nome.bin` — file allegati organizzati per ruolo
+
+#### `DELETE /v1/api/bug-reports/{id}`
+```json
+{ "message": "bug report deleted successfully" }
+```
+
+---
+
+### Auth Admin — Nessuna chiave richiesta (gestisce le proprie credenziali)
+
+#### `POST /v1/api/admin/auth/login`
+```json
+// Request
+{ "username": "admin", "password": "secret" }
+
+// Response 200
+{
+  "session_id": "a3f9...<64 chars>",
+  "user": { "id": "uuid", "username": "admin", "displayname": "Admin", "role": "admin", "enabled": true }
+}
+```
+
+#### `GET /v1/api/admin/auth/validate`
+Header: `X-Session-Token: <session_id>`
+
+```json
+{ "success": true, "user": { ... } }
+```
+
+#### `POST /v1/api/admin/auth/logout`
+Header: `X-Session-Token: <session_id>`
+```json
+{ "logged_out": true }
+```
+
+---
+
+### Gestione Utenti — Solo `X-Admin-Key`
+
+#### `GET /v1/api/admin/users/`
+Lista tutti gli utenti.
+
+#### `POST /v1/api/admin/users/`
+```json
+// Request
+{ "username": "mario", "displayname": "Mario Rossi", "password": "secret", "role": "user" }
+// Response 201: oggetto User
+```
+
+#### `GET /v1/api/admin/users/{id}`
+
+#### `PATCH /v1/api/admin/users/{id}`
+Aggiorna solo i campi forniti. Campi modificabili: `displayname`, `enabled`.
+```json
+{ "displayname": "Nuovo Nome", "enabled": false }
+```
+
+#### `POST /v1/api/admin/users/{id}/reset-password`
+```json
+{ "password": "nuova-password" }
+```
+
+#### `DELETE /v1/api/admin/users/{id}`
+
+---
+
+### Modello `BugReport`
+
+```json
+{
+  "id": 42,
+  "name": "Mario Rossi",
+  "email": "mario@example.com",
+  "description": "L'app crasha all'avvio",
+  "hwid": "ABC123",
+  "hostname": "DESKTOP-XYZ",
+  "os_user": "mario",
+  "submitter_ip": "192.168.1.1",
+  "system_info": { "os": "Windows 11", "ram": "16GB" },
+  "status": "new",
+  "created_at": "2026-03-23T10:00:00Z",
+  "updated_at": "2026-03-23T10:00:00Z"
+}
+```
+
+**Stati possibili:** `new` → `in_review` → `resolved` / `closed`
+
+### Modello `BugReportFile`
+
+```json
+{
+  "id": 1,
+  "report_id": 42,
+  "file_role": "screenshot",
+  "filename": "crash.png",
+  "mime_type": "image/png",
+  "file_size": 204800,
+  "created_at": "2026-03-23T10:00:00Z"
+}
+```
+
+**Ruoli file:** `attachment`, `screenshot`, `log`
+
+### Modello `User`
+
+```json
+{
+  "id": "uuid-v4",
+  "username": "mario",
+  "displayname": "Mario Rossi",
+  "role": "admin",
+  "enabled": true,
+  "created_at": "2026-03-23T10:00:00Z"
+}
+```
+
+**Nota:** `password_hash` non viene mai esposto nelle risposte JSON (`json:"-"`).
+
+---
+
+## 11. Come aggiungere un nuovo endpoint
+
+Esempio: aggiungere `GET /v1/api/bug-reports/{id}/summary`.
+
+### Step 1 — Scrivi l'handler in `internal/handlers/bug_report.route.go`
+
+```go
+func GetBugReportSummary(db *sqlx.DB) http.HandlerFunc {
+    return func(w http.ResponseWriter, r *http.Request) {
+        id := chi.URLParam(r, "id")
+        if id == "" {
+            jsonError(w, http.StatusBadRequest, "missing id parameter")
+            return
+        }
+
+        // esegui la query...
+        jsonOK(w, map[string]string{"summary": "..."})
+    }
+}
+```
+
+### Step 2 — Registra la rotta in `internal/routes/v1/bug_reports.go`
+
+Aggiungila nel gruppo con le permission corrette:
+
+```go
+r.Group(func(r chi.Router) {
+    r.Use(apimw.APIKeyAuth(db))
+    r.Use(apimw.AdminKeyAuth(db))
+    r.Use(httprate.LimitByIP(30, time.Minute))
+
+    r.Get("/", handlers.GetAllBugReports(db))
+    r.Get("/{id}", handlers.GetBugReportByID(db))
+    r.Get("/{id}/summary", handlers.GetBugReportSummary(db)) // <-- aggiunto qui
+    // ...
+})
+```
+
+### Step 3 — Build e test
+
+```bash
+go build ./...      # verifica che compili
+go test ./...       # esegui i test
+air                 # hot-reload in sviluppo
+```
+
+Non serve nessun file di routing separato, nessun decoratore, nessuna annotation. La rotta e' attiva immediatamente alla ricompilazione.
--- a/go.mod
+++ b/go.mod
@@ -10,7 +10,10 @@ require (
 	golang.org/x/crypto v0.49.0
 )

-require golang.org/x/sys v0.42.0 // indirect
+require (
+	golang.org/x/sys v0.42.0 // indirect
+	golang.org/x/time v0.15.0 // indirect
+)

 require (
 	filippo.io/edwards25519 v1.1.1 // indirect
--- a/go.sum
+++ b/go.sum
@@ -23,3 +23,5 @@ golang.org/x/sync v0.7.0 h1:YsImfSBoP9QPYL0xyKJPq0gcaJdG3rInoqxTWbfQu9M=
 golang.org/x/sync v0.7.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
 golang.org/x/sys v0.42.0 h1:omrd2nAlyT5ESRdCLYdm3+fMfNFE/+Rf4bDIQImRJeo=
 golang.org/x/sys v0.42.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/time v0.15.0 h1:bbrp8t3bGUeFOx08pvsMYRTCVSMk89u4tKbNOZbp88U=
+golang.org/x/time v0.15.0/go.mod h1:Y4YMaQmXwGQZoFaVFk4YpCt4FLQMYKZe9oeV/f4MSno=
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -4,6 +4,7 @@ import (
 	"os"
 	"strconv"
 	"strings"
+	"sync"
 )

 type Config struct {
@@ -17,7 +18,17 @@ type Config struct {
 	ConnMaxLifetime int
 }

+var (
+	instance *Config
+	once     sync.Once
+)
+
 func Load() *Config {
+	once.Do(func() { instance = load() })
+	return instance
+}
+
+func load() *Config {
 	port := os.Getenv("PORT")
 	if port == "" {
 		port = "8080"
--- a/internal/middleware/ratelimit.ban.go
+++ b/internal/middleware/ratelimit.ban.go
@@ -0,0 +1,140 @@
+// middleware/ratelimit.go
+package middleware
+
+import (
+	"net"
+	"net/http"
+	"sync"
+	"time"
+
+	"golang.org/x/time/rate"
+)
+
+type visitor struct {
+	limiter  *rate.Limiter
+	lastSeen time.Time
+	failures int
+}
+
+type RateLimiter struct {
+	mu       sync.Mutex
+	visitors map[string]*visitor
+	banned   sync.Map // ip -> unban time
+
+	// config
+	rps        rate.Limit // richieste/sec normali
+	burst      int
+	maxFails   int           // quanti 429 prima del ban
+	banDur     time.Duration // durata ban
+	cleanEvery time.Duration
+}
+
+func NewRateLimiter(rps float64, burst, maxFails int, banDur time.Duration) *RateLimiter {
+	rl := &RateLimiter{
+		visitors:   make(map[string]*visitor),
+		rps:        rate.Limit(rps),
+		burst:      burst,
+		maxFails:   maxFails,
+		banDur:     banDur,
+		cleanEvery: 5 * time.Minute,
+	}
+	go rl.cleanupLoop()
+	return rl
+}
+
+func (rl *RateLimiter) getIP(r *http.Request) string {
+	// Rispetta X-Forwarded-For se dietro Traefik/proxy
+	if ip := r.Header.Get("X-Real-IP"); ip != "" {
+		return ip
+	}
+	if ip := r.Header.Get("X-Forwarded-For"); ip != "" {
+		// Prendi il primo IP (quello del client originale)
+		if h, _, err := net.SplitHostPort(ip); err == nil {
+			return h
+		}
+		return ip
+	}
+	host, _, _ := net.SplitHostPort(r.RemoteAddr)
+	return host
+}
+
+func (rl *RateLimiter) getVisitor(ip string) *visitor {
+	rl.mu.Lock()
+	defer rl.mu.Unlock()
+
+	v, ok := rl.visitors[ip]
+	if !ok {
+		v = &visitor{
+			limiter: rate.NewLimiter(rl.rps, rl.burst),
+		}
+		rl.visitors[ip] = v
+	}
+	v.lastSeen = time.Now()
+	return v
+}
+
+func (rl *RateLimiter) Handler(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		ip := rl.getIP(r)
+
+		// Controlla ban attivo
+		if unbanAt, banned := rl.banned.Load(ip); banned {
+			if time.Now().Before(unbanAt.(time.Time)) {
+				w.Header().Set("Retry-After", unbanAt.(time.Time).Format(time.RFC1123))
+				http.Error(w, "too many requests - temporarily banned", http.StatusForbidden)
+				return
+			}
+			// Ban scaduto
+			rl.banned.Delete(ip)
+		}
+
+		v := rl.getVisitor(ip)
+
+		if !v.limiter.Allow() {
+			rl.mu.Lock()
+			v.failures++
+			fails := v.failures
+			rl.mu.Unlock()
+
+			if fails >= rl.maxFails {
+				unbanAt := time.Now().Add(rl.banDur)
+				rl.banned.Store(ip, unbanAt)
+				// Opzionale: loga il ban
+				w.Header().Set("Retry-After", unbanAt.Format(time.RFC1123))
+				http.Error(w, "banned", http.StatusForbidden)
+				return
+			}
+
+			http.Error(w, "rate limit exceeded", http.StatusTooManyRequests)
+			return
+		}
+
+		// Reset failures su richiesta legittima
+		rl.mu.Lock()
+		v.failures = 0
+		rl.mu.Unlock()
+
+		next.ServeHTTP(w, r)
+	})
+}
+
+func (rl *RateLimiter) cleanupLoop() {
+	ticker := time.NewTicker(rl.cleanEvery)
+	defer ticker.Stop()
+	for range ticker.C {
+		rl.mu.Lock()
+		for ip, v := range rl.visitors {
+			if time.Since(v.lastSeen) > 10*time.Minute {
+				delete(rl.visitors, ip)
+			}
+		}
+		rl.mu.Unlock()
+		// Pulisci anche i ban scaduti
+		rl.banned.Range(func(k, v any) bool {
+			if time.Now().After(v.(time.Time)) {
+				rl.banned.Delete(k)
+			}
+			return true
+		})
+	}
+}
--- a/main.go
+++ b/main.go
@@ -16,6 +16,8 @@ import (
 	"emly-api-go/internal/database"
 	"emly-api-go/internal/database/schema"
 	"emly-api-go/internal/routes"
+
+	emlyMiddleware "emly-api-go/internal/middleware"
 )

 func main() {
@@ -52,6 +54,15 @@ func main() {
 	// Global rate limit to 100 requests per minute
 	r.Use(httprate.LimitByIP(100, time.Minute))

+	rl := emlyMiddleware.NewRateLimiter(
+		5,              // 5 req/sec per IP
+		10,             // burst fino a 10
+		20,             // ban dopo 20 violazioni
+		30*time.Minute, // ban di 15 minuti
+	)
+
+	r.Use(rl.Handler)
+
 	routes.RegisterAll(r, db)

 	addr := fmt.Sprintf(":%s", cfg.Port)