koa-classic-server 2.6.1 → 3.0.0

package/docs/ACTION_PLAN.md

@@ -0,0 +1,293 @@
+# Piano d'Azione — koa-classic-server
+
+> Documento di lavoro per il miglioramento progressivo del progetto.
+> Ogni fase segue il ciclo: **Descrizione → Soluzioni proposte → Domande → Implementazione → Test → Avanzamento**
+
+---
+
+## Indice delle fasi
+
+| # | Fase | Priorità | Stato |
+|---|------|----------|-------|
+| 1 | [File nascosti nel directory listing](#fase-1--file-nascosti-nel-directory-listing) | Alta | ⬜ Da fare |
+| 2 | [Opzione glob per escludere file sensibili](#fase-2--opzione-glob-per-escludere-file-sensibili) | Alta | ⬜ Da fare |
+| 3 | [Content-Security-Policy nell'HTML generato](#fase-3--content-security-policy-nellhtml-generato) | Media | ⬜ Da fare |
+| 4 | [Aggiunta ESLint e standardizzazione `===`](#fase-4--aggiunta-eslint-e-standardizzazione-) | Media | ⬜ Da fare |
+| 5 | [Range Requests HTTP 206](#fase-5--range-requests-http-206) | Media | ⬜ Da fare |
+| 6 | [Gzip / Brotli compression](#fase-6--gzip--brotli-compression) | Media | ⬜ Da fare |
+| 7 | [Traduzione commenti in inglese nei test](#fase-7--traduzione-commenti-in-inglese-nei-test) | Bassa | ⬜ Da fare |
+| 8 | [Roadmap rimozione opzioni deprecate (v3.0.0)](#fase-8--roadmap-rimozione-opzioni-deprecate-v300) | Bassa | ⬜ Da fare |
+
+---
+
+> **Legenda stato:** ⬜ Da fare · 🔄 In corso · ✅ Completato · ⏸️ In pausa
+
+---
+
+## Processo standard per ogni fase
+
+Per ogni fase si segue sempre questo ciclo:
+
+1. **Descrizione** — Spiegazione del problema e del suo impatto
+2. **Soluzioni proposte** — Almeno 2 alternative valutate con pro/contro
+3. **Domande** — Se le informazioni disponibili sono < 90%, si chiedono chiarimenti prima di procedere
+4. **Implementazione** — Modifica del codice sul branch `claude/project-review-EN6kt`
+5. **Test** — Esecuzione della suite di test e verifica regressioni
+6. **Avanzamento** — Aggiornamento dello stato in questo file e passaggio alla fase successiva
+
+---
+
+## Fase 1 — File nascosti nel directory listing
+
+**Stato:** ⬜ Da fare
+**Priorità:** Alta
+**File coinvolti:** `index.cjs` (funzione `show_dir`)
+
+### Descrizione del problema
+
+Il directory listing mostra **tutti** i file e le cartelle presenti nella webroot, inclusi quelli che iniziano con `.` (dot files), come:
+
+- `.env` — variabili d'ambiente con credenziali
+- `.gitignore`, `.gitattributes` — metadati Git
+- `.htpasswd` — password Apache
+- `.DS_Store` — metadati macOS
+- `.npmrc` — configurazioni npm con token
+
+Server come Apache e Nginx nascondono questi file per default. Un file dimenticato nella webroot potrebbe esporre informazioni sensibili agli utenti del browser.
+
+### Soluzioni proposte
+
+*Da definire nella sessione di lavoro dedicata a questa fase.*
+
+### Domande
+
+*Da porre prima dell'implementazione se necessario.*
+
+### Implementazione
+
+*Da eseguire dopo la scelta della soluzione.*
+
+### Test
+
+*Da verificare dopo l'implementazione.*
+
+---
+
+## Fase 2 — Opzione glob per escludere file sensibili
+
+**Stato:** ⬜ Da fare
+**Priorità:** Alta
+**File coinvolti:** `index.cjs` (opzioni di configurazione + `show_dir`)
+
+### Descrizione del problema
+
+Non esiste un'opzione per escludere file o cartelle specifici dal serving e dal directory listing tramite pattern (glob o RegExp). Se un file come `config.json`, `secrets.yaml` o qualsiasi altro file sensibile si trova nella webroot, viene servito senza restrizioni.
+
+Esempi di pattern utili:
+- `*.env` — tutti i file .env
+- `**/*.secret` — file con estensione .secret
+- `private/**` — intera cartella private
+
+### Soluzioni proposte
+
+*Da definire nella sessione di lavoro dedicata a questa fase.*
+
+### Domande
+
+*Da porre prima dell'implementazione se necessario.*
+
+### Implementazione
+
+*Da eseguire dopo la scelta della soluzione.*
+
+### Test
+
+*Da verificare dopo l'implementazione.*
+
+---
+
+## Fase 3 — Content-Security-Policy nell'HTML generato
+
+**Stato:** ⬜ Da fare
+**Priorità:** Media
+**File coinvolti:** `index.cjs` (funzione `show_dir`)
+
+### Descrizione del problema
+
+Le pagine HTML generate dal directory listing non includono un header `Content-Security-Policy`. Senza CSP, il browser non ha indicazioni su quali risorse sono autorizzate, aumentando il rischio di attacchi XSS in caso di eventuali vulnerabilità future nel codice di generazione HTML.
+
+Il progetto già implementa l'escape HTML (funzione `escapeHtml`), ma aggiungere CSP è un ulteriore livello di difesa in profondità.
+
+### Soluzioni proposte
+
+*Da definire nella sessione di lavoro dedicata a questa fase.*
+
+### Domande
+
+*Da porre prima dell'implementazione se necessario.*
+
+### Implementazione
+
+*Da eseguire dopo la scelta della soluzione.*
+
+### Test
+
+*Da verificare dopo l'implementazione.*
+
+---
+
+## Fase 4 — Aggiunta ESLint e standardizzazione `===`
+
+**Stato:** ⬜ Da fare
+**Priorità:** Media
+**File coinvolti:** `index.cjs`, `package.json`, nuovi file di config
+
+### Descrizione del problema
+
+Il codice usa `==` (uguaglianza debole con coercizione di tipo) in circa 25 punti, documentati in `docs/CODE_REVIEW.md`. Anche se nel contesto attuale non causano bug, l'uso di `===` è la best practice JavaScript e previene errori sottili in futuro.
+
+Inoltre il progetto non ha alcun linter o formatter configurato, il che rende difficile mantenere la coerenza stilistica nel tempo e nelle contribuzioni esterne.
+
+### Soluzioni proposte
+
+*Da definire nella sessione di lavoro dedicata a questa fase.*
+
+### Domande
+
+*Da porre prima dell'implementazione se necessario.*
+
+### Implementazione
+
+*Da eseguire dopo la scelta della soluzione.*
+
+### Test
+
+*Da verificare dopo l'implementazione.*
+
+---
+
+## Fase 5 — Range Requests HTTP 206
+
+**Stato:** ⬜ Da fare
+**Priorità:** Media
+**File coinvolti:** `index.cjs` (logica di file serving)
+
+### Descrizione del problema
+
+Il middleware non supporta l'header `Range` delle richieste HTTP. Questo significa che:
+
+- File audio e video non possono essere riprodotti in streaming dai browser
+- Download di file grandi non possono essere ripresi dopo interruzione
+- Strumenti come `curl --range` non funzionano
+
+Il supporto HTTP 206 (Partial Content) è lo standard per la distribuzione di contenuti multimediali e file di grandi dimensioni.
+
+### Soluzioni proposte
+
+*Da definire nella sessione di lavoro dedicata a questa fase.*
+
+### Domande
+
+*Da porre prima dell'implementazione se necessario.*
+
+### Implementazione
+
+*Da eseguire dopo la scelta della soluzione.*
+
+### Test
+
+*Da verificare dopo l'implementazione.*
+
+---
+
+## Fase 6 — Gzip / Brotli compression
+
+**Stato:** ⬜ Da fare
+**Priorità:** Media
+**File coinvolti:** `index.cjs`, `package.json`
+
+### Descrizione del problema
+
+Il middleware serve tutti i file senza compressione. Per file di testo (HTML, CSS, JS, JSON, SVG), la compressione può ridurre le dimensioni del 60-80%, con impatto diretto su:
+
+- Velocità di caricamento per gli utenti
+- Consumo di banda del server
+- Score Lighthouse / Web Vitals
+
+### Soluzioni proposte
+
+*Da definire nella sessione di lavoro dedicata a questa fase.*
+
+### Domande
+
+*Da porre prima dell'implementazione se necessario.*
+
+### Implementazione
+
+*Da eseguire dopo la scelta della soluzione.*
+
+### Test
+
+*Da verificare dopo l'implementazione.*
+
+---
+
+## Fase 7 — Traduzione commenti in inglese nei test
+
+**Stato:** ⬜ Da fare
+**Priorità:** Bassa
+**File coinvolti:** `__tests__/dt-unknown.test.js` e altri
+
+### Descrizione del problema
+
+Alcuni file di test contengono commenti in italiano, il che riduce l'accessibilità del codice per i contribuenti internazionali. Per un progetto open source pubblicato su npm, la lingua standard della codebase dovrebbe essere l'inglese.
+
+### Soluzioni proposte
+
+*Da definire nella sessione di lavoro dedicata a questa fase.*
+
+### Domande
+
+*Da porre prima dell'implementazione se necessario.*
+
+### Implementazione
+
+*Da eseguire dopo la scelta della soluzione.*
+
+### Test
+
+*Da verificare dopo l'implementazione.*
+
+---
+
+## Fase 8 — Roadmap rimozione opzioni deprecate (v3.0.0)
+
+**Stato:** ⬜ Da fare
+**Priorità:** Bassa
+**File coinvolti:** `index.cjs`, `docs/CHANGELOG.md`, `README.md`
+
+### Descrizione del problema
+
+Le opzioni legacy `cacheMaxAge` ed `enableCaching` sono ancora supportate con deprecation warning ma non hanno una data di rimozione pianificata. Mantenerle a tempo indeterminato appesantisce il codice e può confondere i nuovi utenti che leggono la documentazione.
+
+Una roadmap chiara verso `v3.0.0` con breaking changes definiti aiuta gli utenti a pianificare la migrazione.
+
+### Soluzioni proposte
+
+*Da definire nella sessione di lavoro dedicata a questa fase.*
+
+### Domande
+
+*Da porre prima dell'implementazione se necessario.*
+
+### Implementazione
+
+*Da eseguire dopo la scelta della soluzione.*
+
+### Test
+
+*Da verificare dopo l'implementazione.*
+
+---
+
+*Documento aggiornato: 2026-03-21*

package/docs/CHANGELOG.md

@@ -5,6 +5,295 @@ All notable changes to koa-classic-server will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.0.0] - 2026-05-13
+
+### 🆕 New Features
+
+#### `hidden` option — protect dot-files, dot-dirs and custom patterns (Fase 1 + Fase 2)
+
+A new `hidden` option controls which files and directories are blocked from both directory listing and direct HTTP access (returning **404**). Applies recursively to the entire directory tree.
+
+**Default behavior (secure out of the box):**
+- Dot-files (names starting with `.`) → **hidden by default** (`dotFiles.default: 'hidden'`)
+- Dot-directories → **visible by default** (`dotDirs.default: 'visible'`)
+
+```js
+app.use(koaClassicServer('/public', {
+  hidden: {
+    dotFiles: {
+      default: 'hidden',          // 'hidden' | 'visible'
+      whitelist: ['.well-known'], // Always visible (string exact/glob or RegExp)
+      blacklist: [],              // Always hidden — overrides whitelist
+    },
+    dotDirs: {
+      default: 'visible',
+      whitelist: [],
+      blacklist: ['.git', /^\.svn/],
+    },
+    alwaysHide: ['*.secret', 'config/secrets/**', /\.key$/], // Path-aware patterns
+  }
+}));
+```
+
+**Priority (highest to lowest):**
+1. `blacklist` — always hidden, beats everything
+2. `whitelist` — always visible, overrides `alwaysHide` and `default`
+3. `alwaysHide` — path-aware patterns, beats `default`
+4. `default` — fallback behavior for unmatched dot-entries
+
+**`alwaysHide` pattern rules:**
+- String without `/`: matches basename at any depth (e.g. `*.secret` hides `a/b/file.secret`)
+- String with `/`: path-anchored from root (e.g. `config/secrets/**`)
+- RegExp: tested against the full relative path
+
+**Blocked dot-dirs block sub-paths too:**
+`GET /.git/config` returns 404 if `.git` is in `dotDirs.blacklist`.
+
+#### `template.renderTimeout` — bounded template execution (Security M-1)
+
+The template `render` callback now runs under a configurable timeout (default **30 000 ms**, `0` = disabled). When a render exceeds the timeout the middleware responds **`504 Gateway Timeout`** with the usual security headers, instead of leaving the client connection blocked on a slow/hung render. Protects against DoS via connection exhaustion when a render performs unbounded I/O (DB queries, remote fetches, etc.).
+
+The `render` function now receives an **`AbortSignal` as 5th argument**. The signal aborts on timeout *and* when the client disconnects (even when `renderTimeout: 0`). Cooperative renders that propagate the signal to `fetch` / DB clients / `fs.promises.*` also free backend resources on timeout.
+
+```js
+app.use(koaClassicServer('/public', {
+  template: {
+    ext: ['ejs'],
+    renderTimeout: 5000,                                  // ms; 0 disables
+    render: async (ctx, next, filePath, rawBuffer, signal) => {
+      const data = await db.query('SELECT ...', { signal }); // honour signal
+      const ext  = await fetch('https://api/...', { signal });
+      signal.throwIfAborted();
+      ctx.type = 'text/html';
+      ctx.body = ejs.render(rawBuffer.toString(), { data, ext });
+    }
+  }
+}));
+```
+
+**Backward compatible:** existing 4-argument render functions keep working — the 5th argument is simply ignored.
+
+#### `serverCache.*.maxAge` — time-based cache invalidation (Security M-2)
+
+Both server-side caches (`serverCache.rawFile` and `serverCache.compressedFile`) accept a new `maxAge` option (ms, default `0` = disabled). When `> 0`, an entry is considered stale after `maxAge` ms regardless of `mtime + size`, forcing a fresh disk read on the next request.
+
+Designed for **NFS / SMB / Docker bind mounts** where the OS attribute cache can keep `stat()` returning a stale `mtime` for several seconds after a remote modification — making the mtime+size invariant insufficient to detect changes. `maxAge` bounds the worst-case staleness window to a known value.
+
+```js
+app.use(koaClassicServer('/public', {
+  serverCache: {
+    rawFile:        { enabled: true, maxAge: 30000 }, // refresh every 30 s
+    compressedFile: { enabled: true, maxAge: 30000 }
+  }
+}));
+```
+
+> **Limitation:** `maxAge` limits but does not eliminate NFS staleness. For strict freshness combine with a low `actimeo=` on the mount.
+
+Internally a new `LFUCache.refresh(key, fields)` method updates the entry in place while preserving its LFU frequency, so popular files refreshed by `maxAge` don't fall to the bottom of the eviction bucket.
+
+#### `logger` option — pluggable structured logging (Security N-1)
+
+All internal `console.error` / `console.warn` calls now route through an injectable logger. Pass any object that exposes `error(...)` and `warn(...)` methods — `console` (default), `pino`, `winston`, `bunyan`, or a custom adapter — to integrate with aggregated logging pipelines in production.
+
+```js
+const pino = require('pino')();
+
+app.use(koaClassicServer('/public', {
+  logger: pino
+}));
+```
+
+**Contract:**
+- Must be an object with `typeof logger.error === 'function'` and `typeof logger.warn === 'function'`
+- Invalid loggers (missing methods, non-objects, `null`, `false`, arrays) throw at factory time
+- Extra methods (`info`, `debug`, `fatal`, ...) are ignored — pass any superset freely
+
+**ANSI escape codes** in warning messages are only emitted when the logger is the global `console` (detected by reference). Structured loggers receive the plain text, keeping log aggregators clean.
+
+**Backward compatible:** when `logger` is omitted, the default is `console` — existing code and tests that spy on `console.error` / `console.warn` continue to work unchanged.
+
+#### `dirListing` namespace — bounded and paginated directory listings (Security N-2)
+
+A new namespaced option groups all directory-listing config together, replacing the v2-era flat `showDirContents` knob with a structured object. Hardens the listing against indirect DoS via very large directories and improves usability on big folders.
+
+```js
+app.use(koaClassicServer('/public', {
+  dirListing: {
+    enabled:        true,    // render listing HTML when no index file matches (default: true)
+    maxEntries:     10000,   // hard cap on visible / sorted / stat'd entries (default; 0 = disabled)
+    entriesPerPage: 100,     // entries per page in the listing UI (default; 0 = disabled)
+  }
+}));
+```
+
+**dirListing.enabled**
+- Replaces the v2 top-level `showDirContents`. Accepts `true` / `false`. When `false`, requests for a directory without a matching index file return 404 instead of an HTML listing.
+
+**dirListing.maxEntries**
+- Caps how many entries are sorted, stat'd, and rendered per directory listing. Excess entries trigger a yellow banner at the top of the page and an `X-Dir-Truncated: <N>` response header so monitoring can distinguish capped listings.
+- Implementation: the middleware calls `fs.promises.readdir()` once and then slices the result. This bounds rendering and CPU cost but **not** the size of the initial `readdir()` allocation. For typical static-file servers (where the directory contents are controlled by the operator) this is the right trade-off — it recovers v2-class listing performance.
+- Default `10000` is permissive enough for normal use while bounding rendering cost on accidentally-large folders.
+- **Caveat for adversarial workloads:** if you serve a directory writable by untrusted parties, an attacker creating millions of files could still force a large `readdir()` allocation. Tracked for v3.1 as opt-in streaming reads — see `docs/security_improvement_for_V3.md` → *Future Work* → *[F-1]*.
+
+**dirListing.entriesPerPage**
+- Pagination kicks in only when the visible entries exceed `entriesPerPage`; small directories render in a single page exactly like before.
+- The current page is selected by `?page=N` (0-based). Invalid or out-of-range values clamp silently to the nearest valid page.
+- A numbered paginator (`« First | ‹ Prev | 0 1 … N-1 | Next › | Last »`) is rendered below the table, preserving any active `sort`/`order`. An `X-Dir-Pagination: <current>/<last>` header is also emitted.
+
+**Migration from v2**
+
+`showDirContents` (a v2-stable option) keeps working as a **backward-compatibility alias** for `dirListing.enabled`. v2 code that passes it continues to function unchanged. A one-time deprecation warning is emitted via the configured `logger.warn(...)` to encourage migration:
+
+```
+[koa-classic-server] DEPRECATION: options.showDirContents was renamed to dirListing.enabled in v3.0.0.
+  The old name is currently accepted as an alias and may be removed in a future major version.
+  Replace with: dirListing: { enabled: true }
+```
+
+Passing both `showDirContents` and `dirListing.enabled` at the same time throws — pick one.
+
+**Migration from v3.0.0-alpha.0**
+
+The two V3-alpha-only legacy names throw helpful errors at startup (no v2 user can have these in production):
+
+```
+options.maxDirEntries was relocated in v3.0.0.
+  Replace with: dirListing: { maxEntries: 10000 }
+
+options.pageSize was relocated and renamed in v3.0.0.
+  Replace with: dirListing: { entriesPerPage: 100 }
+```
+
+**CSP impact:** the listing CSS now includes rules for `.kcs-banner` and `.kcs-pagination`. The page's CSP hash is auto-recomputed at module load (no manual config change needed).
+
+### 📝 Documentation
+
+#### DNS Rebinding deployment guidance (Security M-3)
+
+The `Host` header is intentionally not validated by the middleware — host validation belongs to the reverse proxy or to a dedicated application-level guard. The new *Best Practices → Sicurezza → DNS Rebinding* section in `docs/DOCUMENTATION.md` explains:
+
+- When the risk applies (LAN/loopback exposure without a fronting proxy).
+- When it doesn't (reverse proxy with `server_name` allowlist, public IP behind CDN/WAF).
+- A drop-in nginx allowlist snippet.
+- A Koa middleware that checks `ctx.host` against an allowlist and returns `421 Misdirected Request`, plus a note on `app.proxy = true` + `X-Forwarded-Host` when terminating TLS upstream.
+
+No code change in `index.cjs` — documentation only.
+
+#### Security headers scope and limits (Security M-4)
+
+Clarify that the security headers emitted by the middleware (`Content-Security-Policy`, `X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy`, `Permissions-Policy`) are applied **only** to middleware-generated responses (directory listing + error pages). User-served static files are returned without these headers — by design, because the right policy is application-specific.
+
+The new *Best Practices → Sicurezza → Limiti dei Security Headers sui file statici* section in `docs/DOCUMENTATION.md` covers:
+
+- A table listing which headers are emitted automatically and on which responses.
+- An upstream Koa middleware example that adds `X-Content-Type-Options`, `Referrer-Policy`, `Strict-Transport-Security` to every response and a strict CSP only to HTML responses.
+- Notes on rolling out CSP via `Content-Security-Policy-Report-Only`, and on `COOP`/`COEP` for projects using `SharedArrayBuffer`.
+
+No code change in `index.cjs` — documentation only.
+
+### 🎯 Design Philosophy
+
+v3.0.0 codifies the project's design intent in a new top-level `CLAUDE.md`: **koa-classic-server is an HTTP file server first**. The contract with the operator is: *"if a file is in `rootDir`, `GET` on its path returns it"*. Defaults serve files without applying surprise restrictions — the operator's directory is the source of truth.
+
+This drove a revision of two v3-alpha defaults late in the cycle (see *Breaking Changes* below) and shapes how new features will be designed going forward. Operators harden via explicit configuration; the README and `docs/DOCUMENTATION.md` now ship a **Security Checklist** and a **Suggested Production Security Configuration** to help with that.
+
+### ⚠️ Breaking Changes
+
+#### Dot-files visible by default (philosophy alignment)
+
+Earlier in the v3.0.0 alpha cycle, `hidden.dotFiles.default` was flipped to `'hidden'` as a security-by-default choice. This created surprise behavior — `GET /.env` returning 404 even when the file exists — which violates the "file server first" design philosophy.
+
+**Final v3.0.0 behavior:** `hidden.dotFiles.default` is `'visible'`, restoring v2 behavior. The implicit-default warning that fired in alpha when the option was omitted is also removed.
+
+| Default | v2 | v3.0.0-alpha early | **v3.0.0 final** |
+|---|---|---|---|
+| `hidden.dotFiles.default` | `'visible'` | `'hidden'` | **`'visible'`** |
+| Implicit-default runtime warning | — | emitted | **removed** |
+
+**Operators upgrading from v2:** no change in behavior — your existing dot-files keep being served. **Migration to harden** (recommended for production): set `hidden.dotFiles.default: 'hidden'` explicitly and whitelist `.well-known` for ACME. See the *Security Checklist* in `README.md`.
+
+#### `dirListing.maxEntries` default raised from 10,000 → 100,000
+
+The earlier v3-alpha default of `10,000` was tight enough that operators with normal-sized media catalogs, releases archives, or asset directories would hit truncation silently (the listing banner would appear). This violated the "no surprise restrictions" rule — the cap was acting as a policy restriction rather than a safety net.
+
+**Final v3.0.0 behavior:** `dirListing.maxEntries` defaults to `100,000` — high enough that 99% of legitimate deployments never hit it, low enough to bound rendering cost on accidentally-huge directories (log rotation broken, mistakenly mounted FS).
+
+| Default | v3.0.0-alpha early | **v3.0.0 final** |
+|---|---|---|
+| `dirListing.maxEntries` | `10000` | **`100000`** |
+| `dirListing.entriesPerPage` | `100` | `100` (unchanged) |
+
+**Caveat:** even with `maxEntries: 100000`, the initial `fs.promises.readdir()` allocation is not bounded. For adversarial-directory workloads (multi-tenant uploads, untrusted writes), this gap will be closed by the v3.1 `dirListing.readMode: 'bounded'` option — tracked under `[F-1]` in `docs/security_improvement_for_V3.md`.
+
+#### Dot-files hardening is now opt-in (was implicit "secure by default")
+
+Operators who *want* the v3-alpha behavior (dot-files hidden by default, including `.env`, `.git/config`, etc.) must now opt in explicitly:
+
+```javascript
+app.use(koaClassicServer('/public', {
+  hidden: {
+    dotFiles: { default: 'hidden', whitelist: ['.well-known'] },
+    dotDirs:  { default: 'hidden', whitelist: ['.well-known'] },
+  },
+}));
+```
+
+This snippet now appears in the *Suggested Production Security Configuration* in both `README.md` and `docs/DOCUMENTATION.md`.
+
+#### Removed string format for `index` option
+- **Removed**: `index: 'index.html'` — passing a non-empty string now throws an `Error` at startup
+- **Empty string** `index: ''` is still silently treated as `[]` (no index file, show directory listing)
+- **Migration**:
+  ```js
+  // Before (v2.x — now throws)
+  app.use(koaClassicServer('/public', { index: 'index.html' }));
+
+  // After (v3.0.0)
+  app.use(koaClassicServer('/public', { index: ['index.html'] }));
+  ```
+
+#### Removed deprecated option names `cacheMaxAge` and `enableCaching`
+- **Removed**: `cacheMaxAge` — use `browserCacheMaxAge` instead
+- **Removed**: `enableCaching` — use `browserCacheEnabled` instead
+- **Behaviour**: Passing either removed option now throws an `Error` at startup with a clear migration message pointing to the new name and the current value.
+- **Migration**:
+  ```js
+  // Before (v2.x — now throws)
+  app.use(koaClassicServer('/public', {
+    enableCaching: true,
+    cacheMaxAge: 3600
+  }));
+
+  // After (v3.0.0)
+  app.use(koaClassicServer('/public', {
+    browserCacheEnabled: true,
+    browserCacheMaxAge: 3600
+  }));
+  ```
+
+#### Renamed `compression.minSize` → `compression.minFileSize`
+
+The threshold below which files are served uncompressed has a clearer name. Brings naming into line with `serverCache.rawFile.maxFileSize`, where "file size" is the explicit unit. Affects only alpha-tester code (the `compression` namespace was introduced in v3 and is not present in v2).
+
+- **Removed**: `compression.minSize` — passing it now throws an `Error` at startup
+- **Migration**:
+  ```js
+  // Before (v3.0.0-alpha.0 — now throws)
+  app.use(koaClassicServer('/public', {
+    compression: { minSize: 2048 }
+  }));
+
+  // After (v3.0.0)
+  app.use(koaClassicServer('/public', {
+    compression: { minFileSize: 2048 }
+  }));
+  ```
+
+The `false` shorthand (disable the threshold entirely) is preserved on the new name: `compression: { minFileSize: false }`.
+
+---
+
 ## [2.6.1] - 2026-03-04
 
 ### 🐛 Bug Fix

package/docs/CODE_REVIEW.md

@@ -1,5 +1,7 @@
 # Code Review - koa-classic-server
 
+> **Nota storica:** questo documento è uno snapshot di code review precedente al refactor V3. Riferimenti a `showDirContents` corrispondono a `dirListing.enabled` nell'API V3 corrente. Vedi [README.md → Migration Guide](../README.md#from-v2x-to-v3x).
+
 ## Analisi Generale del Codice
 
 Data: 2025-11-18