koa-classic-server 3.0.0-alpha.0 → 3.0.0

package/docs/DOCUMENTATION.md

@@ -157,7 +157,7 @@ const koaClassicServer = require('koa-classic-server');
 const app = new Koa();
 
 app.use(koaClassicServer(__dirname + '/public', {
-  showDirContents: true,
+  dirListing: { enabled: true },
   index: 'index.html',
   urlPrefix: '/static'
 }));
@@ -193,7 +193,7 @@ const options = {
 
   // Mostra il contenuto delle directory
   // Default: true
-  showDirContents: true,
+  dirListing: { enabled: true },
 
   // Nome del file index da caricare automaticamente nelle directory
   // Se presente, viene caricato invece del directory listing
@@ -245,16 +245,16 @@ method: ['GET', 'HEAD']
 method: ['GET', 'HEAD', 'POST']
 ```
 
-#### `showDirContents` (Boolean)
+#### `dirListing.enabled` (Boolean)
 
 Controlla se mostrare il contenuto delle directory.
 
 ```javascript
 // Mostra directory listing
-showDirContents: true
+dirListing: { enabled: true }
 
 // Non mostra directory (restituisce "Not Found")
-showDirContents: false
+dirListing: { enabled: false }
 ```
 
 #### `index` (String)
@@ -275,7 +275,7 @@ index: ''
 **Comportamento:**
 1. Utente accede a `/cartella/`
 2. Se esiste `/cartella/index.html` → viene servito
-3. Altrimenti → mostra directory listing (se `showDirContents: true`)
+3. Altrimenti → mostra directory listing (se `dirListing: { enabled: true }`)
 
 #### `urlPrefix` (String)
 
@@ -373,7 +373,7 @@ const koaClassicServer = require('koa-classic-server');
 const app = new Koa();
 
 app.use(koaClassicServer(__dirname + '/public', {
-  showDirContents: true,
+  dirListing: { enabled: true },
   index: 'index.html'
 }));
 
@@ -400,7 +400,7 @@ const app = new Koa();
 app.use(koaClassicServer(__dirname + '/public', {
   urlPrefix: '/static',
   method: ['GET', 'HEAD'],
-  showDirContents: true
+  dirListing: { enabled: true }
 }));
 
 // Altri middleware per route diverse
@@ -427,7 +427,7 @@ const koaClassicServer = require('koa-classic-server');
 const app = new Koa();
 
 app.use(koaClassicServer(__dirname + '/www', {
-  showDirContents: true,
+  dirListing: { enabled: true },
   // Protegge directory sensibili
   urlsReserved: ['/config', '/private', '/.git', '/node_modules']
 }));
@@ -452,7 +452,7 @@ const ejs = require('ejs');
 const app = new Koa();
 
 app.use(koaClassicServer(__dirname + '/views', {
-  showDirContents: false,
+  dirListing: { enabled: false },
   template: {
     render: async (ctx, next, filePath) => {
       // Rendering EJS con dati
@@ -485,19 +485,19 @@ const app = new Koa();
 // File statici pubblici
 app.use(koaClassicServer(__dirname + '/public', {
   urlPrefix: '/public',
-  showDirContents: true
+  dirListing: { enabled: true }
 }));
 
 // Asset (CSS, JS, images)
 app.use(koaClassicServer(__dirname + '/assets', {
   urlPrefix: '/assets',
-  showDirContents: false
+  dirListing: { enabled: false }
 }));
 
 // Download area
 app.use(koaClassicServer(__dirname + '/downloads', {
   urlPrefix: '/downloads',
-  showDirContents: true,
+  dirListing: { enabled: true },
   index: 'README.txt'
 }));
 
@@ -549,7 +549,7 @@ const templateRender = async (ctx, next, filePath) => {
 // File server
 app.use(koaClassicServer(path.join(__dirname, 'public'), {
   method: ['GET', 'HEAD'],
-  showDirContents: process.env.NODE_ENV !== 'production',
+  dirListing: { enabled: process.env.NODE_ENV !== 'production' },
   index: 'index.html',
   urlPrefix: '/files',
   urlsReserved: ['/admin', '/private', '/config', '/.env'],
@@ -599,7 +599,7 @@ app.use(router.allowedMethods());
 
 // File statici (dopo le route API)
 app.use(koaClassicServer(__dirname + '/public', {
-  showDirContents: true
+  dirListing: { enabled: true }
 }));
 
 app.listen(3000);
@@ -631,7 +631,7 @@ Crea e restituisce un middleware Koa per servire file statici.
 
 ```javascript
 const middleware = koaClassicServer('/path/to/files', {
-  showDirContents: true
+  dirListing: { enabled: true }
 });
 
 app.use(middleware);
@@ -682,7 +682,7 @@ template: {
 
 ### Gestione delle Directory
 
-#### Caso 1: showDirContents = true, index presente
+#### Caso 1: dirListing.enabled = true, index presente
 
 ```
 Richiesta: GET /cartella/
@@ -693,7 +693,7 @@ Filesystem:
 Risultato: Serve /cartella/index.html
 ```
 
-#### Caso 2: showDirContents = true, index assente
+#### Caso 2: dirListing.enabled = true, index assente
 
 ```
 Richiesta: GET /cartella/
@@ -704,7 +704,7 @@ Filesystem:
 Risultato: Mostra directory listing HTML
 ```
 
-#### Caso 3: showDirContents = false
+#### Caso 3: dirListing.enabled = false
 
 ```
 Richiesta: GET /cartella/
@@ -925,7 +925,7 @@ describe('My custom test', () => {
   beforeAll(() => {
     app = new Koa();
     app.use(koaClassicServer(__dirname + '/test-files', {
-      showDirContents: true
+      dirListing: { enabled: true }
     }));
     server = app.listen();
   });
@@ -1042,11 +1042,11 @@ npm install ejs
 **Soluzione:**
 
 ```javascript
-// ❌ showDirContents disabilitato
-showDirContents: false
+// ❌ dirListing.enabled disabilitato
+dirListing: { enabled: false }
 
-// ✅ showDirContents abilitato
-showDirContents: true
+// ✅ dirListing.enabled abilitato
+dirListing: { enabled: true }
 ```
 
 ---
@@ -1128,12 +1128,12 @@ const url = '/' + encodeURIComponent(filename);
 
 1. Disabilita directory listing:
 ```javascript
-showDirContents: false
+dirListing: { enabled: false }
 ```
 
 2. Usa file index:
 ```javascript
-showDirContents: true,
+dirListing: { enabled: true },
 index: 'index.html'  // Carica index invece di listing
 ```
 
@@ -1278,11 +1278,238 @@ method: ['GET', 'HEAD']
 #### Disabilita Directory Listing in Produzione
 ```javascript
 app.use(koaClassicServer(rootDir, {
-  showDirContents: process.env.NODE_ENV !== 'production',
+  dirListing: { enabled: process.env.NODE_ENV !== 'production' },
   index: 'index.html'
 }));
 ```
 
+#### DNS Rebinding — valida l'header `Host` a monte
+
+`koa-classic-server` **non valida l'header `Host`** delle richieste in entrata. Questo è intenzionale: la validazione del Virtual Host appartiene allo strato di rete (reverse proxy o middleware Koa applicativo), non a un file server.
+
+In assenza di tale validazione, un host LAN/loopback (es. `127.0.0.1`, `192.168.x.x`) è vulnerabile a **DNS rebinding**: un attaccante remoto può far risolvere il proprio dominio all'IP della vittima ed eseguire richieste cross-origin verso il server locale come se provenissero da un'origine legittima del browser.
+
+**Quando è un problema concreto**
+- Server raggiunto da `localhost` / IP privati senza reverse proxy davanti.
+- Browser dell'utente che visita pagine non fidate mentre il server è attivo.
+
+**Quando NON è un problema**
+- Deploy dietro reverse proxy (nginx, Caddy, Apache, Traefik) configurato con allowlist di `server_name` / hostname.
+- Server raggiungibile solo da IP pubblico dietro CDN/WAF.
+- Binding esplicito a interfaccia non instradabile (`app.listen(port, '127.0.0.1')`) e nessun browser locale espone l'utente a pagine ostili.
+
+**Mitigazione 1 — reverse proxy (raccomandato in produzione)**
+
+Esempio nginx:
+```nginx
+server {
+    listen 80;
+    server_name app.example.com;      # ← allowlist
+    location / { proxy_pass http://127.0.0.1:3000; }
+}
+# Tutte le richieste con Host diverso da app.example.com vengono rifiutate qui.
+```
+
+**Mitigazione 2 — middleware Koa applicativo (utile in dev/LAN)**
+
+Antepone una guardia su `ctx.host` PRIMA di `koa-classic-server`:
+
+```javascript
+const ALLOWED_HOSTS = new Set([
+  'app.example.com',
+  'localhost:3000',
+  '127.0.0.1:3000',
+]);
+
+app.use(async (ctx, next) => {
+  // ctx.host include la porta (es. "localhost:3000")
+  if (!ALLOWED_HOSTS.has(ctx.host)) {
+    ctx.status = 421; // Misdirected Request
+    ctx.body = 'Host not allowed';
+    return;
+  }
+  await next();
+});
+
+app.use(koaClassicServer(rootDir));
+```
+
+> ⚠️ Se il proxy a monte termina TLS e inoltra all'app, configura `app.proxy = true` e usa `ctx.hostname` con `X-Forwarded-Host` solo se il proxy è fidato.
+
+#### Limiti dei Security Headers sui file statici
+
+`koa-classic-server` imposta automaticamente i seguenti header SOLO sulle **risposte generate** dal middleware (directory listing HTML, pagine di errore 400/403/404/405/500):
+
+| Header | Valore |
+|---|---|
+| `Content-Security-Policy` | `default-src 'none'; ...` (hash-based per il listing, fully restrictive per gli errori) |
+| `X-Content-Type-Options` | `nosniff` |
+| `X-Frame-Options` | `DENY` |
+| `Referrer-Policy` | `no-referrer` |
+| `Permissions-Policy` | `camera=(), microphone=(), geolocation=(), payment=()` |
+
+**Cosa NON riceve questi header**
+
+I **file statici** serviti dal disco (HTML, JS, CSS, immagini, font, video, qualsiasi altra estensione) sono restituiti **senza** alcun header di sicurezza aggiunto. Questo è **by-design**:
+
+- Le policy di sicurezza appropriate sono diverse caso per caso (CSP per app SPA, sandbox per documenti, COEP/COOP per pagine con SharedArrayBuffer, ecc.).
+- Imporre una CSP rigida di default romperebbe la maggior parte dei siti reali (script inline, CDN, Google Fonts, ecc.).
+- L'utente possiede la propria policy e deve dichiararla esplicitamente.
+
+> ⚠️ Non assumere che il middleware "metta in sicurezza" i tuoi file: gli header sopra elencati vengono inviati **solo** quando la risposta è generata dal middleware stesso.
+
+**Come aggiungere security headers ai file statici**
+
+Inserisci un middleware Koa **prima** di `koa-classic-server`. Il middleware si applica a ogni risposta uscente, statica o generata che sia, e i `ctx.set()` rimangono attivi anche dopo che il file server scrive il body:
+
+```javascript
+const Koa = require('koa');
+const koaClassicServer = require('koa-classic-server');
+
+const app = new Koa();
+
+// 1) Header globali su TUTTE le risposte (statiche + generate).
+app.use(async (ctx, next) => {
+  // Header sempre validi per un file server pubblico:
+  ctx.set('X-Content-Type-Options', 'nosniff');
+  ctx.set('Referrer-Policy', 'strict-origin-when-cross-origin');
+  ctx.set('Strict-Transport-Security', 'max-age=63072000; includeSubDomains');
+
+  // CSP per file HTML serviti dall'utente (mantieni il file server per gli altri MIME).
+  // Esempio strict-by-default per un sito statico moderno:
+  if (ctx.path.endsWith('.html') || ctx.path === '/' || ctx.path.endsWith('/')) {
+    ctx.set('Content-Security-Policy',
+      "default-src 'self'; img-src 'self' data:; style-src 'self' 'unsafe-inline'; " +
+      "script-src 'self'; object-src 'none'; base-uri 'self'; frame-ancestors 'none'"
+    );
+  }
+
+  await next();
+});
+
+// 2) Quindi il file server.
+app.use(koaClassicServer(__dirname + '/public'));
+
+app.listen(3000);
+```
+
+**Note operative**
+
+- Il middleware sopra **non sovrascrive** gli header che `koa-classic-server` imposta sulle proprie pagine (listing/errori): Koa preserva il primo `set()`, ma se vuoi essere esplicito puoi applicare le tue policy solo a `ctx.status < 400` e a `Content-Type` HTML.
+- Una CSP rigida con `default-src 'self'` rompe pagine che usano script inline o CDN: parti **report-only** (`Content-Security-Policy-Report-Only`) per rilevare le violazioni prima di enforce-arla.
+- Per progetti SPA/PWA che richiedono `SharedArrayBuffer`, considera anche `Cross-Origin-Opener-Policy: same-origin` e `Cross-Origin-Embedder-Policy: require-corp`.
+
+#### Security Checklist & Suggested Configuration
+
+`koa-classic-server` parte dal principio **"file server first"** (vedi [`CLAUDE.md`](../CLAUDE.md)): i default servono i file senza restrizioni di policy nascoste. L'operatore irrobustisce il deploy tramite **configurazione esplicita**.
+
+##### Checklist per categoria
+
+**Static site / public asset serving**
+
+| ✓ | Cosa | Snippet |
+|---|---|---|
+| ☐ | Nascondi dot-files con potenziali segreti | `hidden: { dotFiles: { default: 'hidden', whitelist: ['.well-known'] } }` |
+| ☐ | Blocca dot-directories tipo `.git` | `hidden: { dotDirs: { default: 'hidden', whitelist: ['.well-known'] } }` |
+| ☐ | Disabilita listing in produzione | `dirListing: { enabled: false }` + `index` |
+| ☐ | Abilita HTTP caching | `browserCacheEnabled: true, browserCacheMaxAge: 86400` |
+| ☐ | Restringi i metodi | `method: ['GET', 'HEAD']` |
+| ☐ | Riserva path applicativi | `urlsReserved: ['/api', '/admin']` |
+| ☐ | Aggiungi security headers upstream sui file utente | middleware Koa upstream (vedi *Limiti dei Security Headers* sopra) |
+
+**User uploads / multi-tenant / directory scrivibili da terzi**
+
+| ✓ | Cosa | Snippet |
+|---|---|---|
+| ☐ | Cap entries più stretto contro dir gonfiate | `dirListing: { maxEntries: 1000 }` |
+| ☐ | Hide dot-files a ogni profondità | `hidden: { dotFiles: { default: 'hidden' }, dotDirs: { default: 'hidden' } }` |
+| ☐ | Blocklist path-aware per pattern noti | `hidden: { alwaysHide: ['*.key', '*.pem', /\.secret$/, 'config/secrets/**'] }` |
+| ☐ | Monitora la crescita dir esternamente (cron + alert) | — |
+
+> **Caveat v3.0:** `dirListing.maxEntries` bounda rendering/CPU ma NON la lettura iniziale `readdir()`. Per workload adversarial (utenti non fidati che possono creare milioni di file) la protezione RAM completa arriverà con il `readMode: 'bounded'` di v3.1 (vedi `[F-1]` in `docs/security_improvement_for_V3.md`).
+
+**Production hygiene (qualsiasi deploy)**
+
+| ✓ | Cosa | Snippet |
+|---|---|---|
+| ☐ | Allowlist Host upstream | nginx `server_name` o middleware Koa allowlist su `ctx.host` |
+| ☐ | Disabilita template engine se non SSR | ometti `template` |
+| ☐ | Tune `template.renderTimeout` | abbassa da 30 s per SLA stretti |
+| ☐ | Logger strutturato (Pino/Winston) | `logger: pino()` |
+| ☐ | Pin patch version + `npm audit` in CI | `package.json` + workflow CI |
+
+##### Suggested production security configuration
+
+Una sola configurazione di partenza che copre l'80% dei deploy. Tweak per workload specifici.
+
+```javascript
+const Koa  = require('koa');
+const pino = require('pino')({ level: 'info' });
+const path = require('path');
+const koaClassicServer = require('koa-classic-server');
+
+const app = new Koa();
+
+// 1) Host allowlist — mitiga DNS rebinding su esposizione LAN/loopback.
+const ALLOWED_HOSTS = new Set([
+  'app.example.com',
+  'localhost:3000',
+]);
+app.use(async (ctx, next) => {
+  if (!ALLOWED_HOSTS.has(ctx.host)) {
+    ctx.status = 421;
+    ctx.body = 'Misdirected Request';
+    return;
+  }
+  await next();
+});
+
+// 2) Security headers sui file utente (il middleware li imposta solo su
+//    listing/errori, NON sui file statici — by design).
+app.use(async (ctx, next) => {
+  ctx.set('X-Content-Type-Options',    'nosniff');
+  ctx.set('Referrer-Policy',           'strict-origin-when-cross-origin');
+  ctx.set('Strict-Transport-Security', 'max-age=63072000; includeSubDomains');
+  await next();
+});
+
+// 3) Il file server con default irrobustiti per produzione.
+app.use(koaClassicServer(path.join(__dirname, 'public'), {
+  method: ['GET', 'HEAD'],
+
+  index: ['index.html'],
+
+  dirListing: {
+    enabled:        process.env.NODE_ENV !== 'production',
+    maxEntries:     10000,                // più stretto del default 100000 anti-OOM
+    entriesPerPage: 100,
+  },
+
+  hidden: {
+    dotFiles: {
+      default:   'hidden',                // hardening esplicito vs default 'visible' filosofico
+      whitelist: ['.well-known'],         // ACME / Let's Encrypt
+    },
+    dotDirs: {
+      default:   'hidden',
+      whitelist: ['.well-known'],
+    },
+    alwaysHide: ['*.key', '*.pem', /^backup-/, /\.secret$/],
+  },
+
+  browserCacheEnabled: true,
+  browserCacheMaxAge:  86400,             // 24 h cache
+
+  logger: pino,                           // structured logging
+
+  urlsReserved: ['/api', '/admin'],       // route applicative gestite altrove
+}));
+
+app.listen(3000);
+```
+
+Per **user-uploads / multi-tenant**: oltre al blocco sopra, riduci `dirListing.maxEntries` a `1000` e monitora la dimensione della directory dall'esterno fino a quando v3.1 non aggiunge il `readMode: 'bounded'`.
+
 ---
 
 ### 2. Performance
@@ -1292,7 +1519,7 @@ app.use(koaClassicServer(rootDir, {
 const isProduction = process.env.NODE_ENV === 'production';
 
 app.use(koaClassicServer(rootDir, {
-  showDirContents: !isProduction,
+  dirListing: { enabled: !isProduction },
   method: ['GET', 'HEAD']
 }));
 ```
@@ -1334,7 +1561,7 @@ module.exports = {
   rootDir: path.join(__dirname, '../public'),
   options: {
     method: ['GET', 'HEAD'],
-    showDirContents: true,
+    dirListing: { enabled: true },
     index: 'index.html',
     urlPrefix: '/static',
     urlsReserved: ['/admin', '/config']
@@ -1459,7 +1686,7 @@ if (isDev) {
 
 // File server con configurazione ambiente-specifica
 app.use(koaClassicServer(path.join(__dirname, 'public'), {
-  showDirContents: isDev,  // Solo in dev
+  dirListing: { enabled: isDev },  // Solo in dev
   index: 'index.html',
   urlPrefix: isDev ? '' : '/static',  // Prefix solo in prod
   urlsReserved: ['/admin', '/config', '/.env'],
@@ -1491,7 +1718,7 @@ app.listen(process.env.PORT || 3000);
 const configs = [
   { name: 'base', options: {} },
   { name: 'with-prefix', options: { urlPrefix: '/public' } },
-  { name: 'no-listing', options: { showDirContents: false } }
+  { name: 'no-listing', options: { dirListing: { enabled: false } } }
 ];
 
 configs.forEach(({ name, options }) => {
@@ -1521,7 +1748,7 @@ configs.forEach(({ name, options }) => {
 ```javascript
 app.use(koaClassicServer(__dirname + '/public', {
   // Mostra directory solo in development per sicurezza
-  showDirContents: process.env.NODE_ENV !== 'production',
+  dirListing: { enabled: process.env.NODE_ENV !== 'production' },
 
   // Protegge configurazioni sensibili
   // Nota: funziona solo per directory di primo livello

package/docs/EXAMPLES_INDEX_OPTION.md

@@ -339,7 +339,7 @@ const app = new Koa();
 // Configurazione production-ready
 app.use(koaClassicServer('./public', {
     method: ['GET', 'HEAD'],
-    showDirContents: true,
+    dirListing: { enabled: true },
 
     // Index configuration con fallback multipli
     index: [

package/docs/FLOW_DIAGRAM.md

@@ -1,5 +1,7 @@
 # Flow Diagram - koa-classic-server
 
+> **Nota storica:** diagrammi e snippet di questo documento sono pre-V3. Riferimenti a `options.showDirContents` corrispondono a `options.dirListing.enabled` nell'API V3 corrente. Vedi [README.md → Migration Guide](../README.md#from-v2x-to-v3x).
+
 ## Table of Contents
 - [Overview](#overview)
 - [Main Flow Diagram](#main-flow-diagram)

package/docs/INDEX_OPTION_PRIORITY.md

@@ -61,7 +61,7 @@ index: ['index1.html', 'index2.html', 'index3.html']
    - ✅ Se trovato → **SERVE index3.html** (STOP)
    - ❌ Se non trovato → Passa al passo 4
 
-4. Nessun file trovato → **Mostra directory listing** (se `showDirContents: true`)
+4. Nessun file trovato → **Mostra directory listing** (se `dirListing: { enabled: true }`)
 
 ---
 
@@ -502,7 +502,7 @@ app.use(koaClassicServer('./public', {
 **A:** Le stringhe sono **molto più veloci** (O(1) vs O(n)). Metti sempre le stringhe prima delle RegExp.
 
 ### Q: Cosa succede se nessun pattern matcha?
-**A:** Se `showDirContents: true`, mostra directory listing. Altrimenti restituisce 404.
+**A:** Se `dirListing: { enabled: true }`, mostra directory listing. Altrimenti restituisce 404.
 
 ---
 

package/docs/OPTIMIZATION_HTTP_CACHING.md

@@ -1,5 +1,7 @@
 # Ottimizzazione #3: HTTP Caching Headers
 
+> **Nota storica:** documento di analisi pre-V3. Riferimenti a `showDirContents` corrispondono a `dirListing.enabled` nell'API V3 corrente. Vedi [README.md → Migration Guide](../README.md#from-v2x-to-v3x).
+
 ## Panoramica
 
 **Problema:** I file statici vengono riscaricati dal browser ad ogni richiesta, anche se non sono cambiati.