koa-classic-server 2.6.0 → 3.0.0-alpha.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,124 @@ 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] - Unreleased
+
+### 🆕 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`.
+
+### ⚠️ Breaking Changes
+
+#### Dot-files hidden by default
+`hidden.dotFiles.default` is `'hidden'` by default. In v2.x, dot-files (`.env`, `.gitignore`, etc.) were served normally. In v3.x they return 404 unless explicitly allowed.
+
+To restore v2.x behavior: `hidden: { dotFiles: { default: 'visible' } }`
+
+#### 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
+  }));
+  ```
+
+---
+
+## [2.6.1] - 2026-03-04
+
+### 🐛 Bug Fix
+
+#### Fixed DT_UNKNOWN Handling (type 0) on overlayfs, NFS, FUSE, NixOS buildFHSEnv, ecryptfs
+- **Issue**: On filesystems where `readdir({ withFileTypes: true })` returns dirents with `DT_UNKNOWN` (type 0), all `dirent.is*()` methods return `false`. This caused three failures:
+  1. `isFileOrSymlinkToFile()` missed valid files — `findIndexFile()` returned empty results, so `GET /` showed a directory listing instead of rendering the index file
+  2. `isDirOrSymlinkToDir()` missed valid directories — directory type resolution failed
+  3. `show_dir()` skipped entries with type 0, logging `"Unknown file type: 0"` — directory listings appeared empty or partial
+- **Affected environments**: overlayfs (Docker image layers), NFS (some implementations), FUSE filesystems (sshfs, s3fs, rclone mount), NixOS with buildFHSEnv, ecryptfs (encrypted home directories), and any filesystem that doesn't fill `d_type` in the kernel's `getdents64` syscall
+- **Impact**: HIGH — Server unusable on affected filesystems (index file not served, directory listing empty)
+- **Fix**: Added `fs.promises.stat()` fallback in all three locations when none of the `dirent.is*()` type methods return `true` (i.e., type is genuinely unknown). On standard filesystems (ext4, btrfs, xfs, APFS, NTFS), `d_type` is always filled correctly, so the `stat()` fallback is never reached — **zero performance overhead** on the fast path.
+- **Code**:
+  - `isFileOrSymlinkToFile()` — DT_UNKNOWN fallback via `stat().isFile()`
+  - `isDirOrSymlinkToDir()` — DT_UNKNOWN fallback via `stat().isDirectory()`
+  - `show_dir()` — Accept type 0 entries and resolve via `stat()` instead of skipping them
+- **Reference**: Linux `man 2 getdents` — *"Currently, only some filesystems have full support for returning the file type in d_type. All applications must properly handle a return of DT_UNKNOWN."*
+
+### 🧪 Testing
+- Added `__tests__/dt-unknown.test.js` with 20 tests covering:
+  - `isFileOrSymlinkToFile` / `isDirOrSymlinkToDir` with DT_UNKNOWN dirents
+  - `findIndexFile` with all-unknown-type entries (string and RegExp patterns)
+  - `show_dir` rendering (resolved types, no skipped entries, correct MIME types and sizes)
+  - Full integration tests (index file serving, direct file access, complete directory listing)
+  - Edge cases (mixed regular + DT_UNKNOWN dirents, index priority, Dirent type 0 verification)
+- Tests use `jest.spyOn(fs.promises, 'readdir')` to mock DT_UNKNOWN dirents via `new fs.Dirent(name, 0)` while keeping `fs.promises.stat()` working normally
+- All 329 tests pass across 12 test suites (zero regressions)
+
+### 📦 Package Changes
+- **Version**: `2.6.0` → `2.6.1`
+- **Semver**: Patch version bump (bug fix only, no API changes)
+
+---
+
 ## [2.6.0] - 2026-03-01
 
 ### 📦 Dependency Upgrades

package/docs/EXAMPLES_INDEX_OPTION.md

@@ -359,8 +359,8 @@ app.use(koaClassicServer('./public', {
     ],
 
     // HTTP Caching
-    enableCaching: true,
-    cacheMaxAge: 3600,
+    browserCacheEnabled: true,
+    browserCacheMaxAge: 3600,
 
     // URL configuration
     urlPrefix: '/static',

package/docs/FLOW_DIAGRAM.md

@@ -141,13 +141,13 @@ module.exports = function koaClassicServer(rootDir, opts = {}) {
         : [];
 
     // 7. Configure HTTP caching
-    options.cacheMaxAge = typeof options.cacheMaxAge === 'number' &&
-                          options.cacheMaxAge >= 0
-        ? options.cacheMaxAge
+    options.browserCacheMaxAge = typeof options.browserCacheMaxAge === 'number' &&
+                                 options.browserCacheMaxAge >= 0
+        ? options.browserCacheMaxAge
         : 3600;
-    options.enableCaching = typeof options.enableCaching === 'boolean'
-        ? options.enableCaching
-        : true;
+    options.browserCacheEnabled = typeof options.browserCacheEnabled === 'boolean'
+        ? options.browserCacheEnabled
+        : false;
 
     // 8. Return Koa middleware function
     return async (ctx, next) => {
@@ -172,8 +172,8 @@ START
   │   ├─ urlsReserved: []
   │   ├─ template.render: undefined
   │   ├─ template.ext: []
-  │   ├─ cacheMaxAge: 3600 (1 hour)
-  │   └─ enableCaching: true
+  │   ├─ browserCacheMaxAge: 3600 (1 hour)
+  │   └─ browserCacheEnabled: false
   │
   └─> Return async middleware function
 ```
@@ -415,7 +415,7 @@ Handles serving individual files with caching, template rendering, and streaming
                          │
                          ▼
 ┌─────────────────────────────────────────────────────────────────┐
-│  3. HTTP Caching (if enableCaching = true)                      │
+│  3. HTTP Caching (if browserCacheEnabled = true)                │
 │     Generate ETag: "mtime-size"                                 │
 │     Set Last-Modified: mtime.toUTCString()                      │
 │     Set Cache-Control: public, max-age=3600                     │
@@ -492,7 +492,7 @@ fileExt in template.ext? → YES
 ### Code Example: HTTP Caching
 ```javascript
 // index.cjs:313-350
-if (options.enableCaching) {
+if (options.browserCacheEnabled) {
     // Generate ETag
     const etag = `"${fileStat.mtime.getTime()}-${fileStat.size}"`;
 
@@ -502,7 +502,7 @@ if (options.enableCaching) {
     // Set headers
     ctx.set('ETag', etag);
     ctx.set('Last-Modified', lastModified);
-    ctx.set('Cache-Control', `public, max-age=${options.cacheMaxAge}, must-revalidate`);
+    ctx.set('Cache-Control', `public, max-age=${options.browserCacheMaxAge}, must-revalidate`);
 
     // Check If-None-Match (ETag validation)
     const clientEtag = ctx.get('If-None-Match');
@@ -782,8 +782,8 @@ app.use(koaClassicServer('/var/www/public', {
     },
 
     // HTTP caching (1 hour)
-    cacheMaxAge: 3600,
-    enableCaching: true
+    browserCacheMaxAge: 3600,
+    browserCacheEnabled: true
 }));
 
 app.listen(3000);