koa-classic-server 3.0.0 → 3.1.0

package/README.md

@@ -17,7 +17,7 @@ The 3.0 series builds on 2.x with new observability hooks, bounded resource usag
 
 ✅ **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.
+✅ **Soft cap on listing rendering** — `dirListing.maxEntries` defaults to `10000` 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
@@ -224,7 +224,7 @@ app.use(koaClassicServer(__dirname + '/public', {
 
 ### 8. Hidden Files & Dot-File Protection (V3 default: hidden)
 
-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).
+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'`. See the [Security Hardening Guide → Dot-files and dot-directories](./docs/SECURITY_HARDENING.md#31-dot-files-and-dot-directories-env-git-keys).
 
 ```javascript
 app.use(koaClassicServer(__dirname + '/www', {
@@ -305,10 +305,12 @@ const koaClassicServer = require('koa-classic-server');
 
 const app = new Koa();
 
-// Allowlist Host headers to mitigate DNS rebinding (see docs/DOCUMENTATION.md → Sicurezza).
+// Allowlist Host headers to mitigate DNS rebinding (see docs/DOCUMENTATION.md → DNS Rebinding).
+// Uses raw ctx.get('host') (not ctx.host) to avoid trusting a forgeable X-Forwarded-Host.
 const ALLOWED_HOSTS = new Set(['app.example.com', 'localhost:3000']);
+const normalizeHost = (h) => (h || '').toLowerCase().replace(/\.$/, '');
 app.use(async (ctx, next) => {
-  if (!ALLOWED_HOSTS.has(ctx.host)) { ctx.status = 421; ctx.body = 'Host not allowed'; return; }
+  if (!ALLOWED_HOSTS.has(normalizeHost(ctx.get('host')))) { ctx.status = 421; ctx.body = 'Host not allowed'; return; }
   await next();
 });
 
@@ -488,9 +490,30 @@ The middleware follows symbolic links transparently via `fs.promises.stat()` —
 | Symlink to file | `( Symlink )` | yes | target MIME |
 | Symlink to directory | `( Symlink )` | yes | `DIR` |
 | Broken symlink | `( Broken Symlink )` | no | original MIME guess |
+| Policy-blocked symlink | `( Blocked Symlink )` | no | MIME guess, size hidden |
 
 Regular files incur zero additional `stat()` overhead.
 
+#### `symlinks` policy (V3.1+) — protect against symlink escape
+
+By default (`symlinks: 'follow'`) a symlink inside `rootDir` is followed **even when its target lives outside `rootDir`** — consistent with the *"file server first"* philosophy (`rootDir` is the source of truth). If `rootDir` contains directories writable by untrusted parties (uploads, spool, multi-tenant hosting), a planted symlink could then read any file the process can access. Opt into containment:
+
+| Value | Behavior | Overhead |
+|---|---|---|
+| `'follow'` *(default)* | Follow symlinks anywhere, including outside `rootDir`. Historical behavior. | none |
+| `'follow-within-root'` | Follow only while the resolved realpath stays inside `rootDir`; escaping links → **404**. | one `realpath()` per served path |
+| `'deny'` | Never follow a symlink resolved **below** `rootDir`. | one `realpath()` per served path |
+
+```js
+app.use(koaClassicServer(rootDir, { symlinks: 'follow-within-root' }));
+```
+
+Notes:
+- **`rootDir` may itself be a symlink** (atomic-deploy / Capistrano / Nix) in every mode: the boundary is pinned to `realpath(rootDir)` resolved once at factory init.
+- Protected modes require `rootDir` to **exist at factory time** (they resolve its realpath up front) and throw otherwise.
+- In the directory listing, blocked symlinks appear as `( Blocked Symlink )`, non-clickable, and do not expose the target's size.
+- Residual risk: the check is realpath-based, so (a) a symlink swapped between the check and the file open (TOCTOU) is not fully prevented, and (b) **hardlinks** cannot be detected — a hardlink has no resolvable target path, so its `realpath` is inside `rootDir` even when it points to an external inode. For hostile multi-tenant setups combine with OS-level isolation (chroot, per-tenant mounts, `nosymfollow`, a dedicated upload filesystem).
+
 ---
 
 ## Security
@@ -500,12 +523,14 @@ Regular files incur zero additional `stat()` overhead.
 #### 1. Path Traversal
 
 ```text
-GET /../../etc/passwd            → 403 Forbidden
-GET /%2e%2e%2fpackage.json       → 403 Forbidden
+GET /../../etc/passwd            → 404 Not Found
+GET /%2e%2e%2fpackage.json       → 404 Not Found
 GET /file\0.txt                  → 400 Bad Request   (null-byte guard)
+GET /%                           → 400 Bad Request   (malformed percent-encoding)
+Host: bad host                   → 400 Bad Request   (invalid Host header)
 ```
 
-Defense in depth: null-byte rejection → `path.normalize()` → resolved-path boundary check against `rootDir`.
+Defense in depth: malformed-request rejection (bad percent-encoding / invalid `Host` → 400) → null-byte rejection → `path.normalize()` → resolved-path boundary check against `rootDir`. The boundary check is boundary-aware (`rootDir` exactly or `rootDir` + separator — never a sibling like `/srv/wwwsecret` for root `/srv/www`) and returns **404** so "outside root" is indistinguishable from "not found", matching symlink-escape and hidden entries. Malformed inputs return **400**, never an unhandled 500.
 
 #### 2. XSS in Directory Listing
 
@@ -527,11 +552,11 @@ The middleware emits the following on directory listings and error pages (404/40
 | `Referrer-Policy` | `no-referrer` |
 | `Permissions-Policy` | `camera=(), microphone=(), geolocation=(), payment=()` |
 
-> ⚠️ 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.
+> ⚠️ User-served static files (HTML/JS/CSS on disk) are returned **without** these headers — by design. Enable `staticSecurityHeaders: { nosniff: true }` and see the [Security Hardening Guide → Security headers on static files](./docs/SECURITY_HARDENING.md#35-security-headers-on-static-files) for applying your own CSP/HSTS via an upstream middleware.
 
 #### 5. DNS Rebinding
 
-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.
+The middleware does not validate the `Host` header — that belongs to the reverse proxy or an application-level allowlist. See the [Security Hardening Guide → Host validation / DNS rebinding](./docs/SECURITY_HARDENING.md#36-host-validation--dns-rebinding) for nginx + Koa allowlist examples.
 
 #### 6. Reserved URLs
 
@@ -557,119 +582,18 @@ File metadata is verified before streaming. A file deleted between check and acc
 - [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)
+### Hardening & production configuration
 
-- [ ] **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
+koa-classic-server follows the principle **"if a file is in `rootDir`, `GET` on its path returns it"** — defaults are transparent and the operator is the source of truth (see [`CLAUDE.md`](./CLAUDE.md)). Hardening is therefore **opt-in via explicit configuration**.
 
-### Suggested production security configuration
+The full, canonical hardening reference lives in one place to avoid drift:
 
-A single configuration block that covers most production deployments. Start here and tune for your workload (static site vs uploads vs internal admin):
-
-```javascript
-const Koa  = require('koa');
-const pino = require('pino')({ level: 'info' });
-const path = require('path');
-const koaClassicServer = require('koa-classic-server');
-
-const app = new Koa();
-
-// 1) 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);
-```
+📖 **[Security Hardening Guide → `docs/SECURITY_HARDENING.md`](./docs/SECURITY_HARDENING.md)**
 
-For multi-tenant or user-upload scenarios, also drop `dirListing.maxEntries` to `1000` and monitor the served directory's size externally.
+It covers a threat-model-based approach (trusted content / internal tool / user-uploads &
+multi-tenant), per-topic recommendations (dot-files, symlinks, listings & directory size,
+`nosniff`, `Host`/DNS rebinding, and more), per-profile checklists, residual risks, and a
+**copy-paste maximally-hardened configuration**.
 
 ---
 
@@ -959,8 +883,8 @@ Contributions are welcome:
 ## Known Limitations
 
 - `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))
+- The middleware does not validate the `Host` header — configure a reverse proxy or an upstream allowlist (see [Security Hardening Guide → Host validation / DNS rebinding](./docs/SECURITY_HARDENING.md#36-host-validation--dns-rebinding))
+- Static files are returned without security headers by default — enable `staticSecurityHeaders: { nosniff: true }` and/or apply upstream middleware (see [Security Hardening Guide → Security headers on static files](./docs/SECURITY_HARDENING.md#35-security-headers-on-static-files))
 
 See [DEBUG_REPORT.md](./docs/DEBUG_REPORT.md) for technical details.
 

package/index.cjs

@@ -158,6 +158,14 @@ function sendNotFound(ctx) {
     ctx.body = _NOT_FOUND_HTML;
 }
 
+// Plain-text 400 for malformed requests (bad percent-encoding, invalid Host,
+// null byte). Kept minimal and header-light to match the existing null-byte /
+// traversal guards — the response body carries no attacker-controlled data.
+function sendBadRequest(ctx) {
+    ctx.status = 400;
+    ctx.body = 'Bad Request';
+}
+
 // Validates and returns a logger compatible with our contract. The minimum
 // surface is `{ error: Function, warn: Function }` — any object exposing both
 // (console, pino, winston, bunyan, ...) is accepted as-is.
@@ -198,6 +206,28 @@ function sendTemplateError(ctx, status, html, logMsg, err, logger) {
     ctx.body = html;
 }
 
+// Rewrites an already-rendered response into an RFC 9110 §9.3.2 compliant HEAD
+// response: the status and headers produced by the render are preserved, the
+// body is replaced with an empty buffer (so no content is sent), and
+// Content-Length is restored to the byte length the GET body would have had.
+// Reassigning ctx.body to a non-stream value also makes Koa auto-destroy a
+// previous stream body, so no file descriptor leaks. Stream / non-buffer bodies
+// (uncommon for template renders) carry no Content-Length, matching the static
+// streaming-HEAD branch.
+function stripBodyForHead(ctx) {
+    if (ctx.headerSent) return;       // render already flushed — status/headers are locked
+    const body = ctx.body;
+    if (body == null) return;         // render produced no body (redirect, pass-through, ...) — leave status as-is
+    const hasKnownLength = typeof body === 'string' || Buffer.isBuffer(body);
+    const length = hasKnownLength ? Buffer.byteLength(body) : null;
+    ctx.body = Buffer.alloc(0);
+    if (length !== null) {
+        ctx.set('Content-Length', String(length)); // body setter zeroed it — restore the real length
+    } else {
+        ctx.remove('Content-Length');               // unknown length — omit, like static streaming HEAD
+    }
+}
+
 // Attempts to render the requested file through the user's template engine.
 // Returns true if the request was handled (success, timeout, or error response
 // already written), false if no template applies (caller should continue with
@@ -214,6 +244,16 @@ async function tryRenderTemplate(ctx, next, filePath, rawBuffer, templateOpts, l
     const fileExt = path.extname(filePath).slice(1);
     if (!fileExt || !templateOpts.ext.includes(fileExt)) return false;
 
+    // RFC 9110 §9.3.2: HEAD must mirror GET (same status + headers, no body). The
+    // user's render is run exactly as for GET — by presenting ctx.method as GET for
+    // the duration of the render — so it resolves, validates, and sets Content-Type
+    // / status identically; stripBodyForHead() then discards the body and restores
+    // Content-Length. Without this, a render that early-returns on non-GET never
+    // sets ctx.body, leaving ctx.status at Koa's default 404 for HEAD even though
+    // GET returns 200.
+    const isHeadRequest = ctx.method === 'HEAD';
+    if (isHeadRequest) ctx.method = 'GET';
+
     const controller = new AbortController();
     const onClientClose = () => controller.abort();
     ctx.req.on('close', onClientClose);
@@ -255,6 +295,10 @@ async function tryRenderTemplate(ctx, next, filePath, rawBuffer, templateOpts, l
     } finally {
         if (timer) clearTimeout(timer);
         ctx.req.removeListener('close', onClientClose);
+        if (isHeadRequest) {
+            ctx.method = 'HEAD';
+            stripBodyForHead(ctx);
+        }
     }
 
     return true;
@@ -487,10 +531,20 @@ module.exports = function koaClassicServer(
     opts STRUCTURE
      opts = {
         method: ['GET'], // Supported methods, otherwise next() will be called
+        symlinks: 'follow', // Symlink policy (V3.1+). Opt-in protection against symlink escape:
+                            //   'follow'             (default) — follow symlinks anywhere, incl.
+                            //                        targets OUTSIDE rootDir. Zero overhead;
+                            //                        historical behavior (no rootDir existence check).
+                            //   'follow-within-root' — follow only while the resolved realpath stays
+                            //                        inside rootDir; escaping links return 404.
+                            //   'deny'               — never follow a symlink resolved below rootDir
+                            //                        (rootDir being a symlink itself is always allowed).
+                            //   Protected modes cost one fs.realpath() per served path and require
+                            //   rootDir to exist at factory time. See README "Security Checklist".
         dirListing: {                   // Directory listing configuration (V3+).
             enabled:        true,       // Render the directory listing HTML when no index file matches.
                                         //   Set to false to return 404 instead of a listing.
-            maxEntries:     100000,     // Soft cap on entries shown / sorted / stat'd per listing.
+            maxEntries:     10000,      // Soft cap on entries shown / sorted / stat'd per listing.
                                         //   Implementation: fs.promises.readdir() then slice(0, maxEntries).
                                         //   This is a SAFETY NET against catastrophic operational accidents
                                         //   (broken log rotation, mistakenly mounted huge FS) — not a policy
@@ -577,6 +631,14 @@ module.exports = function koaClassicServer(
             mimeTypes: [],                // compressible MIME types (replaces default list if provided)
         },
         // compression: false            // shorthand to disable all compression
+        staticSecurityHeaders: {   // Opt-in security headers on STATIC file responses (V3.1+).
+            nosniff: false,        // false (default) — no change. true → sets
+                                   //   'X-Content-Type-Options: nosniff' on 200/206/304 static
+                                   //   responses, stopping MIME sniffing (content-sniffing XSS on
+                                   //   user-uploaded files). Does NOT apply to template-rendered
+                                   //   output. Off by default: hardening is opt-in. Other headers
+                                   //   (X-Frame-Options, HSTS, ...) stay with the reverse proxy.
+        },
         logger: console,    // Logger used for internal errors and warnings.
                             // Must expose error(...) and warn(...). Pass pino/winston/bunyan
                             // or any compatible object to integrate with aggregated logging.
@@ -1030,6 +1092,100 @@ module.exports = function koaClassicServer(
         return { rawFile, compressedFile };
     }
 
+    // ── symlinks policy (V3.1+) — opt-in protection against symlink escape ──
+    // 'follow'             (default) : follow symlinks anywhere, including targets
+    //                                  outside rootDir. Zero overhead — current behavior.
+    // 'follow-within-root'          : follow symlinks only while the resolved realpath
+    //                                  stays inside rootDir; escaping links return 404.
+    // 'deny'                        : never follow a symlink resolved BELOW rootDir
+    //                                  (rootDir itself being a symlink is always allowed).
+    // Protected modes cost one fs.realpath() per served path. See the Security Checklist.
+    if (options.symlinks === undefined) {
+        options.symlinks = 'follow';
+    } else if (
+        options.symlinks !== 'follow' &&
+        options.symlinks !== 'follow-within-root' &&
+        options.symlinks !== 'deny'
+    ) {
+        throw new Error(
+            '[koa-classic-server] options.symlinks must be one of "follow", "follow-within-root", "deny". ' +
+            'Got: ' + String(options.symlinks)
+        );
+    }
+    const _symlinkMode = options.symlinks;
+
+    // realpath of rootDir, resolved once at init (pinned). This is what makes a
+    // rootDir that is ITSELF a symlink work in protected modes: the boundary check
+    // compares against the real target, not the (unresolved) symlink path.
+    // In 'follow' mode we skip this entirely (and keep the historical behavior of
+    // NOT requiring rootDir to exist at factory time).
+    let realRootDir = normalizedRootDir;
+    if (_symlinkMode !== 'follow') {
+        try {
+            realRootDir = fs.realpathSync.native(normalizedRootDir);
+        } catch (err) {
+            throw new Error(
+                `[koa-classic-server] rootDir must exist when symlinks mode is "${_symlinkMode}". ` +
+                'Original error: ' + err.message
+            );
+        }
+    }
+
+    // Case-insensitive path comparison on filesystems that are case-insensitive by
+    // default (APFS/HFS+ on macOS, NTFS on Windows) — otherwise a casing mismatch
+    // between realRootDir and a resolved path would produce spurious 404s.
+    const _caseInsensitiveFS = process.platform === 'darwin' || process.platform === 'win32';
+
+    function _isWithinRoot(resolved, root) {
+        if (_caseInsensitiveFS) {
+            resolved = resolved.toLowerCase();
+            root = root.toLowerCase();
+        }
+        if (resolved === root) return true;
+        const withSep = root.endsWith(path.sep) ? root : root + path.sep;
+        return resolved.startsWith(withSep);
+    }
+
+    // Returns true if serving `resolvedPath` is permitted under the current symlinks
+    // policy. In 'follow' mode this is a no-op (no syscall). In protected modes it
+    // resolves the realpath and checks it against realRootDir.
+    async function symlinkAllowed(resolvedPath) {
+        if (_symlinkMode === 'follow') return true;
+        let real;
+        try {
+            real = await fs.promises.realpath(resolvedPath);
+        } catch {
+            return false; // cannot resolve (broken/circular link, race) → treat as not found
+        }
+        if (_symlinkMode === 'deny') {
+            // Reject if ANY symlink was resolved below rootDir: the real path must equal
+            // the path obtained by swapping only the rootDir prefix (no inner resolution).
+            const rel = path.relative(normalizedRootDir, resolvedPath);
+            const expected = path.join(realRootDir, rel);
+            return _caseInsensitiveFS
+                ? real.toLowerCase() === expected.toLowerCase()
+                : real === expected;
+        }
+        // 'follow-within-root': the resolved target must stay inside rootDir.
+        return _isWithinRoot(real, realRootDir);
+    }
+
+    // ── staticSecurityHeaders (V3.1+) — opt-in security headers on static responses ──
+    // Off by default (design philosophy: hardening is opt-in, documentation over defaults).
+    // Currently supports `nosniff` (X-Content-Type-Options: nosniff), which stops browsers
+    // from MIME-sniffing a response and interpreting it against the declared Content-Type
+    // (a content-sniffing XSS vector when serving user-uploaded files). Other headers
+    // (X-Frame-Options, Referrer-Policy, HSTS) remain the reverse proxy's responsibility.
+    const _ssh = options.staticSecurityHeaders;
+    if (_ssh !== undefined && (typeof _ssh !== 'object' || _ssh === null || Array.isArray(_ssh))) {
+        throw new Error(
+            '[koa-classic-server] options.staticSecurityHeaders must be an object, e.g. { nosniff: true }.'
+        );
+    }
+    const staticSecurityHeaders = {
+        nosniff: !!(_ssh && _ssh.nosniff),
+    };
+
     const compressionConfig = normalizeCompressionConfig(options.compression);
     const serverCacheConfig = normalizeServerCacheConfig(options.serverCache);
 
@@ -1152,11 +1308,18 @@ module.exports = function koaClassicServer(
         const urlToUse = options.useOriginalUrl ? ctx.originalUrl : ctx.url;
         const _origin  = ctx.protocol + '://' + ctx.host;
         const fullUrl  = _origin + urlToUse;
+        // Parse the request URL. `new URL()` throws on an invalid Host header
+        // (e.g. "Host: bad host") — reject as 400 rather than letting it surface as 500.
         let pageHref = '';
-        if (fullUrl.charAt(fullUrl.length - 1) === '/') {
-            pageHref = new URL(fullUrl.slice(0, -1));
-        } else {
-            pageHref = new URL(fullUrl);
+        try {
+            if (fullUrl.charAt(fullUrl.length - 1) === '/') {
+                pageHref = new URL(fullUrl.slice(0, -1));
+            } else {
+                pageHref = new URL(fullUrl);
+            }
+        } catch {
+            sendBadRequest(ctx);
+            return;
         }
 
         // Check URL prefix
@@ -1175,7 +1338,12 @@ module.exports = function koaClassicServer(
             let a_pathnameOutPrefix = a_pathname.slice(_urlPrefixParts.length);
             let s_pathnameOutPrefix = a_pathnameOutPrefix.join("/");
             let hrefOutPrefix = pageHref.origin + '/' + s_pathnameOutPrefix;
-            pageHrefOutPrefix = new URL(hrefOutPrefix);
+            try {
+                pageHrefOutPrefix = new URL(hrefOutPrefix);
+            } catch {
+                sendBadRequest(ctx);
+                return;
+            }
         }
 
         // Check reserved URLs (first level only)
@@ -1194,26 +1362,37 @@ module.exports = function koaClassicServer(
         if (pageHrefOutPrefix.pathname === "/") {
             requestedPath = "";
         } else {
-            requestedPath = decodeURIComponent(pageHrefOutPrefix.pathname);
+            // decodeURIComponent() throws URIError on malformed percent-encoding
+            // (e.g. "/%", "/%zz", a truncated UTF-8 sequence) — reject as 400
+            // rather than letting it surface as an unhandled 500.
+            try {
+                requestedPath = decodeURIComponent(pageHrefOutPrefix.pathname);
+            } catch {
+                sendBadRequest(ctx);
+                return;
+            }
         }
 
         // Null byte guard: path.normalize() throws ERR_INVALID_ARG_VALUE for paths
         // containing \0. Reject early with 400 Bad Request before it reaches fs calls.
         if (requestedPath.includes('\0')) {
-            ctx.status = 400;
-            ctx.body = 'Bad Request';
+            sendBadRequest(ctx);
             return;
         }
 
         const normalizedPath = path.normalize(requestedPath);
         const fullPath = path.join(normalizedRootDir, normalizedPath);
 
-        // Security check: ensure resolved path is within rootDir.
+        // Security check: ensure resolved path is within rootDir. Uses the shared
+        // _isWithinRoot() helper, which is boundary-aware: it matches rootDir exactly
+        // or rootDir + path.sep, never a sibling (e.g. /srv/wwwsecret for root /srv/www) —
+        // hardened defense in depth against a future change to how fullPath is built.
         // Covers: ../ traversal, URL-encoded variants (%2e%2e%2f), and on Windows
         // backslash sequences (path.normalize converts \ to / before the check).
-        if (!fullPath.startsWith(normalizedRootDir)) {
-            ctx.status = 403;
-            ctx.body = 'Forbidden';
+        // Returns 404 (not 403) so "outside root" is indistinguishable from "not found",
+        // matching the symlink-escape and hidden-entry outcomes.
+        if (!_isWithinRoot(fullPath, normalizedRootDir)) {
+            sendNotFound(ctx);
             return;
         }
 
@@ -1289,8 +1468,8 @@ module.exports = function koaClassicServer(
             if (!extOfRequested && requestedPath !== '' && !requestedPath.endsWith('/') && !hadTrailingSlash) {
                 const pathWithExt = fullPath + hideExt;
 
-                // Security check: ensure resolved path is still within rootDir
-                if (pathWithExt.startsWith(normalizedRootDir)) {
+                // Security check: ensure resolved path is still within rootDir (boundary-aware)
+                if (_isWithinRoot(pathWithExt, normalizedRootDir)) {
                     try {
                         const statWithExt = await fs.promises.stat(pathWithExt);
                         if (statWithExt.isFile()) {
@@ -1324,6 +1503,15 @@ module.exports = function koaClassicServer(
             }
         }
 
+        // Symlink boundary check (V-1): in protected modes reject any requested file
+        // or directory whose realpath escapes rootDir (or, in 'deny' mode, any symlink
+        // resolved below rootDir). The `_symlinkMode !== 'follow'` guard short-circuits
+        // before any await so the default 'follow' mode stays truly zero-overhead.
+        if (_symlinkMode !== 'follow' && !(await symlinkAllowed(toOpen))) {
+            sendNotFound(ctx);
+            return;
+        }
+
         if (stat.isDirectory()) {
             // Handle directory
             if (options.dirListing.enabled) {
@@ -1334,6 +1522,13 @@ module.exports = function koaClassicServer(
                         const indexRelPath = path.relative(normalizedRootDir, path.join(toOpen, indexFile.name)).split(path.sep).join('/');
                         if (!isHiddenEntry(indexFile.name, indexRelPath, false)) {
                             const indexPath = path.join(toOpen, indexFile.name);
+                            // Symlink boundary check (V-1): an index file may itself be a
+                            // symlink escaping rootDir — validate before serving it.
+                            // Guarded so the default 'follow' mode skips the await entirely.
+                            if (_symlinkMode !== 'follow' && !(await symlinkAllowed(indexPath))) {
+                                sendNotFound(ctx);
+                                return;
+                            }
                             await loadFile(indexPath, indexFile.stat);
                             return;
                         }
@@ -1406,6 +1601,15 @@ module.exports = function koaClassicServer(
             // Advertise range support on all file responses (including 304)
             ctx.set('Accept-Ranges', 'bytes');
 
+            // Opt-in static security headers (V-4). Applies to all static file
+            // responses (200 / 206 / 304). Placed after the template early-return,
+            // so template-rendered output is unaffected (that is the operator's
+            // responsibility inside their render function). Off by default — see
+            // the design philosophy: hardening is opt-in, not a default.
+            if (staticSecurityHeaders.nosniff) {
+                ctx.set('X-Content-Type-Options', 'nosniff');
+            }
+
             // Cache-Control set early — applies to all responses (200, 206, 304)
             if (options.browserCacheEnabled) {
                 ctx.set('Cache-Control', `public, max-age=${options.browserCacheMaxAge}, must-revalidate`);
@@ -1802,10 +2006,18 @@ module.exports = function koaClassicServer(
                             const itemRelPath = dirRelPath ? dirRelPath + '/' + s_name : s_name;
                             if (isHiddenEntry(s_name, itemRelPath, itemIsDir)) return null;
 
+                            // Symlink boundary (V-1): in protected modes, flag entries whose
+                            // target escapes rootDir (or, in 'deny' mode, any symlink). Blocked
+                            // entries are rendered non-clickable and do not expose the target size.
+                            let isBlockedSymlink = false;
+                            if (_symlinkMode !== 'follow' && !isBrokenSymlink && (type === 3 || type === 0)) {
+                                if (!(await symlinkAllowed(itemPath))) isBlockedSymlink = true;
+                            }
+
                             // Get file size — reuse cachedStat if already available (avoids double stat for symlinks)
                             let sizeStr = '-';
                             let sizeBytes = 0;
-                            if (!isBrokenSymlink) {
+                            if (!isBrokenSymlink && !isBlockedSymlink) {
                                 try {
                                     const itemStat = cachedStat || await fs.promises.stat(itemPath);
                                     if (effectiveType === 1) {
@@ -1826,6 +2038,7 @@ module.exports = function koaClassicServer(
                                 effectiveType,
                                 isSymlink: type === 3,
                                 isBrokenSymlink,
+                                isBlockedSymlink,
                                 mimeType,
                                 sizeStr,
                                 sizeBytes,
@@ -1887,14 +2100,16 @@ module.exports = function koaClassicServer(
                     // Symlink indicator label
                     const symlinkLabel = item.isBrokenSymlink
                         ? ' ( Broken Symlink )'
-                        : item.isSymlink
-                            ? ' ( Symlink )'
-                            : '';
+                        : item.isBlockedSymlink
+                            ? ' ( Blocked Symlink )'
+                            : item.isSymlink
+                                ? ' ( Symlink )'
+                                : '';
 
                     if (item.isReserved) {
                         parts.push(`${rowStart} ${escapeHtml(item.name)}${symlinkLabel}</td> <td> DIR BUT RESERVED</td><td>${item.sizeStr}</td></tr>`);
-                    } else if (item.isBrokenSymlink) {
-                        // Broken symlink: name visible but not clickable
+                    } else if (item.isBrokenSymlink || item.isBlockedSymlink) {
+                        // Broken or policy-blocked symlink: name visible but not clickable
                         parts.push(`${rowStart} ${escapeHtml(item.name)}${symlinkLabel}</td> <td> ${escapeHtml(item.mimeType)} </td><td>${item.sizeStr}</td></tr>`);
                     } else {
                         parts.push(`${rowStart} <a href="${escapeHtml(item.itemUri)}">${escapeHtml(item.name)}</a>${symlinkLabel} </td> <td> ${escapeHtml(item.mimeType)} </td><td>${item.sizeStr}</td></tr>`);