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

package/__tests__/template-timeout.test.js

@@ -0,0 +1,321 @@
+const Koa = require('koa');
+const koaClassicServer = require('../index.cjs');
+const supertest = require('supertest');
+const path = require('path');
+
+const ROOT = path.join(__dirname, 'publicWwwTest');
+const TEMPLATE_URL = '/ejs-templates/simple.ejs';
+
+function buildServer(renderFn, opts = {}) {
+    const app = new Koa();
+    app.silent = true;
+    app.use(koaClassicServer(ROOT, {
+        method: ['GET'],
+        hidden: { dotFiles: { default: 'hidden' }, dotDirs: { default: 'visible' } },
+        template: {
+            ext: ['ejs'],
+            render: renderFn,
+            ...(opts.renderTimeout !== undefined ? { renderTimeout: opts.renderTimeout } : {})
+        }
+    }));
+    const server = app.listen();
+    return { server, request: supertest(server) };
+}
+
+// Sleep that does not keep the event loop alive — used to simulate
+// non-cooperative long-running work without leaving orphan timers behind.
+function unrefSleep(ms) {
+    return new Promise(resolve => {
+        const t = setTimeout(resolve, ms);
+        if (typeof t.unref === 'function') t.unref();
+    });
+}
+
+describe('template.renderTimeout', () => {
+    let consoleErrorSpy;
+
+    beforeEach(() => {
+        consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+        consoleErrorSpy.mockRestore();
+    });
+
+    describe('Factory validation', () => {
+        test('rejects negative renderTimeout', () => {
+            expect(() => koaClassicServer(ROOT, {
+                template: { ext: ['ejs'], render: () => {}, renderTimeout: -1 }
+            })).toThrow(/renderTimeout must be a finite number/);
+        });
+
+        test('rejects non-number renderTimeout', () => {
+            expect(() => koaClassicServer(ROOT, {
+                template: { ext: ['ejs'], render: () => {}, renderTimeout: '5000' }
+            })).toThrow(/renderTimeout must be a finite number/);
+        });
+
+        test('rejects NaN renderTimeout', () => {
+            expect(() => koaClassicServer(ROOT, {
+                template: { ext: ['ejs'], render: () => {}, renderTimeout: NaN }
+            })).toThrow(/renderTimeout must be a finite number/);
+        });
+
+        test('rejects Infinity renderTimeout', () => {
+            expect(() => koaClassicServer(ROOT, {
+                template: { ext: ['ejs'], render: () => {}, renderTimeout: Infinity }
+            })).toThrow(/renderTimeout must be a finite number/);
+        });
+
+        test('accepts 0 (disabled)', () => {
+            expect(() => koaClassicServer(ROOT, {
+                template: { ext: ['ejs'], render: () => {}, renderTimeout: 0 }
+            })).not.toThrow();
+        });
+
+        test('accepts positive integer', () => {
+            expect(() => koaClassicServer(ROOT, {
+                template: { ext: ['ejs'], render: () => {}, renderTimeout: 1000 }
+            })).not.toThrow();
+        });
+
+        test('defaults to 30000 when undefined', () => {
+            const opts = { template: { ext: ['ejs'], render: () => {} } };
+            koaClassicServer(ROOT, opts);
+            expect(opts.template.renderTimeout).toBe(30000);
+        });
+    });
+
+    describe('Successful render within timeout', () => {
+        let env;
+        afterEach(() => env && env.server.close());
+
+        test('returns 200 when render completes before timeout', async () => {
+            env = buildServer(async (ctx) => {
+                await new Promise(r => setTimeout(r, 20));
+                ctx.type = 'text/html';
+                ctx.body = '<p>ok</p>';
+            }, { renderTimeout: 500 });
+
+            const res = await env.request.get(TEMPLATE_URL);
+            expect(res.status).toBe(200);
+            expect(res.text).toContain('ok');
+        });
+    });
+
+    describe('Timeout behaviour', () => {
+        let env;
+        afterEach(() => env && env.server.close());
+
+        test('returns 504 when render exceeds timeout', async () => {
+            env = buildServer(async () => {
+                await unrefSleep(5000);
+            }, { renderTimeout: 100 });
+
+            const res = await env.request.get(TEMPLATE_URL);
+            expect(res.status).toBe(504);
+            expect(res.text).toContain('Gateway Timeout');
+            expect(res.text).toContain('took too long to render');
+        });
+
+        test('504 response carries security headers', async () => {
+            env = buildServer(async () => {
+                await unrefSleep(5000);
+            }, { renderTimeout: 50 });
+
+            const res = await env.request.get(TEMPLATE_URL);
+            expect(res.status).toBe(504);
+            expect(res.headers['content-security-policy']).toMatch(/default-src 'none'/);
+            expect(res.headers['x-content-type-options']).toBe('nosniff');
+            expect(res.headers['x-frame-options']).toBe('DENY');
+        });
+
+        test('renderTimeout: 0 disables the timer (render is allowed to run long)', async () => {
+            env = buildServer(async (ctx) => {
+                await new Promise(r => setTimeout(r, 200));
+                ctx.type = 'text/html';
+                ctx.body = '<p>slow but ok</p>';
+            }, { renderTimeout: 0 });
+
+            const res = await env.request.get(TEMPLATE_URL);
+            expect(res.status).toBe(200);
+            expect(res.text).toContain('slow but ok');
+        });
+    });
+
+    describe('Render argument contract', () => {
+        let env;
+        afterEach(() => env && env.server.close());
+
+        test('render is called with (ctx, next, filePath, rawBuffer, signal) in that order', async () => {
+            let received;
+            env = buildServer(async (...args) => {
+                received = args;
+                args[0].body = 'ok';
+            }, { renderTimeout: 1000 });
+
+            await env.request.get(TEMPLATE_URL);
+
+            expect(received).toHaveLength(5);
+            // ctx: Koa context — must expose req/res/state
+            expect(received[0]).toBeDefined();
+            expect(received[0].req).toBeDefined();
+            expect(received[0].res).toBeDefined();
+            expect(received[0].state).toBeDefined();
+            // next: function (downstream middleware)
+            expect(typeof received[1]).toBe('function');
+            // filePath: absolute path to the requested file
+            expect(typeof received[2]).toBe('string');
+            expect(path.isAbsolute(received[2])).toBe(true);
+            expect(received[2]).toMatch(/simple\.ejs$/);
+            // rawBuffer: Buffer or null depending on serverCache.rawFile state
+            expect(received[3] === null || Buffer.isBuffer(received[3])).toBe(true);
+            // signal: AbortSignal
+            expect(received[4]).toBeInstanceOf(AbortSignal);
+        });
+    });
+
+    describe('AbortSignal contract', () => {
+        let env;
+        afterEach(() => env && env.server.close());
+
+        test('passes an AbortSignal as 5th argument', async () => {
+            let receivedSignal;
+            env = buildServer(async (ctx, _next, _path, _buf, signal) => {
+                receivedSignal = signal;
+                ctx.body = 'ok';
+            }, { renderTimeout: 1000 });
+
+            await env.request.get(TEMPLATE_URL);
+            expect(receivedSignal).toBeInstanceOf(AbortSignal);
+            expect(receivedSignal.aborted).toBe(false);
+        });
+
+        test('signal is NOT aborted after a successful render completes', async () => {
+            let signalAtEnd;
+            let signalRef;
+            env = buildServer(async (ctx, _next, _path, _buf, signal) => {
+                signalRef = signal;
+                await new Promise(r => setTimeout(r, 20));
+                signalAtEnd = signal.aborted;
+                ctx.type = 'text/html';
+                ctx.body = '<p>done</p>';
+            }, { renderTimeout: 1000 });
+
+            const res = await env.request.get(TEMPLATE_URL);
+            expect(res.status).toBe(200);
+            // Signal must not be aborted at the end of a successful render
+            expect(signalAtEnd).toBe(false);
+            // ...and must remain non-aborted after the handler finishes
+            // (i.e. our cleanup must not abort it as a side-effect)
+            await new Promise(r => setTimeout(r, 50));
+            expect(signalRef.aborted).toBe(false);
+        });
+
+        test('signal aborts when render times out', async () => {
+            let signalAtTimeout = null;
+            env = buildServer(async (ctx, _next, _path, _buf, signal) => {
+                await unrefSleep(300);
+                signalAtTimeout = signal.aborted;
+            }, { renderTimeout: 50 });
+
+            const res = await env.request.get(TEMPLATE_URL);
+            expect(res.status).toBe(504);
+            await new Promise(r => setTimeout(r, 400));
+            expect(signalAtTimeout).toBe(true);
+        });
+
+        test('cooperative render that honours signal terminates early', async () => {
+            const renderDuration = jest.fn();
+            env = buildServer(async (ctx, _next, _path, _buf, signal) => {
+                const start = Date.now();
+                try {
+                    await new Promise((resolve, reject) => {
+                        const t = setTimeout(resolve, 5000);
+                        signal.addEventListener('abort', () => {
+                            clearTimeout(t);
+                            reject(new Error('aborted'));
+                        });
+                    });
+                } finally {
+                    renderDuration(Date.now() - start);
+                }
+            }, { renderTimeout: 50 });
+
+            const res = await env.request.get(TEMPLATE_URL);
+            expect(res.status).toBe(504);
+            await new Promise(r => setTimeout(r, 200));
+            const elapsed = renderDuration.mock.calls[0]?.[0] ?? 9999;
+            expect(elapsed).toBeLessThan(1000);
+        });
+    });
+
+    describe('Error handling integrity', () => {
+        let env;
+        afterEach(() => env && env.server.close());
+
+        test('late rejection after timeout does not crash the process', async () => {
+            const unhandledHandler = jest.fn();
+            process.on('unhandledRejection', unhandledHandler);
+
+            env = buildServer(async () => {
+                await new Promise(r => setTimeout(r, 100));
+                throw new Error('late failure');
+            }, { renderTimeout: 30 });
+
+            const res = await env.request.get(TEMPLATE_URL);
+            expect(res.status).toBe(504);
+
+            await new Promise(r => setTimeout(r, 250));
+            process.off('unhandledRejection', unhandledHandler);
+            expect(unhandledHandler).not.toHaveBeenCalled();
+        });
+
+        test('synchronous render returning rejected promise still produces 500', async () => {
+            env = buildServer(() => Promise.reject(new Error('boom')), { renderTimeout: 1000 });
+
+            const res = await env.request.get(TEMPLATE_URL);
+            expect(res.status).toBe(500);
+            expect(res.text).toContain('Internal Server Error');
+        });
+
+        test('synchronous throw in render produces 500', async () => {
+            env = buildServer(() => { throw new Error('sync boom'); }, { renderTimeout: 1000 });
+
+            const res = await env.request.get(TEMPLATE_URL);
+            expect(res.status).toBe(500);
+            expect(res.text).toContain('Internal Server Error');
+        });
+    });
+
+    describe('Client disconnect', () => {
+        let env;
+        afterEach(() => env && env.server.close());
+
+        test('signal aborts when client closes the connection before render finishes', async () => {
+            let abortObserved = false;
+            env = buildServer(async (ctx, _next, _path, _buf, signal) => {
+                signal.addEventListener('abort', () => { abortObserved = true; });
+                await unrefSleep(1000);
+                ctx.body = 'late';
+            }, { renderTimeout: 0 });
+
+            const addr = env.server.address();
+            const http = require('http');
+            await new Promise((resolve) => {
+                const req = http.request({
+                    host: addr.address === '::' ? '127.0.0.1' : addr.address,
+                    port: addr.port,
+                    path: TEMPLATE_URL,
+                    method: 'GET'
+                }, () => {});
+                req.on('error', () => {});
+                req.end();
+                setTimeout(() => { req.destroy(); resolve(); }, 50);
+            });
+
+            await new Promise(r => setTimeout(r, 100));
+            expect(abortObserved).toBe(true);
+        });
+    });
+});

package/docs/CHANGELOG.md

@@ -5,7 +5,7 @@ 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
+## [3.0.0] - 2026-05-13
 
 ### 🆕 New Features
 
@@ -49,12 +49,197 @@ app.use(koaClassicServer('/public', {
 **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 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.
+#### 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
 
-To restore v2.x behavior: `hidden: { dotFiles: { default: 'visible' } }`
+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
@@ -87,6 +272,26 @@ To restore v2.x behavior: `hidden: { dotFiles: { default: 'visible' } }`
   }));
   ```
 
+#### 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

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