koa-classic-server 2.6.1 → 3.0.0

package/README.md

@@ -1,35 +1,34 @@
 # koa-classic-server
 
-🚀 **Production-ready Koa middleware** for serving static files with Apache2-like directory listing, sortable columns, HTTP caching, template engine support, and enterprise-grade security.
+🚀 **Production-ready Koa middleware** for serving static files with Apache2-like directory listing, sortable columns, pagination, hash-based CSP, template-engine timeouts, injectable logging, and enterprise-grade security.
 
 [![npm version](https://img.shields.io/npm/v/koa-classic-server.svg)](https://www.npmjs.com/package/koa-classic-server)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Tests](https://img.shields.io/badge/tests-309%20passing-brightgreen.svg)]()
+[![Tests](https://img.shields.io/badge/tests-532%20passing-brightgreen.svg)]()
+[![Node](https://img.shields.io/badge/node-%3E%3D18-blue.svg)]()
 
 ---
 
-## 🎉 Version 2.X - Production-Ready Release
-
-The 2.X series brings major performance improvements, enhanced security, and powerful new features while maintaining full backward compatibility.
-
-### Key Features in Version 2.X
-
-✅ **URL Rewriting Support** - Compatible with i18n and routing middleware via `useOriginalUrl` option
-✅ **Improved Caching Controls** - Clear `browserCacheEnabled` and `browserCacheMaxAge` options
-✅ **Development-Friendly Defaults** - Caching disabled by default for easier development
-✅ **Production Optimized** - Enable caching in production for 80-95% bandwidth reduction
-✅ **Sortable Directory Columns** - Click Name/Type/Size to sort (Apache2-like)
-✅ **File Size Display** - Human-readable file sizes (B, KB, MB, GB, TB)
-✅ **HTTP Caching** - ETag and Last-Modified headers with 304 responses
-✅ **Async/Await** - Non-blocking I/O for high performance
-✅ **Performance Optimized** - 50-70% faster directory listings
-✅ **Enhanced Index Option** - Array format with RegExp support
-✅ **Template Engine Support** - EJS, Pug, Handlebars, Nunjucks, and more
-✅ **Enterprise Security** - Path traversal, XSS, race condition protection
-✅ **Clean URLs** - Hide file extensions with `hideExtension` (mod_rewrite-like behavior)
-✅ **Symlink Support** - Full symbolic link support (NixOS, Docker, npm link, Capistrano)
-✅ **Comprehensive Testing** - 309 tests passing with extensive coverage
-✅ **Complete Documentation** - Detailed guides and examples
+## 🎉 Version 3.0 — File Server First, Observable, Bounded
+
+The 3.0 series builds on 2.x with new observability hooks, bounded resource usage on accidentally-large directories, and a more focused **design philosophy**: koa-classic-server is an **HTTP file server first** — defaults serve files without applying surprise restrictions, and hardening is opt-in via explicit configuration plus a documented Security Checklist.
+
+### Key Features in Version 3.x
+
+✅ **Design philosophy made explicit** — *"if a file is in `rootDir`, `GET` returns it"* — codified in [`CLAUDE.md`](./CLAUDE.md), with a **Security Checklist** + **Suggested Production Security Configuration** in this README and `docs/DOCUMENTATION.md`
+✅ **`dirListing` namespace** — listing options grouped under one structured object (`enabled`, `maxEntries`, `entriesPerPage`); the v2 `showDirContents` flag is kept as a deprecated alias with a one-time warning
+✅ **Soft cap on listing rendering** — `dirListing.maxEntries` defaults to `100000` as a *safety net* against accidentally-huge directories (broken log rotation, mistakenly mounted FS), NOT as a policy restriction; banner + `X-Dir-Truncated` header on the rare hit. Opt-in RAM-bounded streaming reads planned for v3.1.
+✅ **Paginated listings** — `dirListing.entriesPerPage` adds 0-based `?page=N` navigation with First/Prev/Next/Last + `X-Dir-Pagination` header
+✅ **Template render timeout + AbortSignal** — `template.renderTimeout` (default 30s) + a per-request `template.signal` so slow renders never wedge the server
+✅ **Injectable logger** — pass any `{ error, warn, info, debug }`-shaped logger (Pino, Bunyan, Winston, console) for full observability
+✅ **Hash-based CSP on listing page** — automatic SHA-256 of inline CSS, recomputed at module load
+✅ **Security headers on generated pages** — `CSP`, `X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy`, `Permissions-Policy` on listing + error pages
+✅ **Sortable Directory Columns** — Click Name/Type/Size to sort (Apache2-like) with sort/order preserved across paginator links
+✅ **HTTP Caching** — ETag, Last-Modified, conditional 304 responses (opt-in via `browserCacheEnabled`)
+✅ **Template Engine Support** — EJS, Pug, Handlebars, Nunjucks, and more — with full async/await, AbortSignal forwarding, and timeout enforcement
+✅ **Clean URLs** — Hide file extensions via `hideExtension` (mod_rewrite-like)
+✅ **Symlink Support** — Transparent resolution + clear indicators in the listing
+✅ **532 tests passing** — comprehensive coverage including security, listing pagination, logger injection, template timeouts, and edge cases
 
 [See full changelog →](./docs/CHANGELOG.md)
 
@@ -37,23 +36,26 @@ The 2.X series brings major performance improvements, enhanced security, and pow
 
 ## Features
 
-**koa-classic-server** is a high-performance middleware for serving static files with Apache2-like behavior, making file browsing intuitive and powerful.
+**koa-classic-server** is a high-performance middleware for serving static files with Apache2-like behavior, making file browsing intuitive, observable, and safe.
 
 ### Core Features
 
-- 🗂️ **Apache2-like Directory Listing** - Sortable columns (Name, Type, Size)
-- 📄 **Static File Serving** - Automatic MIME type detection with streaming
-- 📊 **Sortable Columns** - Click headers to sort ascending/descending
-- 📏 **File Sizes** - Human-readable display (B, KB, MB, GB, TB)
-- ⚡ **HTTP Caching** - ETag, Last-Modified, 304 responses
-- 🎨 **Template Engine Support** - EJS, Pug, Handlebars, Nunjucks, etc.
-- 🔒 **Enterprise Security** - Path traversal, XSS, race condition protection
-- ⚙️ **Highly Configurable** - URL prefixes, reserved paths, index files
-- 🚀 **High Performance** - Async/await, non-blocking I/O, optimized algorithms
-- 🔗 **Symlink Support** - Transparent symlink resolution with directory listing indicators
-- 🌐 **Clean URLs** - Hide file extensions for SEO-friendly URLs via `hideExtension`
-- 🧪 **Well-Tested** - 309 passing tests with comprehensive coverage
-- 📦 **Dual Module Support** - CommonJS and ES Modules
+- 🗂️ **Apache2-like Directory Listing** — Sortable columns (Name, Type, Size)
+- 📄 **Static File Serving** — Automatic MIME type detection with streaming
+- 📊 **Sortable Columns** — Click headers to sort ascending/descending
+- 📏 **File Sizes** — Human-readable display (B, KB, MB, GB, TB)
+- 📃 **Bounded + Paginated Listings** — `dirListing.maxEntries` cap + `dirListing.entriesPerPage` navigation
+- ⏱️ **Template Render Timeout** — Configurable timeout with AbortSignal propagation
+- 📝 **Injectable Logger** — Plug Pino/Bunyan/Winston/console at construction time
+- ⚡ **HTTP Caching** — ETag, Last-Modified, 304 responses (opt-in)
+- 🎨 **Template Engine Support** — EJS, Pug, Handlebars, Nunjucks, etc.
+- 🔒 **Enterprise Security** — Path traversal, XSS, race condition protection, CSP, dot-file hiding
+- ⚙️ **Highly Configurable** — URL prefixes, reserved paths, index files, hidden patterns
+- 🚀 **High Performance** — Async/await, non-blocking I/O, single-syscall directory reads
+- 🔗 **Symlink Support** — Transparent resolution with directory listing indicators
+- 🌐 **Clean URLs** — Hide file extensions for SEO-friendly URLs via `hideExtension`
+- 🧪 **Well-Tested** — 532 passing tests with comprehensive coverage
+- 📦 **Dual Module Support** — CommonJS and ES Modules
 
 ---
 
@@ -95,11 +97,15 @@ const koaClassicServer = require('koa-classic-server');
 const app = new Koa();
 
 app.use(koaClassicServer(__dirname + '/public', {
-  showDirContents: true,
   index: ['index.html', 'index.htm'],
   urlPrefix: '/static',
-  browserCacheMaxAge: 3600,
-  browserCacheEnabled: true
+  dirListing: {
+    enabled:        true,
+    maxEntries:     5000,    // cap huge directories
+    entriesPerPage: 50,      // 50 entries per listing page
+  },
+  browserCacheEnabled: true,
+  browserCacheMaxAge:  3600,
 }));
 
 app.listen(3000);
@@ -121,365 +127,222 @@ import koaClassicServer from 'koa-classic-server';
 
 ### 2. Basic File Server
 
-Serve static files from a directory:
-
 ```javascript
 const Koa = require('koa');
+const path = require('path');
 const koaClassicServer = require('koa-classic-server');
 
 const app = new Koa();
 
-app.use(koaClassicServer(__dirname + '/public', {
-  showDirContents: true,
-  index: ['index.html']
+app.use(koaClassicServer(path.join(__dirname, 'public'), {
+  dirListing: { enabled: true },
+  index: ['index.html'],
 }));
 
 app.listen(3000);
 ```
 
-**What it does:**
-- Serves files from `/public` directory
-- Shows directory listing when accessing folders
-- Looks for `index.html` in directories
-- Sortable columns (Name, Type, Size)
-- File sizes displayed in human-readable format
-
 ### 3. With URL Prefix
 
-Serve files under a specific URL path:
-
 ```javascript
-app.use(koaClassicServer(__dirname + '/assets', {
+app.use(koaClassicServer(__dirname + '/public', {
   urlPrefix: '/static',
-  showDirContents: true
 }));
+// http://localhost:3000/static/image.png → public/image.png
 ```
 
-**Result:**
-- `http://localhost:3000/static/image.png` → serves `/assets/image.png`
-- `http://localhost:3000/static/` → shows `/assets` directory listing
-
 ### 4. With Reserved Paths
 
-Protect specific directories from being accessed:
-
 ```javascript
-app.use(koaClassicServer(__dirname + '/www', {
-  urlsReserved: ['/admin', '/config', '/.git', '/node_modules']
+app.use(koaClassicServer(__dirname, {
+  urlsReserved: ['/api', '/admin', '/.git', '/node_modules'],
 }));
+// /api/* is passed through to the next middleware untouched.
 ```
 
-**Result:**
-- `/admin/*` → passed to next middleware (not served)
-- `/config/*` → protected
-- Other paths → served normally
+### 5. Bounded + Paginated Directory Listings (V3)
 
-### 5. With Template Engine (EJS)
-
-Dynamically render templates with data:
+For directories that may grow without bound (uploads, archives, logs), cap the maximum number of entries the middleware will enumerate and paginate what's visible:
 
 ```javascript
-const ejs = require('ejs');
-
-app.use(koaClassicServer(__dirname + '/views', {
-  template: {
-    ext: ['ejs', 'html.ejs'],
-    render: async (ctx, next, filePath) => {
-      const data = {
-        title: 'My App',
-        user: ctx.state.user || { name: 'Guest' },
-        items: ['Item 1', 'Item 2', 'Item 3'],
-        timestamp: new Date().toISOString()
-      };
-
-      ctx.body = await ejs.renderFile(filePath, data);
-      ctx.type = 'text/html';
-    }
-  }
+app.use(koaClassicServer(__dirname + '/uploads', {
+  dirListing: {
+    enabled:        true,
+    maxEntries:     10000,  // cap visible / sorted / stat'd entries (default; 0 = disabled)
+    entriesPerPage: 100,    // entries per page in the listing UI (default; 0 = disabled)
+  },
 }));
 ```
 
-**Template example (`views/dashboard.ejs`):**
-```html
-<!DOCTYPE html>
-<html>
-<head>
-    <title><%= title %></title>
-</head>
-<body>
-    <h1>Welcome, <%= user.name %>!</h1>
-    <ul>
-    <% items.forEach(item => { %>
-        <li><%= item %></li>
-    <% }); %>
-    </ul>
-    <p>Generated at: <%= timestamp %></p>
-</body>
-</html>
-```
+**What happens on a directory with 1,000,000 files**
 
-**See complete guide:** [Template Engine Documentation →](./docs/template-engine/TEMPLATE_ENGINE_GUIDE.md)
+- The middleware calls `fs.promises.readdir()` once and slices the result to `dirListing.maxEntries` — sorting, stat'ing, and rendering are CPU-bounded by `dirListing.maxEntries`. The initial `readdir()` itself is **not** bounded (see v3.1 roadmap for an opt-in streaming mode targeting adversarial-directory workloads).
+- A yellow banner appears at the top of the listing: *"Showing first 10000 entries (cap reached)…"*
+- The response carries `X-Dir-Truncated: 10000` so monitoring can flag capped pages.
+- Pagination is rendered below the table with `« First · ‹ Prev · 0 1 … N · Next › · Last »`, and an `X-Dir-Pagination: <current>/<last>` response header is set.
+- Navigate via `?page=N` (0-based). Out-of-range values clamp silently to the nearest valid page. Active `sort` / `order` query params are preserved across paginator links.
 
-### 6. Clean URLs with hideExtension
+### 6. Template Engine with Timeout + AbortSignal (V3)
 
-Hide file extensions from URLs, similar to Apache's `mod_rewrite`:
+V3 hardens template rendering against runaway or hung renders: the middleware enforces a configurable timeout and forwards a `template.signal` (AbortSignal) you can use inside your renderer to abort I/O and long-running work.
 
 ```javascript
 const ejs = require('ejs');
+const koaClassicServer = require('koa-classic-server');
 
-app.use(koaClassicServer(__dirname + '/public', {
-  showDirContents: true,
-  index: ['index.ejs'],
-  hideExtension: {
-    ext: '.ejs',      // Extension to hide (required)
-    redirect: 301     // HTTP redirect code (optional, default: 301)
-  },
+app.use(koaClassicServer(__dirname + '/views', {
   template: {
     ext: ['ejs'],
-    render: async (ctx, next, filePath) => {
+    renderTimeout: 5000,  // 5s hard cap (default 30000ms; 0 disables the cap)
+    render: async (ctx, next, filePath, { signal }) => {
+      // Forward the signal to your I/O — fetch, DB queries, async work.
+      const data = await fetchData({ signal });
+      if (signal.aborted) return;
       ctx.body = await ejs.renderFile(filePath, data);
-      ctx.type = 'text/html';
-    }
-  }
+      ctx.type  = 'text/html';
+    },
+  },
 }));
 ```
 
-**URL Behavior:**
-
-| Request URL | Action | Result |
-|-------------|--------|--------|
-| `/about` | Resolves `about.ejs` | Serves file (200) |
-| `/blog/article` | Resolves `blog/article.ejs` | Serves file (200) |
-| `/about.ejs` | Redirect | 301 → `/about` |
-| `/about.ejs?lang=it` | Redirect | 301 → `/about?lang=it` |
-| `/index.ejs` | Redirect | 301 → `/` |
-| `/section/index.ejs` | Redirect | 301 → `/section/` |
-| `/style.css` | No interference | Normal flow |
-| `/about/` | No interference | Shows directory listing |
-
-**Conflict Resolution:**
+If the renderer exceeds `renderTimeout`, the request fails closed with a 500 and a single warning is emitted via the configured logger — the response stream is never left half-written.
 
-- **Directory vs file**: When both `about/` directory and `about.ejs` file exist, `/about` serves the file. Use `/about/` to access the directory.
-- **Extensionless vs extension**: When both `about` (no ext) and `about.ejs` exist, `/about` always serves `about.ejs`. The extensionless file becomes unreachable.
+### 7. Injectable Logger (V3)
 
-> **Note**: This conflict resolution behavior differs from Apache/Nginx, where directories typically take priority over files with the same base name.
-
-### 7. URL Rewriting Support (useOriginalUrl)
-
-When using URL rewriting middleware (i18n, routing), set `useOriginalUrl: false` so koa-classic-server resolves files from the rewritten URL instead of the original one:
+By default the middleware logs to `console`. Pass any object exposing `error`, `warn`, `info`, `debug` to integrate with your production logging stack:
 
 ```javascript
-const Koa = require('koa');
-const koaClassicServer = require('koa-classic-server');
+const pino = require('pino')();
 
-const app = new Koa();
-
-// i18n middleware: strips language prefix and rewrites ctx.url
-app.use(async (ctx, next) => {
-  const langMatch = ctx.path.match(/^\/(it|en|fr|de|es)\//);
-  if (langMatch) {
-    ctx.state.lang = langMatch[1];       // Save language for templates
-    ctx.url = ctx.path.replace(/^\/(it|en|fr|de|es)/, '') + ctx.search;
-  }
-  await next();
-});
-
-// Serve files using the rewritten URL
 app.use(koaClassicServer(__dirname + '/public', {
-  useOriginalUrl: false  // Use ctx.url (rewritten) instead of ctx.originalUrl
+  logger: pino,  // any { error, warn, info, debug }-shaped object works
 }));
-
-app.listen(3000);
 ```
 
-**How it works:**
-
-| Request | `ctx.originalUrl` | `ctx.url` (rewritten) | File resolved |
-|---------|-------------------|----------------------|---------------|
-| `/it/page.html` | `/it/page.html` | `/page.html` | `public/page.html` |
-| `/en/page.html` | `/en/page.html` | `/page.html` | `public/page.html` |
-| `/page.html` | `/page.html` | `/page.html` | `public/page.html` |
+- Backward compatible: when `logger` is omitted, behavior is unchanged (uses `console`).
+- All internal warnings and errors flow through the same logger — useful for routing them to Sentry, Datadog, or stdout JSON.
 
-- With `useOriginalUrl: true` (default): the server would look for `public/it/page.html` (which doesn't exist)
-- With `useOriginalUrl: false`: the server looks for `public/page.html` (correct)
+### 8. Hidden Files & Dot-File Protection (V3 default: hidden)
 
-### 8. Advanced hideExtension Scenarios
+Dot-files and dot-directories are **visible by default in v3** — aligned with the "file server first" philosophy (see [`CLAUDE.md`](./CLAUDE.md)). For production deployments where `.env`, `.git/config`, etc. could be served accidentally, **opt into hardening** explicitly via `hidden.dotFiles.default: 'hidden'`. This is the first item on the [Security Checklist](#design-philosophy--security-checklist).
 
-#### Recommended file structure
-
-```
-views/
-├── index.ejs              ← / (home page)
-├── about.ejs              ← /about
-├── contact.ejs            ← /contact
-├── blog/
-│   ├── index.ejs          ← /blog/
-│   ├── first-post.ejs     ← /blog/first-post
-│   └── second-post.ejs    ← /blog/second-post
-├── docs/
-│   ├── index.ejs          ← /docs/
-│   ├── getting-started.ejs ← /docs/getting-started
-│   └── api-reference.ejs  ← /docs/api-reference
-└── assets/
-    ├── style.css          ← /assets/style.css (served normally)
-    └── script.js          ← /assets/script.js (served normally)
+```javascript
+app.use(koaClassicServer(__dirname + '/www', {
+  hidden: {
+    dotFiles: {
+      default:   'hidden',                    // 'hidden' | 'visible'
+      whitelist: ['.well-known', '.htaccess'],// exact name, glob, or RegExp
+      blacklist: [],                          // overrides whitelist
+    },
+    dotDirs: {
+      default:   'visible',
+      whitelist: [],
+      blacklist: ['.git'],
+    },
+    alwaysHide: ['*.key', /secret/i, '/private/**'], // path-aware patterns
+  },
+}));
 ```
 
-#### hideExtension with i18n middleware
+### 9. Clean URLs with `hideExtension`
 
-Combine `hideExtension` with `useOriginalUrl: false` for multilingual sites with clean URLs:
+Serve `.ejs` (or any extension) as extensionless URLs and 301-redirect the canonical form:
 
 ```javascript
-const Koa = require('koa');
-const koaClassicServer = require('koa-classic-server');
-const ejs = require('ejs');
-
-const app = new Koa();
-
-// i18n middleware: /it/about → ctx.url = /about, ctx.state.lang = 'it'
-app.use(async (ctx, next) => {
-  const langMatch = ctx.path.match(/^\/(it|en|fr)\//);
-  if (langMatch) {
-    ctx.state.lang = langMatch[1];
-    ctx.url = ctx.path.replace(/^\/(it|en|fr)/, '') + ctx.search;
-  } else {
-    ctx.state.lang = 'en';  // Default language
-  }
-  await next();
-});
-
 app.use(koaClassicServer(__dirname + '/views', {
-  index: ['index.ejs'],
-  useOriginalUrl: false,     // Resolve files from rewritten URL
   hideExtension: {
-    ext: '.ejs',
-    redirect: 301
+    ext: '.ejs',     // required, must start with '.'
+    redirect: 301,   // optional, 301 (default) or 302
   },
   template: {
     ext: ['ejs'],
     render: async (ctx, next, filePath) => {
-      ctx.body = await ejs.renderFile(filePath, { lang: ctx.state.lang });
-      ctx.type = 'text/html';
-    }
-  }
+      ctx.body = await ejs.renderFile(filePath);
+      ctx.type  = 'text/html';
+    },
+  },
 }));
-
-app.listen(3000);
+// GET /about      → serves views/about.ejs
+// GET /about.ejs  → 301 redirect to /about
 ```
 
-**Result:**
-
-| Request | Rewritten URL | File resolved | Redirect target |
-|---------|---------------|---------------|-----------------|
-| `/it/about` | `/about` | `views/about.ejs` | — |
-| `/en/blog/first-post` | `/blog/first-post` | `views/blog/first-post.ejs` | — |
-| `/it/about.ejs` | `/about.ejs` | — | 301 → `/it/about` (preserves `/it/` prefix) |
+### 10. URL Rewriting Support (`useOriginalUrl`)
 
-> **Note**: Redirects always use `ctx.originalUrl` to preserve the language prefix, regardless of the `useOriginalUrl` setting.
-
-#### Temporary redirect (302)
-
-Use `redirect: 302` instead of 301 when the URL mapping may change (staging, A/B testing, or during migration):
+Set `useOriginalUrl: false` when running behind i18n routers or path-rewriters that mutate `ctx.url`:
 
 ```javascript
-hideExtension: {
-  ext: '.ejs',
-  redirect: 302   // Temporary redirect — browsers won't cache it
-}
-```
-
-> **When to use 302**: A 301 (permanent) tells browsers and search engines to cache the redirect. Use 302 (temporary) during development, staging, or when you're not yet sure the clean URL structure is final.
-
-### 9. With HTTP Caching
-
-Enable aggressive caching for static files:
+app.use(async (ctx, next) => {
+  if (ctx.path.startsWith('/it/')) {
+    ctx.url = ctx.path.replace(/^\/it/, '');  // /it/page.html → /page.html
+  }
+  await next();
+});
 
-```javascript
-app.use(koaClassicServer(__dirname + '/public', {
-  browserCacheEnabled: true,       // Enable ETag and Last-Modified
-  browserCacheMaxAge: 86400,        // Cache for 24 hours (in seconds)
+app.use(koaClassicServer(__dirname + '/www', {
+  useOriginalUrl: false,  // use ctx.url (rewritten) instead of ctx.originalUrl
 }));
 ```
 
-**⚠️ Important: Production Recommendation**
-
-The default value for `browserCacheEnabled` is `false` to facilitate development (where you want changes to be immediately visible). **For production environments, it is strongly recommended to set `browserCacheEnabled: true`** to benefit from:
-
-- 80-95% bandwidth reduction
-- 304 Not Modified responses for unchanged files
-- Faster page loads for returning visitors
-- Reduced server load
-
-**See details:** [HTTP Caching Optimization →](./docs/OPTIMIZATION_HTTP_CACHING.md)
-
-### 10. Multiple Index Files with Priority
-
-Search for multiple index files with custom order:
+### 11. HTTP Caching (opt-in)
 
 ```javascript
 app.use(koaClassicServer(__dirname + '/public', {
-  index: [
-    'index.html',           // First priority
-    'index.htm',            // Second priority
-    /index\.[eE][jJ][sS]/,  // Third: index.ejs (case-insensitive)
-    'default.html'          // Last priority
-  ]
+  browserCacheEnabled: true,     // emit ETag + Last-Modified, honor If-None-Match / If-Modified-Since
+  browserCacheMaxAge:  86400,    // Cache-Control: max-age=86400 (24h)
 }));
 ```
 
-**See details:** [Index Option Priority →](./docs/INDEX_OPTION_PRIORITY.md)
+Defaults: `browserCacheEnabled: false` (development-friendly). Enable in production for an 80–95% bandwidth reduction on cache hits.
 
-### 11. Complete Production Example
-
-Real-world configuration for production:
+### 12. Complete Production Example
 
 ```javascript
-const Koa = require('koa');
-const koaClassicServer = require('koa-classic-server');
-const ejs = require('ejs');
+const Koa  = require('koa');
 const path = require('path');
+const pino = require('pino')({ level: 'info' });
+const ejs  = require('ejs');
+const koaClassicServer = require('koa-classic-server');
 
 const app = new Koa();
 
-// Serve static assets with caching
+// Allowlist Host headers to mitigate DNS rebinding (see docs/DOCUMENTATION.md → Sicurezza).
+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 = 'Host not allowed'; return; }
+  await next();
+});
+
+// Static-file security headers (see docs/DOCUMENTATION.md → Limiti dei Security Headers).
+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();
+});
+
 app.use(koaClassicServer(path.join(__dirname, 'public'), {
-  method: ['GET', 'HEAD'],
-  showDirContents: false,  // Disable directory listing in production
-  index: ['index.html', 'index.htm'],
-  urlPrefix: '/assets',
-  urlsReserved: ['/admin', '/api', '/.git'],
+  index: ['index.html'],
+  dirListing: {
+    enabled:        process.env.NODE_ENV !== 'production',
+    maxEntries:     10000,
+    entriesPerPage: 100,
+  },
   browserCacheEnabled: true,
-  browserCacheMaxAge: 86400,  // 24 hours
-}));
-
-// Serve dynamic templates with clean URLs
-app.use(koaClassicServer(path.join(__dirname, 'views'), {
-  showDirContents: false,
-  index: ['index.ejs'],
-  useOriginalUrl: false,  // Use ctx.url (for i18n or routing middleware)
-  hideExtension: {
-    ext: '.ejs',           // /about → serves about.ejs
-    redirect: 301          // /about.ejs → 301 redirect to /about
+  browserCacheMaxAge:  86400,
+  logger:              pino,
+  hidden: {
+    dotFiles: { default: 'hidden', whitelist: ['.well-known'] },
+    dotDirs:  { default: 'hidden', whitelist: ['.well-known'] },
+    alwaysHide: ['*.key', /^backup-/],
   },
   template: {
-    ext: ['ejs'],
-    render: async (ctx, next, filePath) => {
-      const data = {
-        env: process.env.NODE_ENV,
-        user: ctx.state.user,
-        config: ctx.state.config
-      };
-
-      try {
-        ctx.body = await ejs.renderFile(filePath, data);
-        ctx.type = 'text/html';
-      } catch (error) {
-        console.error('Template error:', error);
-        ctx.status = 500;
-        ctx.body = 'Internal Server Error';
-      }
-    }
-  }
+    ext:           ['ejs'],
+    renderTimeout: 5000,
+    render: async (ctx, next, filePath, { signal }) => {
+      ctx.body = await ejs.renderFile(filePath, { user: ctx.state.user }, { signal });
+      ctx.type = 'text/html';
+    },
+  },
 }));
 
 app.listen(3000);
@@ -489,243 +352,324 @@ app.listen(3000);
 
 ## API Reference
 
-### koaClassicServer(rootDir, options)
+### `koaClassicServer(rootDir, options)`
 
 Creates a Koa middleware for serving static files.
 
 **Parameters:**
-
-- **`rootDir`** (String, required): Absolute path to the directory containing files
-- **`options`** (Object, optional): Configuration options
+- **`rootDir`** *(String, required)* — Absolute path to the directory containing files
+- **`options`** *(Object, optional)* — Configuration options
 
 **Returns:** Koa middleware function
 
-### Options
+### Options Summary
 
 ```javascript
 {
   // HTTP methods allowed (default: ['GET'])
   method: ['GET', 'HEAD'],
 
-  // Show directory contents (default: true)
-  showDirContents: true,
+  // Directory listing (V3 namespace)
+  dirListing: {
+    enabled:        true,
+    maxEntries:     10000,   // cap visible entries (0 = disabled)
+    entriesPerPage: 100,     // entries per page (0 = disabled)
+  },
 
-  // Index file configuration
-  // Array format (recommended):
-  //   - Strings: exact matches ['index.html', 'default.html']
-  //   - RegExp: pattern matches [/index\.html/i]
-  //   - Mixed: ['index.html', /INDEX\.HTM/i]
-  // Priority determined by array order (first match wins)
-  // See docs/INDEX_OPTION_PRIORITY.md for details
+  // Index file resolution (Array of strings and/or RegExp)
   index: ['index.html', 'index.htm'],
 
-  // URL path prefix (default: '')
-  // Files served under this prefix
-  urlPrefix: '/static',
-
-  // Reserved paths (default: [])
-  // First-level directories passed to next middleware
-  urlsReserved: ['/admin', '/api', '/.git'],
-
-  // Template engine configuration
-  template: {
-    // Template rendering function
-    render: async (ctx, next, filePath) => {
-      // Your rendering logic
-      ctx.body = await yourEngine.render(filePath, data);
-    },
+  // URL routing
+  urlPrefix:    '/static',
+  urlsReserved: ['/api', '/admin'],
+  useOriginalUrl: true,
 
-    // File extensions to process
-    ext: ['ejs', 'pug', 'hbs']
+  // Hidden files / dirs
+  hidden: {
+    dotFiles: { default: 'visible', whitelist: [], blacklist: [] },
+    dotDirs:  { default: 'visible', whitelist: [], blacklist: [] },
+    alwaysHide: [],
   },
 
-  // Browser HTTP caching configuration
-  // NOTE: Default is false for development. Set to true in production for better performance!
-  browserCacheEnabled: false,     // Enable ETag & Last-Modified (default: false)
-  browserCacheMaxAge: 3600,        // Cache-Control max-age in seconds (default: 3600 = 1 hour)
+  // Clean URLs
+  hideExtension: { ext: '.ejs', redirect: 301 },
 
-  // URL resolution
-  useOriginalUrl: true,     // Use ctx.originalUrl (default) or ctx.url
-                            // Set false for URL rewriting middleware (i18n, routing)
+  // Browser HTTP caching
+  browserCacheEnabled: false,
+  browserCacheMaxAge:  3600,
 
-  // Clean URLs - hide file extension from URLs (mod_rewrite-like)
-  hideExtension: {
-    ext: '.ejs',            // Extension to hide (required, must start with '.')
-    redirect: 301           // HTTP redirect code (optional, default: 301)
+  // Template engine
+  template: {
+    ext:           ['ejs'],
+    renderTimeout: 30000,   // ms; 0 disables the cap
+    render: async (ctx, next, filePath, { signal }) => { /* ... */ },
   },
 
-  // DEPRECATED (use new names above):
-  // enableCaching: use browserCacheEnabled instead
-  // cacheMaxAge: use browserCacheMaxAge instead
+  // Observability
+  logger: console,          // any { error, warn, info, debug } shape
 }
 ```
 
 ### Options Details
 
 | Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `method` | Array | `['GET']` | Allowed HTTP methods |
-| `showDirContents` | Boolean | `true` | Show directory listing |
-| `index` | Array/String | `[]` | Index file patterns (array format recommended) |
-| `urlPrefix` | String | `''` | URL path prefix |
-| `urlsReserved` | Array | `[]` | Reserved directory paths (first-level only) |
-| `template.render` | Function | `undefined` | Template rendering function |
-| `template.ext` | Array | `[]` | Extensions for template rendering |
-| `browserCacheEnabled` | Boolean | `false` | Enable browser HTTP caching headers (recommended: `true` in production) |
-| `browserCacheMaxAge` | Number | `3600` | Browser cache duration in seconds |
-| `useOriginalUrl` | Boolean | `true` | Use `ctx.originalUrl` (default) or `ctx.url` for URL resolution |
-| `hideExtension.ext` | String | - | Extension to hide (e.g. `'.ejs'`). Enables clean URL feature |
-| `hideExtension.redirect` | Number | `301` | HTTP redirect code for URLs with extension |
-| ~~`enableCaching`~~ | Boolean | `false` | **DEPRECATED**: Use `browserCacheEnabled` instead |
-| ~~`cacheMaxAge`~~ | Number | `3600` | **DEPRECATED**: Use `browserCacheMaxAge` instead |
-
-#### useOriginalUrl (Boolean, default: true)
-
-Controls which URL property is used for file resolution:
-- **`true` (default)**: Uses `ctx.originalUrl` (immutable, reflects the original request)
-- **`false`**: Uses `ctx.url` (mutable, can be modified by middleware)
-
-**When to use `false`:**
-
-Set `useOriginalUrl: false` when using URL rewriting middleware such as i18n routers or path rewriters that modify `ctx.url`. This allows koa-classic-server to serve files based on the rewritten URL instead of the original request URL.
-
-**Example with i18n middleware:**
+|---|---|---|---|
+| `method` | `String[]` | `['GET']` | Allowed HTTP methods |
+| `dirListing.enabled` | `Boolean` | `true` | **V3** Render directory listing HTML when no index file matches |
+| `dirListing.maxEntries` | `Number` | `10000` | **V3** Cap entries shown / sorted / stat'd (0 = disabled) |
+| `dirListing.entriesPerPage` | `Number` | `100` | **V3** Entries per listing page (0 = disabled) |
+| `index` | `Array` | `[]` | Index file patterns (strings, RegExp, or mixed) |
+| `urlPrefix` | `String` | `''` | URL path prefix |
+| `urlsReserved` | `String[]` | `[]` | First-level paths passed through to next middleware |
+| `useOriginalUrl` | `Boolean` | `true` | Use `ctx.originalUrl` (`true`) or `ctx.url` (`false`) |
+| `hideExtension.ext` | `String` | – | Extension to hide (`.ejs`, must start with `.`) |
+| `hideExtension.redirect` | `Number` | `301` | HTTP redirect code |
+| `hidden.dotFiles.default` | `String` | `'visible'` | Default visibility for `.foo` files (`'hidden'` to harden) |
+| `hidden.dotFiles.whitelist` | `Array` | `[]` | Names always visible (string/glob/RegExp) |
+| `hidden.dotFiles.blacklist` | `Array` | `[]` | Names always hidden (overrides whitelist) |
+| `hidden.dotDirs.default` | `String` | `'visible'` | Default visibility for `.foo` directories |
+| `hidden.dotDirs.whitelist` | `Array` | `[]` | Names always visible |
+| `hidden.dotDirs.blacklist` | `Array` | `[]` | Names always hidden |
+| `hidden.alwaysHide` | `Array` | `[]` | Path-aware patterns (string glob or RegExp) |
+| `browserCacheEnabled` | `Boolean` | `false` | Emit ETag + Last-Modified (recommended `true` in production) |
+| `browserCacheMaxAge` | `Number` | `3600` | `Cache-Control: max-age` in seconds |
+| `template.render` | `Function` | – | `async (ctx, next, filePath, { signal }) => void` |
+| `template.ext` | `String[]` | `[]` | Extensions handled by the template engine |
+| `template.renderTimeout` | `Number` | `30000` | **V3** Max render time in ms (0 = disabled) |
+| `logger` | `Object` | `console` | **V3** Logger with `{ error, warn, info, debug }` |
+
+For deep dives, see [DOCUMENTATION.md](./docs/DOCUMENTATION.md) and the per-option guides in [`docs/`](./docs).
 
-```javascript
-const Koa = require('koa');
-const koaClassicServer = require('koa-classic-server');
-
-const app = new Koa();
+---
 
-// i18n middleware that rewrites URLs
-app.use(async (ctx, next) => {
-  if (ctx.path.match(/^\/it\//)) {
-    ctx.url = ctx.path.replace(/^\/it/, ''); // /it/page.html → /page.html
-  }
-  await next();
-});
+## Directory Listing Features
 
-// Serve files using rewritten URL
-app.use(koaClassicServer(__dirname + '/www', {
-  useOriginalUrl: false  // Use ctx.url (rewritten) instead of ctx.originalUrl
-}));
+### Sortable Columns
 
-app.listen(3000);
-```
+Click any column header to sort:
+- **Name** — Alphabetical (A→Z / Z→A)
+- **Type** — By MIME type (directories first)
+- **Size** — By byte size (directories first)
 
-**How it works:**
-- Request: `GET /it/page.html`
-- `ctx.originalUrl`: `/it/page.html` (unchanged)
-- `ctx.url`: `/page.html` (rewritten by middleware)
-- With `useOriginalUrl: false`: Server looks for `/www/page.html` ✅
-- With `useOriginalUrl: true` (default): Server looks for `/www/it/page.html` ❌ 404
+Visual indicators: `↑` ascending, `↓` descending. Sort + order are preserved across pagination links.
 
----
+### Pagination (V3)
 
-## Directory Listing Features
+When the number of visible entries exceeds `dirListing.entriesPerPage`, a numbered paginator is rendered below the table:
 
-### Sortable Columns
+```
+« First · ‹ Prev · 0 · 1 · … · 7 · 8 · 9 · Next › · Last »
+```
 
-Click on column headers to sort:
+- Page index is 0-based (`?page=N`).
+- Invalid or out-of-range values clamp silently.
+- Response header `X-Dir-Pagination: <current>/<last>` is emitted only when pagination is meaningful.
 
-- **Name** - Alphabetical sorting (A-Z or Z-A)
-- **Type** - Sort by MIME type (directories always first)
-- **Size** - Sort by file size (directories always first)
+### Truncation Banner (V3)
 
-Visual indicators:
-- **↑** - Ascending order
-- **↓** - Descending order
+When `dirListing.maxEntries` is hit, a banner is rendered above the table and `X-Dir-Truncated: <N>` is set, so capped listings are visible both to users and to monitoring.
 
 ### File Size Display
 
-Human-readable format:
-- `1.5 KB` - Kilobytes
-- `2.3 MB` - Megabytes
-- `1.2 GB` - Gigabytes
-- `-` - Directories (no size)
+Human-readable: `1.5 KB`, `2.3 MB`, `1.2 GB`. Directories show `-`.
 
 ### Navigation
 
-- **Click folder name** - Enter directory
-- **Click file name** - Download/view file
-- **Parent Directory** - Go up one level
+- Click folder → enter directory
+- Click file → serve / download
+- **Parent Directory** link → go up one level
 
 ### Symlink Support
 
-The middleware fully supports symbolic links, which is essential for environments where served files are symlinks rather than regular files:
+The middleware follows symbolic links transparently via `fs.promises.stat()` — useful in NixOS, Docker bind mounts, `npm link`, and Capistrano-style deploys.
 
-- **NixOS buildFHSEnv** - Files in www/ appear as symlinks to the Nix store
-- **Docker bind mounts** - Mounted files may appear as symlinks
-- **npm link** - Linked packages are symlinks
-- **Capistrano-style deploys** - The `current` directory is a symlink to the active release
+| Entry type | Indicator | Clickable | Type column |
+|---|---|---|---|
+| Symlink to file | `( Symlink )` | yes | target MIME |
+| Symlink to directory | `( Symlink )` | yes | `DIR` |
+| Broken symlink | `( Broken Symlink )` | no | original MIME guess |
 
-**How it works:**
+Regular files incur zero additional `stat()` overhead.
 
-Symlinks are followed transparently via `fs.promises.stat()`, but only when `dirent.isSymbolicLink()` is true. Regular files incur zero additional overhead.
+---
 
-**Directory listing indicators:**
+## Security
 
-| Entry type | Indicator | Clickable | Type shown |
-|------------|-----------|-----------|------------|
-| Symlink to file | `( Symlink )` | Yes | Target MIME type |
-| Symlink to directory | `( Symlink )` | Yes | `DIR` |
-| Broken/circular symlink | `( Broken Symlink )` | No | `unknown` |
-| Regular file/directory | none | Yes | Real type |
+### Built-in Protection
 
-**Edge cases handled:**
-- Broken symlinks (missing target) return 404 on direct access
-- Circular symlinks (A → B → A) are treated as broken, no infinite loops
-- Symlinks to directories are fully navigable
+#### 1. Path Traversal
 
----
+```text
+GET /../../etc/passwd            → 403 Forbidden
+GET /%2e%2e%2fpackage.json       → 403 Forbidden
+GET /file\0.txt                  → 400 Bad Request   (null-byte guard)
+```
 
-## Security
+Defense in depth: null-byte rejection → `path.normalize()` → resolved-path boundary check against `rootDir`.
 
-### Built-in Protection
+#### 2. XSS in Directory Listing
 
-koa-classic-server includes enterprise-grade security:
+All file and directory names are HTML-escaped. CSS is inlined under a hash-based `Content-Security-Policy` recomputed at module load — script execution from inline `<style>`/`<script>` is rejected by the browser.
 
-#### 1. Path Traversal Protection
+#### 3. Dot-Files Hidden by Default (V3)
 
-Prevents access to files outside `rootDir`:
+`.env`, `.git/config`, SSH keys, etc. return 404 unless explicitly whitelisted via `hidden.dotFiles.whitelist`. The `.well-known` whitelist pattern stays friendly to ACME / Let's Encrypt.
 
-```javascript
-// ❌ Blocked requests
-GET /../../../etc/passwd       → 403 Forbidden
-GET /../config/database.yml    → 403 Forbidden
-GET /%2e%2e%2fpackage.json     → 403 Forbidden
-```
+#### 4. Security Headers on Generated Pages
 
-#### 2. XSS Protection
+The middleware emits the following on directory listings and error pages (404/405/500/etc.):
 
-All filenames and paths are HTML-escaped:
+| Header | Value |
+|---|---|
+| `Content-Security-Policy` | hash-based on listing, fully restrictive on errors |
+| `X-Content-Type-Options` | `nosniff` |
+| `X-Frame-Options` | `DENY` |
+| `Referrer-Policy` | `no-referrer` |
+| `Permissions-Policy` | `camera=(), microphone=(), geolocation=(), payment=()` |
 
-```javascript
-// Malicious filename: <script>alert('xss')</script>.txt
-// Displayed as: &lt;script&gt;alert('xss')&lt;/script&gt;.txt
-// ✅ Safe - script doesn't execute
-```
+> ⚠️ User-served static files (HTML/JS/CSS on disk) are returned **without** these headers — by design. See [docs/DOCUMENTATION.md → Limiti dei Security Headers](./docs/DOCUMENTATION.md#limiti-dei-security-headers-sui-file-statici) for an upstream-middleware example that applies your own CSP/HSTS to static files.
+
+#### 5. DNS Rebinding
 
-#### 3. Reserved URLs
+The middleware does not validate the `Host` header — that belongs to the reverse proxy or an application-level allowlist. See [docs/DOCUMENTATION.md → DNS Rebinding](./docs/DOCUMENTATION.md#dns-rebinding--valida-lheader-host-a-monte) for nginx + Koa allowlist examples.
 
-Protect sensitive directories:
+#### 6. Reserved URLs
 
 ```javascript
 app.use(koaClassicServer(__dirname, {
-  urlsReserved: ['/admin', '/config', '/.git', '/node_modules']
+  urlsReserved: ['/admin', '/api', '/.git', '/node_modules'],
 }));
 ```
 
-#### 4. Race Condition Protection
+#### 7. Race-Condition Protection
+
+File metadata is verified before streaming. A file deleted between check and access returns `404`, never a crash or partial response.
+
+#### 8. Bounded Listings (V3)
 
-File access is verified before streaming:
+`dirListing.maxEntries` caps the number of entries that are sorted, stat'd, and rendered per listing — bounds CPU and HTML size against accidentally-large folders. The initial `readdir()` is not bounded by this option; an opt-in streaming mode for adversarial-directory workloads is planned for v3.1.
+
+#### 9. Template Render Timeout (V3)
+
+`template.renderTimeout` (default 30 s) prevents a hung or runaway template render from blocking the request indefinitely; the AbortSignal forwarded to the renderer lets you abort downstream I/O cleanly.
+
+**See:**
+- [Security improvement roadmap →](./docs/security_improvement_for_V3.md)
+- [Security tests →](./__tests__/security.test.js)
+
+### Design philosophy & Security Checklist
+
+koa-classic-server follows the principle: **"if a file is in `rootDir`, `GET` on its path returns it"**. The defaults serve files without applying surprise restrictions — the operator is the source of truth. See [`CLAUDE.md`](./CLAUDE.md) for the full design philosophy.
+
+This means hardening is **opt-in via explicit configuration**. The checklist below covers the most common production concerns. Each item is one or two lines of configuration; not all of them apply to every deployment.
+
+#### ✅ Static site / public asset serving
+
+- [ ] **Hide dot-files** that may contain secrets:
+  `hidden: { dotFiles: { default: 'hidden', whitelist: ['.well-known'] } }`
+- [ ] **Block dot-directories** like `.git`:
+  `hidden: { dotDirs: { default: 'hidden', whitelist: ['.well-known'] } }`
+- [ ] **Disable directory listing** in production:
+  `dirListing: { enabled: false }` (combine with an `index` file)
+- [ ] **Enable browser HTTP caching**:
+  `browserCacheEnabled: true, browserCacheMaxAge: 86400`
+- [ ] **Restrict methods** to read-only (default already `['GET']`):
+  `method: ['GET', 'HEAD']`
+- [ ] **Reserve sensitive paths** for app routes:
+  `urlsReserved: ['/api', '/admin']`
+- [ ] **Add upstream security headers** for user-served HTML (not auto-added by this middleware — see *DNS Rebinding / Headers* in `docs/DOCUMENTATION.md`).
+
+#### ✅ User uploads, multi-tenant, untrusted-write directories
+
+- [ ] **Lower the entry cap** for accidentally-large dirs:
+  `dirListing: { maxEntries: 1000 }` (default 100000 is a safety net, not a security feature)
+- [ ] **Hide dot-files at every depth**:
+  `hidden: { dotFiles: { default: 'hidden' }, dotDirs: { default: 'hidden' } }`
+- [ ] **Add path-aware blocklists** for known secret patterns:
+  `hidden: { alwaysHide: ['*.key', '*.pem', /\.secret$/, 'config/secrets/**'] }`
+- [ ] **Monitor directory growth externally** (cron + alert) — the v3.0 cap bounds rendering CPU but not the initial `readdir()` allocation. See `[F-1]` in `docs/security_improvement_for_V3.md` for the v3.1 streaming-read opt-in tracking this gap.
+
+#### ✅ Production hygiene (any deployment)
+
+- [ ] **Validate `Host` header upstream** (nginx `server_name` allowlist or app-level middleware) — this middleware does NOT validate `Host`. See *DNS Rebinding* in `docs/DOCUMENTATION.md`.
+- [ ] **Disable template-engine in production** if you don't use SSR — minimizes attack surface:
+  omit the `template` option entirely
+- [ ] **Tune `template.renderTimeout`** if you do use SSR — default 30 s is conservative; tighten for tight-SLA services
+- [ ] **Inject a real logger** instead of `console`:
+  `logger: pino()` so security-relevant warnings reach your aggregation
+- [ ] **Pin the latest patch version** in `package.json` and run `npm audit` in CI
+
+### Suggested production security configuration
+
+A single configuration block that covers most production deployments. Start here and tune for your workload (static site vs uploads vs internal admin):
 
 ```javascript
-// File deleted between check and access?
-// ✅ Returns 404 instead of crashing
+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) Validate Host header — mitigates DNS rebinding on LAN / loopback exposure.
+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) Apply security headers to user-served HTML/JS/CSS. The middleware
+//    sets these only on its own generated pages (listing + errors).
+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) The file server with hardened defaults.
+app.use(koaClassicServer(path.join(__dirname, 'public'), {
+  method: ['GET', 'HEAD'],            // read-only
+
+  index: ['index.html'],              // serve index when present
+
+  dirListing: {
+    enabled: process.env.NODE_ENV !== 'production',
+    maxEntries: 10000,                // tighten the soft cap below the 100k default
+    entriesPerPage: 100,
+  },
+
+  hidden: {
+    dotFiles: {
+      default: 'hidden',              // hide .env / .htaccess / etc by default
+      whitelist: ['.well-known'],     // expose ACME / Let's Encrypt
+    },
+    dotDirs: {
+      default: 'hidden',
+      whitelist: ['.well-known'],
+    },
+    alwaysHide: ['*.key', '*.pem', /^backup-/, /\.secret$/],
+  },
+
+  browserCacheEnabled: true,
+  browserCacheMaxAge:  86400,         // 24 h — bandwidth savings on cache hits
+
+  logger: pino,                       // pipe internal warnings to structured logs
+
+  urlsReserved: ['/api', '/admin'],   // routes handled by other middleware
+}));
+
+app.listen(3000);
 ```
 
-**See full security audit:** [Security Tests →](./__tests__/security.test.js)
+For multi-tenant or user-upload scenarios, also drop `dirListing.maxEntries` to `1000` and monitor the served directory's size externally.
 
 ---
 
@@ -733,32 +677,21 @@ File access is verified before streaming:
 
 ### Optimizations
 
-Version 2.x includes major performance improvements:
-
-- **Async/Await** - Non-blocking I/O, event loop never blocked
-- **Array Join** - 30-40% less memory vs string concatenation
-- **HTTP Caching** - 80-95% bandwidth reduction
-- **Single stat() Call** - No double file system access
-- **Streaming** - Large files streamed efficiently
+- **Single-syscall `readdir()`** — directory entries fetched in one batched syscall, then sliced to `dirListing.maxEntries` to cap rendering work
+- **Single `stat()`** per item — no double filesystem traversal
+- **Array `.join()`** for listing HTML — significantly less GC pressure than `+=`
+- **HTTP conditional responses** — 304s with `If-None-Match` / `If-Modified-Since` (when caching enabled)
+- **File streaming** — large files streamed via `fs.createReadStream`, never buffered in full
+- **Pre-computed CSP hash** — SHA-256 of inline CSS hashed once at module load, not per request
 
 ### Benchmarks
 
-Performance results on directory with 1,000 files:
-
-```
-Before (v1.x):     ~350ms per request
-After (v2.x):      ~190ms per request
-Improvement:       46% faster
-```
-
-**See detailed benchmarks:** [Performance Analysis →](./docs/PERFORMANCE_ANALYSIS.md)
+See [`docs/BENCHMARKS.md`](./docs/BENCHMARKS.md) and [`docs/PERFORMANCE_COMPARISON.md`](./docs/PERFORMANCE_COMPARISON.md) for full benchmarks and methodology.
 
 ---
 
 ## Testing
 
-Run the comprehensive test suite:
-
 ```bash
 # Run all tests
 npm test
@@ -770,106 +703,127 @@ npm run test:security
 npm run test:performance
 ```
 
-**Test Coverage:**
-- ✅ 309 tests passing
-- ✅ Security tests (path traversal, XSS, race conditions)
-- ✅ EJS template integration tests
-- ✅ Index option tests (strings, arrays, RegExp)
-- ✅ hideExtension tests (clean URLs, redirects, conflicts, validation)
-- ✅ Symlink tests (file, directory, broken, circular, indicators)
+**Coverage:**
+- ✅ 532 tests passing across 20 suites
+- ✅ Security (path traversal, XSS, race conditions, CSP, hidden-files)
+- ✅ Directory listing (sorting, pagination, truncation cap, symlinks)
+- ✅ Template engine (timeout, abort signal, error propagation, EJS integration)
+- ✅ Logger injection (validation, custom logger, console default)
+- ✅ Index option (arrays, RegExp, priority)
+- ✅ `hideExtension` (clean URLs, redirects, conflicts, validation)
+- ✅ HTTP caching (ETag, Last-Modified, 304)
 - ✅ Performance benchmarks
-- ✅ Directory sorting tests
 
 ---
 
 ## Complete Documentation
 
-### Core Documentation
-
-- **[DOCUMENTATION.md](./docs/DOCUMENTATION.md)** - Complete API reference and usage guide
-- **[FLOW_DIAGRAM.md](./docs/FLOW_DIAGRAM.md)** - Visual flow diagrams and code execution paths
-- **[CHANGELOG.md](./docs/CHANGELOG.md)** - Version history and release notes
+### Core
+- **[DOCUMENTATION.md](./docs/DOCUMENTATION.md)** — Full API reference and usage guide
+- **[FLOW_DIAGRAM.md](./docs/FLOW_DIAGRAM.md)** — Visual flow diagrams and execution paths
+- **[CHANGELOG.md](./docs/CHANGELOG.md)** — Version history and release notes
 
 ### Template Engine
-
-- **[TEMPLATE_ENGINE_GUIDE.md](./docs/template-engine/TEMPLATE_ENGINE_GUIDE.md)** - Complete guide to template engine integration
-  - Progressive examples (simple to enterprise)
-  - EJS, Pug, Handlebars, Nunjucks support
-  - Best practices and troubleshooting
+- **[TEMPLATE_ENGINE_GUIDE.md](./docs/template-engine/TEMPLATE_ENGINE_GUIDE.md)** — EJS, Pug, Handlebars, Nunjucks; AbortSignal + timeout patterns
 
 ### Configuration
+- **[INDEX_OPTION_PRIORITY.md](./docs/INDEX_OPTION_PRIORITY.md)** — Priority rules for `index`
+- **[EXAMPLES_INDEX_OPTION.md](./docs/EXAMPLES_INDEX_OPTION.md)** — 10 practical examples
 
-- **[INDEX_OPTION_PRIORITY.md](./docs/INDEX_OPTION_PRIORITY.md)** - Detailed priority behavior for `index` option
-  - String vs Array vs RegExp formats
-  - Priority order examples
-  - Migration guide from v1.x
-
-- **[EXAMPLES_INDEX_OPTION.md](./docs/EXAMPLES_INDEX_OPTION.md)** - 10 practical examples of `index` option with RegExp
-  - Case-insensitive matching
-  - Multiple extensions
-  - Complex patterns
+### Security
+- **[security_improvement_for_V3.md](./docs/security_improvement_for_V3.md)** — Audit roadmap and status
 
 ### Performance
+- **[PERFORMANCE_ANALYSIS.md](./docs/PERFORMANCE_ANALYSIS.md)** — Optimization analysis
+- **[PERFORMANCE_COMPARISON.md](./docs/PERFORMANCE_COMPARISON.md)** — Latency, throughput, concurrency
+- **[OPTIMIZATION_HTTP_CACHING.md](./docs/OPTIMIZATION_HTTP_CACHING.md)** — Caching internals
+- **[BENCHMARKS.md](./docs/BENCHMARKS.md)** — Methodology and results
 
-- **[PERFORMANCE_ANALYSIS.md](./docs/PERFORMANCE_ANALYSIS.md)** - Performance optimization analysis
-  - Before/after comparisons
-  - Memory usage analysis
-  - Bottleneck identification
-
-- **[PERFORMANCE_COMPARISON.md](./docs/PERFORMANCE_COMPARISON.md)** - Detailed performance benchmarks
-  - Request latency
-  - Throughput metrics
-  - Concurrent request handling
+### Code Quality
+- **[CODE_REVIEW.md](./docs/CODE_REVIEW.md)** — Code review and standards
+- **[DEBUG_REPORT.md](./docs/DEBUG_REPORT.md)** — Known limitations and debugging
 
-- **[OPTIMIZATION_HTTP_CACHING.md](./docs/OPTIMIZATION_HTTP_CACHING.md)** - HTTP caching implementation details
-  - ETag generation
-  - Last-Modified headers
-  - 304 Not Modified responses
+---
 
-- **[BENCHMARKS.md](./docs/BENCHMARKS.md)** - Benchmark results and methodology
+## Migration Guide
 
-### Code Quality
+### From v2.x to v3.x
 
-- **[CODE_REVIEW.md](./docs/CODE_REVIEW.md)** - Code quality analysis and review
-  - Security audit
-  - Best practices
-  - Standardization improvements
+**Breaking changes**
 
-- **[DEBUG_REPORT.md](./docs/DEBUG_REPORT.md)** - Known limitations and debugging info
-  - Reserved URLs behavior
-  - Edge cases
-  - Troubleshooting tips
+| What | v2.x | v3.x |
+|---|---|---|
+| `index: 'index.html'` | accepted | **throws** — must be an array |
+| `cacheMaxAge` | accepted | **removed** — use `browserCacheMaxAge` |
+| `enableCaching` | accepted | **removed** — use `browserCacheEnabled` |
+| `showDirContents` | accepted | accepted as **deprecated alias** — emits a one-time warning, prefer `dirListing: { enabled: true }` |
+| Dot-files | served | **served** (unchanged — opt into hiding via `hidden.dotFiles.default: 'hidden'`; see Security Checklist) |
+| Logger | `console` only | `logger` option injects any logger; default still `console` |
+| Template `render` signature | `(ctx, next, filePath)` | `(ctx, next, filePath, { signal })` — old signature still works, `signal` is opt-in |
 
----
+**Quick migration**
 
-## Migration Guide
-
-### From v1.x to v2.x
+```javascript
+// v2.x
+app.use(koaClassicServer(root, {
+  index:           'index.html',
+  enableCaching:   true,
+  cacheMaxAge:     3600,
+  showDirContents: true,
+}));
 
-**Breaking Changes:**
-- `index` option: String format deprecated (still works), use array format
+// v3.x
+app.use(koaClassicServer(root, {
+  index:               ['index.html'],
+  browserCacheEnabled: true,
+  browserCacheMaxAge:  3600,
+  dirListing:          { enabled: true },
+}));
+```
 
-**Migration:**
+**Dot-files in v3**
 
 ```javascript
-// v1.x (deprecated)
+// To restore v2.x behavior (serve dot-files):
+{ hidden: { dotFiles: { default: 'visible' } } }
+
+// Recommended v3 — hide dot-files but expose .well-known for ACME / Let's Encrypt:
 {
-  index: 'index.html'
+  hidden: {
+    dotFiles: { default: 'hidden', whitelist: ['.well-known'] },
+    dotDirs:  { default: 'hidden', whitelist: ['.well-known'] },
+  },
 }
+```
 
-// v2.x (recommended)
-{
-  index: ['index.html']
+**Template render in v3**
+
+```javascript
+// v2.x — still works:
+template: { render: async (ctx, next, filePath) => { /* ... */ } }
+
+// v3.x — opt into the AbortSignal:
+template: {
+  renderTimeout: 5000,
+  render: async (ctx, next, filePath, { signal }) => {
+    const data = await fetchData({ signal });
+    ctx.body  = await ejs.renderFile(filePath, data, { signal });
+    ctx.type  = 'text/html';
+  },
 }
 ```
 
-**New Features:**
-- HTTP caching (enabled by default)
-- Sortable directory columns
-- File size display
-- Enhanced index option with RegExp
+### From v1.x to v2.x
+
+```javascript
+// v1.x
+{ index: 'index.html' }
+
+// v2.x+
+{ index: ['index.html'] }
+```
 
-**See full migration guide:** [CHANGELOG.md](./docs/CHANGELOG.md)
+See the full [CHANGELOG.md](./docs/CHANGELOG.md) for every change.
 
 ---
 
@@ -894,22 +848,26 @@ const koaClassicServer = require('koa-classic-server');
 
 const app = new Koa();
 
-// Serve static assets
+// Static assets — no listing in production
 app.use(koaClassicServer(__dirname + '/public', {
   urlPrefix: '/static',
-  showDirContents: false
+  dirListing: { enabled: false },
 }));
 
-// Serve user uploads
+// User uploads — paginated browsable index
 app.use(koaClassicServer(__dirname + '/uploads', {
   urlPrefix: '/files',
-  showDirContents: true
+  dirListing: {
+    enabled:        true,
+    maxEntries:     5000,
+    entriesPerPage: 50,
+  },
 }));
 
 app.listen(3000);
 ```
 
-### Example 3: Development Server with Templates
+### Example 3: Development Server with Templates + Timeout
 
 ```javascript
 const Koa = require('koa');
@@ -918,63 +876,77 @@ const ejs = require('ejs');
 
 const app = new Koa();
 
-// Development mode - show directories
 app.use(koaClassicServer(__dirname + '/src', {
-  showDirContents: true,
+  dirListing: { enabled: true },
   template: {
     ext: ['ejs'],
-    render: async (ctx, next, filePath) => {
+    renderTimeout: 3000,
+    render: async (ctx, next, filePath, { signal }) => {
       ctx.body = await ejs.renderFile(filePath, {
         dev: true,
-        timestamp: Date.now()
-      });
+        timestamp: Date.now(),
+      }, { signal });
       ctx.type = 'text/html';
-    }
-  }
+    },
+  },
 }));
 
 app.listen(3000);
 ```
 
----
+### Example 4: Production with Pino Logger + Caching
 
-## Troubleshooting
+```javascript
+const Koa = require('koa');
+const pino = require('pino')({ level: 'info' });
+const koaClassicServer = require('koa-classic-server');
 
-### Common Issues
+const app = new Koa();
 
-**Issue: 404 errors for all files**
+app.use(koaClassicServer(__dirname + '/public', {
+  index:               ['index.html'],
+  dirListing:          { enabled: false },
+  browserCacheEnabled: true,
+  browserCacheMaxAge:  86400,
+  logger:              pino,
+}));
 
-Check that `rootDir` is an absolute path:
+app.listen(3000);
+```
 
-```javascript
-// ❌ Wrong (relative path)
-koaClassicServer('./public')
+---
 
-// ✅ Correct (absolute path)
-koaClassicServer(__dirname + '/public')
-koaClassicServer(path.join(__dirname, 'public'))
-```
+## Troubleshooting
 
-**Issue: Reserved URLs not working**
+**404 for all files**
 
-Reserved URLs only work for first-level directories:
+Use an absolute path for `rootDir`:
 
 ```javascript
-urlsReserved: ['/admin']  // ✅ Blocks /admin/*
-urlsReserved: ['/admin/users']  // ❌ Doesn't work (nested)
+koaClassicServer('./public')                   // ❌ relative
+koaClassicServer(__dirname + '/public')        // ✅ absolute
+koaClassicServer(path.join(__dirname, 'pub'))  // ✅ absolute
 ```
 
-**Issue: Directory sorting not working**
+**Reserved URLs not matching nested paths**
+
+`urlsReserved` only matches first-level path segments — use it for top-level routes (`/api`), not nested ones (`/api/users`).
+
+**Directory listing shows fewer files than expected**
+
+Check the response headers: `X-Dir-Truncated` indicates the `dirListing.maxEntries` cap was reached. Increase the cap or paginate via `?page=N`.
+
+**Templates time out under load**
 
-Make sure you're accessing directories without query params initially. The sorting is applied when you click headers.
+Lower `template.renderTimeout` to fail fast, forward the `signal` to your I/O, and check the logger output for `Template render timeout after Xms` warnings.
 
-**See full troubleshooting:** [DEBUG_REPORT.md](./docs/DEBUG_REPORT.md)
+See full troubleshooting: [DEBUG_REPORT.md](./docs/DEBUG_REPORT.md).
 
 ---
 
 ## Contributing
 
-Contributions are welcome! Please:
+Contributions are welcome:
 
 1. Fork the repository
 2. Create a feature branch
@@ -986,8 +958,9 @@ Contributions are welcome! Please:
 
 ## Known Limitations
 
-- Reserved URLs only work for first-level directories
-- Template rendering is synchronous per request
+- `urlsReserved` only matches first-level path segments
+- The middleware does not validate the `Host` header — configure a reverse proxy or an upstream allowlist (see [DOCUMENTATION.md → DNS Rebinding](./docs/DOCUMENTATION.md#dns-rebinding--valida-lheader-host-a-monte))
+- Static files are returned without security headers — apply your own upstream middleware (see [DOCUMENTATION.md → Limiti dei Security Headers](./docs/DOCUMENTATION.md#limiti-dei-security-headers-sui-file-statici))
 
 See [DEBUG_REPORT.md](./docs/DEBUG_REPORT.md) for technical details.
 
@@ -995,7 +968,7 @@ See [DEBUG_REPORT.md](./docs/DEBUG_REPORT.md) for technical details.
 
 ## License
 
-MIT License - see LICENSE file for details
+MIT License — see LICENSE file for details.
 
 ---
 
@@ -1007,10 +980,10 @@ Italo Paesano
 
 ## Links
 
-- **[npm Package](https://www.npmjs.com/package/koa-classic-server)** - Official npm package
-- **[GitHub Repository](https://github.com/italopaesano/koa-classic-server)** - Source code
-- **[Issue Tracker](https://github.com/italopaesano/koa-classic-server/issues)** - Report bugs
-- **[Full Documentation](./docs/DOCUMENTATION.md)** - Complete reference
+- **[npm Package](https://www.npmjs.com/package/koa-classic-server)** — Official npm package
+- **[GitHub Repository](https://github.com/italopaesano/koa-classic-server)** — Source code
+- **[Issue Tracker](https://github.com/italopaesano/koa-classic-server/issues)** — Report bugs
+- **[Full Documentation](./docs/DOCUMENTATION.md)** — Complete reference
 
 ---