koa-classic-server 3.0.1 → 4.0.0

package/index.cjs

@@ -6,7 +6,7 @@ const crypto = require("crypto");
 const zlib = require("zlib");
 const util = require("util");
 const mime = require("mime-types");
-const { Readable } = require('stream');
+const { Readable, pipeline } = require('stream');
 
 const _brotliCompressAsync = util.promisify(zlib.brotliCompress);
 const _gzipAsync           = util.promisify(zlib.gzip);
@@ -151,6 +151,7 @@ function buildErrorHtml(title, heading, message) {
 const _NOT_FOUND_HTML       = buildErrorHtml('URL not found',         'Not Found',             'The requested URL was not found on this server.');
 const _GATEWAY_TIMEOUT_HTML = buildErrorHtml('Gateway Timeout',       'Gateway Timeout',       'The template took too long to render.');
 const _TEMPLATE_ERROR_HTML  = buildErrorHtml('Internal Server Error', 'Internal Server Error', 'Template rendering failed for the requested resource.');
+const _INTERNAL_ERROR_HTML  = buildErrorHtml('Internal Server Error', 'Internal Server Error', 'The server encountered an unexpected condition.');
 
 function sendNotFound(ctx) {
     setGeneratedPageHeaders(ctx, NOT_FOUND_CSP);
@@ -158,6 +159,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.
@@ -184,6 +193,23 @@ function warnPayload(logger, message) {
         : [message];
 }
 
+// Config-deprecation warnings, deduplicated once-per-process (per distinct
+// message) so creating many middleware instances doesn't repeat the same nag —
+// same intent as the _showDirContentsDeprecationWarned flag, generalized to
+// multiple messages. These options (urlPrefix, urlsReserved, ...) are v2-stable,
+// so a malformed value is TOLERATED with a warning for now rather than thrown:
+// throwing on a stable option would be a breaking change on a minor upgrade.
+// The next major will flip `warnConfigDeprecation` into a hard throw (the call
+// sites already carry the final message) — see docs/revisione_codice_v3.1.md #11.
+const _configDeprecationsWarned = new Set();
+function warnConfigDeprecation(logger, message) {
+    if (_configDeprecationsWarned.has(message)) return;
+    _configDeprecationsWarned.add(message);
+    logger.warn(...warnPayload(logger,
+        '[koa-classic-server] DEPRECATION: ' + message +
+        '\n  This is tolerated for now and WILL throw in a future major version.'));
+}
+
 // Sends an error response for a failed template render. If headers were already
 // flushed by the render itself, destroys the underlying socket instead (the
 // status/body can no longer be changed at that point).
@@ -379,6 +405,24 @@ function parseRangeHeader(rangeHeader, fileSize) {
     return { start, end };
 }
 
+// Evaluate an If-None-Match header against our (strong) ETag, per RFC 9110 §13.1.2.
+// The header is either "*" (matches any existing representation) or a comma-separated
+// list of entity-tags. The comparison is the WEAK function: a leading "W/" is ignored
+// on both sides (a proxy/CDN may have weakened the validator). Returns true when the
+// precondition is satisfied, i.e. the client's cached representation is still current
+// and the server should answer 304 (Not Modified) for a GET/HEAD.
+function ifNoneMatchSatisfied(headerValue, etag) {
+    if (!headerValue) return false;
+    const trimmed = headerValue.trim();
+    if (trimmed === '*') return true; // "*" matches any existing representation
+    const target = etag.replace(/^W\//, ''); // our ETag is strong, but strip defensively
+    for (const part of trimmed.split(',')) {
+        const tag = part.trim().replace(/^W\//, '');
+        if (tag && tag === target) return true;
+    }
+    return false;
+}
+
 // LFU cache with O(1) eviction using frequency buckets.
 // peek(key)  — read without touching frequency (for staleness checks)
 // get(key)   — read and increment frequency
@@ -412,10 +456,17 @@ class LFUCache {
     }
 
     set(key, entry) {
+        // An entry larger than the whole cache can never fit: bail out BEFORE the
+        // eviction loop, otherwise it would flush every other entry for nothing.
+        // Warn (throttled) so the operator learns the cache is undersized for
+        // this file instead of it silently never being cached.
+        if (entry.buffer.length > this.maxSize) {
+            this._warnThrottled(`[koa-classic-server] serverCache.${this.cacheLabel}: entry of ${entry.buffer.length} bytes exceeds maxSize (${this.maxSize} bytes) and will never be cached. Consider increasing maxSize.`);
+            return;
+        }
         while (this.currentSize + entry.buffer.length > this.maxSize && this._keyMap.size > 0) {
             this._evictOne();
         }
-        if (this.currentSize + entry.buffer.length > this.maxSize) return; // entry too large for cache
 
         this._keyMap.set(key, { ...entry, freq: 1 });
         this._addToFreqBucket(key, 1);
@@ -491,16 +542,37 @@ class LFUCache {
         bucket.delete(evictKey);
         if (bucket.size === 0) this._freqMap.delete(this._minFreq);
 
-        if (this.warnInterval !== false) {
-            const now = Date.now();
-            if (now - this._lastWarnAt >= this.warnInterval) {
-                this.logger.warn(`[koa-classic-server] serverCache.${this.cacheLabel}: maxSize reached, evicting LFU entries. Consider increasing maxSize.`);
-                this._lastWarnAt = now;
-            }
+        this._warnThrottled(`[koa-classic-server] serverCache.${this.cacheLabel}: maxSize reached, evicting LFU entries. Consider increasing maxSize.`);
+    }
+
+    // Emits a warning at most once per warnInterval ms (0 = always, false = never).
+    _warnThrottled(message) {
+        if (this.warnInterval === false) return;
+        const now = Date.now();
+        if (now - this._lastWarnAt >= this.warnInterval) {
+            this.logger.warn(message);
+            this._lastWarnAt = now;
         }
     }
 }
 
+// Single-flight job map helper: joins the in-flight job for `key`, or starts
+// `work()` as the leader. Concurrent callers share the same Promise — including
+// a rejection, so on failure every waiter falls back together instead of
+// re-running the work. The entry is removed as soon as the job settles
+// (success or failure), so the next request after a failure retries from
+// scratch and the map only ever holds jobs actually in progress.
+function singleFlight(map, key, work) {
+    let job = map.get(key);
+    if (!job) {
+        job = work();
+        map.set(key, job);
+        const clean = () => map.delete(key);
+        job.then(clean, clean);
+    }
+    return job;
+}
+
 // Upserts a fresh entry into an LFUCache. When the previous entry was only
 // stale-by-age (mtime + size unchanged), updates in place so the existing
 // frequency counter survives — important for popular files refreshed by maxAge.
@@ -523,10 +595,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
@@ -542,16 +624,36 @@ module.exports = function koaClassicServer(
                                         //   when visible entries > entriesPerPage. Page index via
                                         //   ?page=N (0-based); out-of-range values are clamped silently.
                                         //   Must be a finite integer >= 0; 0 = disabled (no pagination).
+            trailingSlash: true,        // Canonical trailing-slash enforcement (V4). Default true:
+                                        //   GET /dir  (directory, no slash) → 301 redirect to /dir/
+                                        //   GET /file/ (file, trailing slash) → 404
+                                        //   so relative links in an index page resolve against the
+                                        //   directory. Set false for the v3 behavior (serve directories
+                                        //   and files regardless of the trailing slash).
         },
-        index: ["index.html"], // Index file name(s) - must be an ARRAY:
-                               //   - Array of strings: ["index.html", "index.htm", "default.html"]
-                               //   - Array of RegExp:  [/index\.html/i, /default\.(html|htm)/i]
-                               //   - Mixed array:      ["index.html", /index\.[eE][jJ][sS]/]
-                               // Priority is determined by array order (first match wins)
-        urlPrefix: "", // URL path prefix
-        urlsReserved: [], // Reserved paths (first level only)
+        index: [], // Index file name(s) - must be an ARRAY.
+                   // Default: [] — no index file is looked up; directories always
+                   // show the listing (when dirListing.enabled). Configure explicitly
+                   // for the classic index-file behavior, e.g. ["index.html"].
+                   //   - Array of strings: ["index.html", "index.htm", "default.html"]
+                   //   - Array of RegExp:  [/index\.html/i, /default\.(html|htm)/i]
+                   //   - Mixed array:      ["index.html", /index\.[eE][jJ][sS]/]
+                   // Priority is determined by array order (first match wins)
+        urlPrefix: "", // URL path prefix. Should start with "/" and NOT end with "/"
+                       //   (e.g. "/static"); "" disables the prefix. A malformed value
+                       //   is tolerated with a deprecation warning for now (behavior
+                       //   unchanged) and WILL throw in the next major version.
+        urlsReserved: [], // Reserved first-level paths passed through to next().
+                          //   Each entry should be a single first-level path: a leading
+                          //   "/" plus one segment, no further "/" (e.g. "/admin").
+                          //   Malformed entries are tolerated with a deprecation warning
+                          //   for now and WILL throw in the next major version (a
+                          //   non-string entry is dropped to avoid a per-request 500).
         template: {
             render: undefined, // Template rendering function: async (ctx, next, filePath, rawBuffer, signal) => {}
+                               // rawBuffer (4th arg, may be null) is READ-ONLY: the same Buffer
+                               // instance is shared with the server cache and with concurrent
+                               // requests — mutating it corrupts other responses.
             ext: [], // File extensions to process with template.render
             renderTimeout: 30000, // Max ms allowed for template.render (number ≥ 0; 0 = disabled).
                                   // On timeout responds 504 Gateway Timeout. The render receives an
@@ -610,9 +712,25 @@ module.exports = function koaClassicServer(
             enabled: true,                // master switch (false = disable all compression)
             encodings: ['br', 'gzip'],    // algorithms in priority order; [] = disable
             minFileSize: 1024,            // min file size in bytes to compress; false = no minimum
+            maxFileSize: 10485760,        // max file size (bytes) for the buffered high-quality
+                                          //   compression path (whole file in RAM → brotli Q11 →
+                                          //   result cached). Default: 10 MB; false = no cap.
+                                          //   Larger files are STILL compressed, but via the
+                                          //   bounded-RAM streaming mode (brotli Q4 / gzip 6, no
+                                          //   Content-Length, not cached). This is a SAFETY NET
+                                          //   against unbounded RAM/CPU on huge compressible files
+                                          //   (multi-GB logs/JSON/CSV), not a serving restriction.
             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.
@@ -630,8 +748,31 @@ module.exports = function koaClassicServer(
 
     const normalizedRootDir = path.resolve(rootDir);
 
-    const options = opts || {};
-    options.template = opts.template || {};
+    // Options must be a plain object, or omitted entirely (the `opts = {}`
+    // default covers undefined). An explicit null — or any other non-object —
+    // is a configuration bug: surface it with a helpful error instead of a raw
+    // TypeError further down (or, worse, a silent fall-through to defaults).
+    if (opts === null || typeof opts !== 'object' || Array.isArray(opts)) {
+        throw new Error(
+            '[koa-classic-server] options must be a plain object (or omitted entirely). Got: ' +
+            (opts === null ? 'null' : Array.isArray(opts) ? 'an array' : typeof opts)
+        );
+    }
+
+    // Work on a copy: the factory normalizes options in place and must never
+    // mutate the caller's configuration object (reusing one config for two
+    // instances, or inspecting it after startup, would otherwise observe the
+    // rewritten values). Only the two nested objects the normalization writes
+    // into need their own copy — template (render/ext/renderTimeout) and
+    // hideExtension (ext/redirect); every other namespace is only read and
+    // normalized into new internal structures.
+    const options = { ...opts };
+    options.template = (opts.template && typeof opts.template === 'object' && !Array.isArray(opts.template))
+        ? { ...opts.template }
+        : {};
+    if (options.hideExtension && typeof options.hideExtension === 'object' && !Array.isArray(options.hideExtension)) {
+        options.hideExtension = { ...options.hideExtension };
+    }
 
     const _logger = normalizeLogger(options.logger);
 
@@ -706,6 +847,15 @@ module.exports = function koaClassicServer(
             'dirListing.entriesPerPage',
             100
         ),
+        // Canonical trailing-slash enforcement (V4). Default ON:
+        //   - GET /dir  (directory, no slash) → 301 redirect to /dir/
+        //   - GET /file/ (file, trailing slash) → 404
+        // so relative links in an index page resolve against the directory and
+        // a file is only reachable at its slash-less URL. Set false to keep the
+        // v3 behavior (serve directories and files regardless of trailing slash).
+        trailingSlash: userDirListing && userDirListing.trailingSlash !== undefined
+            ? !!userDirListing.trailingSlash
+            : true,
     };
 
     // Normalize index option to array format
@@ -729,9 +879,68 @@ module.exports = function koaClassicServer(
         options.index = [];
     }
 
-    options.urlPrefix = typeof options.urlPrefix === 'string' ? options.urlPrefix : "";
+    // ── urlPrefix / urlsReserved validation (V3.1, deprecation-warn) ──
+    // The request-time matcher depends on an implicit format for both options,
+    // and a malformed value fails SILENTLY: a urlPrefix with a stray
+    // leading/trailing slash makes the middleware serve nothing (it always falls
+    // through to next()), and a urlsReserved entry without a leading slash makes
+    // the reservation never match (the path is served instead of passed on).
+    // Both are v2-stable options, so instead of throwing (a breaking change on a
+    // minor upgrade — a mis-slashed value that "worked" only by falling through
+    // to a downstream handler would suddenly change behavior), we WARN and leave
+    // the runtime behavior exactly as it is today. The next major turns these
+    // warnings into throws. The one exception is a non-string urlsReserved entry:
+    // it would 500 on every request (value.substring is not a function), which is
+    // not working behavior, so it is dropped defensively (still warned).
+    if (options.urlPrefix === undefined) {
+        options.urlPrefix = "";
+    } else if (typeof options.urlPrefix !== 'string') {
+        // Unchanged behavior: pre-existing code already coerced non-string → "".
+        warnConfigDeprecation(_logger,
+            'urlPrefix should be a string like "/static" (or "" for no prefix); got ' +
+            (options.urlPrefix === null ? 'null' : typeof options.urlPrefix) + ' — treating it as "".');
+        options.urlPrefix = "";
+    } else if (options.urlPrefix !== "" && (!options.urlPrefix.startsWith('/') || options.urlPrefix.endsWith('/'))) {
+        // Left as-is: the matcher behaves exactly as today (falls through to
+        // next() under this prefix). Warn only — no behavior change.
+        warnConfigDeprecation(_logger,
+            'urlPrefix should start with "/" and not end with "/" (use "" to disable); got ' +
+            JSON.stringify(options.urlPrefix) + ' — it will not route correctly until corrected.');
+    }
     const _urlPrefixParts = options.urlPrefix.split("/");
-    options.urlsReserved = Array.isArray(options.urlsReserved) ? options.urlsReserved : [];
+
+    if (options.urlsReserved === undefined) {
+        options.urlsReserved = [];
+    } else if (!Array.isArray(options.urlsReserved)) {
+        // Unchanged behavior: pre-existing code already coerced non-array → [].
+        warnConfigDeprecation(_logger,
+            'urlsReserved should be an array of first-level paths like ["/admin"]; got ' +
+            (options.urlsReserved === null ? 'null' : typeof options.urlsReserved) + ' — treating it as [].');
+        options.urlsReserved = [];
+    } else {
+        const cleaned = [];
+        for (const value of options.urlsReserved) {
+            if (typeof value !== 'string') {
+                // Dropped defensively: a non-string entry would throw at match
+                // time (value.substring is not a function) → a 500 on every
+                // request. Dropping it can't break working code.
+                warnConfigDeprecation(_logger,
+                    'urlsReserved entries must be strings like "/admin"; dropping a non-string (' +
+                    (value === null ? 'null' : typeof value) + ') entry.');
+                continue;
+            }
+            // Malformed but non-crashing (missing leading slash, extra segment,
+            // trailing slash, empty): kept as-is so the matcher behaves exactly
+            // as today (it simply won't match). Warn only.
+            if (value === '' || !value.startsWith('/') || value.indexOf('/', 1) !== -1) {
+                warnConfigDeprecation(_logger,
+                    'each urlsReserved entry should be a single first-level path — a leading "/" plus one ' +
+                    'segment, e.g. "/admin"; got ' + JSON.stringify(value) + ' — it will not match until corrected.');
+            }
+            cleaned.push(value);
+        }
+        options.urlsReserved = cleaned;
+    }
     options.template.render = (options.template.render === undefined || typeof options.template.render === 'function') ? options.template.render : undefined;
     options.template.ext = Array.isArray(options.template.ext) ? options.template.ext : [];
 
@@ -762,7 +971,21 @@ module.exports = function koaClassicServer(
         );
     }
 
-    options.browserCacheMaxAge = typeof options.browserCacheMaxAge === 'number' && options.browserCacheMaxAge >= 0 ? options.browserCacheMaxAge : 3600;
+    // browserCacheMaxAge: non-negative integer seconds. An invalid value (negative, NaN,
+    // non-integer, Infinity, or a string) previously fell back to 3600 SILENTLY (#12).
+    // Consistent with #11: warn now and keep the fallback; a future major will throw
+    // (validateNonNegativeInt semantics) — so what warns here is exactly what will throw then.
+    if (options.browserCacheMaxAge === undefined) {
+        options.browserCacheMaxAge = 3600;
+    } else if (!(typeof options.browserCacheMaxAge === 'number'
+        && Number.isInteger(options.browserCacheMaxAge)
+        && options.browserCacheMaxAge >= 0)) {
+        warnConfigDeprecation(_logger,
+            'browserCacheMaxAge must be a non-negative integer (seconds). Got: ' +
+            String(options.browserCacheMaxAge) + '. Falling back to the default 3600 for now.');
+        options.browserCacheMaxAge = 3600;
+    }
+    // else: valid — keep as-is
     options.browserCacheEnabled = typeof options.browserCacheEnabled === 'boolean' ? options.browserCacheEnabled : false;
     options.useOriginalUrl = typeof options.useOriginalUrl === 'boolean' ? options.useOriginalUrl : true;
 
@@ -986,6 +1209,7 @@ module.exports = function koaClassicServer(
                 enabled: true,
                 encodings: ['br', 'gzip'],              // priority order: brotli first, gzip as fallback
                 minFileSize: 1024,                      // bytes; skip compression for files smaller than this
+                maxFileSize: 10485760,                  // bytes; above this the buffered+cached path is skipped (streaming instead)
                 mimeTypes: new Set(DEFAULT_COMPRESSIBLE_MIME_TYPES),
             };
         }
@@ -1008,11 +1232,17 @@ module.exports = function koaClassicServer(
         const minFileSize = compression.minFileSize === false ? false
             : (typeof compression.minFileSize === 'number' && compression.minFileSize >= 0 ? compression.minFileSize : 1024);
 
+        // Cap for the buffered (whole-file-in-RAM, max-quality, cached) compression
+        // path. false = no cap. Files above the cap still get compressed via the
+        // bounded-RAM streaming mode — safety net, not a serving restriction.
+        const maxFileSize = compression.maxFileSize === false ? false
+            : (typeof compression.maxFileSize === 'number' && compression.maxFileSize > 0 ? compression.maxFileSize : 10485760);
+
         const mimeTypes = Array.isArray(compression.mimeTypes) && compression.mimeTypes.length > 0
             ? compression.mimeTypes
             : DEFAULT_COMPRESSIBLE_MIME_TYPES;
 
-        return { enabled, encodings, minFileSize, mimeTypes: new Set(mimeTypes) };
+        return { enabled, encodings, minFileSize, maxFileSize, mimeTypes: new Set(mimeTypes) };
     }
 
     // Normalize and validate the serverCache option into a clean internal structure.
@@ -1066,6 +1296,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);
 
@@ -1087,12 +1411,40 @@ module.exports = function koaClassicServer(
         _logger
     );
 
-    // Returns the client's preferred encoding based on Accept-Encoding header,
-    // filtered against the enabled encodings list. Returns null if no match.
+    // Single-flight maps for cache population (thundering-herd protection):
+    // N concurrent misses on the same key share ONE read (+ compression) instead
+    // of N duplicated jobs. Entries live only while a job is in flight. Keys
+    // include the stat'd mtime+size so requests that observed different versions
+    // of the file never share a job (each response stays coherent with its own
+    // ETag/Last-Modified).
+    const _inflightRawReads     = new Map(); // `${path}:${mtime}:${size}` → Promise<Buffer>
+    const _inflightCompressions = new Map(); // `${path}:${encoding}:${mtime}:${size}` → Promise<Buffer>
+
+    // Returns the server-preferred enabled encoding the client is willing to accept.
+    // Server preference order (compressionConfig.encodings) still wins; the
+    // Accept-Encoding q-values are used only to EXCLUDE encodings the client refuses
+    // (q=0), per RFC 9110 §12.5.3. Token match is exact, not substring ("x-gzip" is
+    // NOT "gzip"). A "*" supplies the q-value for any encoding not explicitly listed.
     function getClientEncoding(acceptEncoding) {
         if (!acceptEncoding) return null;
+        const qValues = new Map(); // token → q-value
+        for (const part of acceptEncoding.split(',')) {
+            const [tokenRaw, ...params] = part.split(';');
+            const token = tokenRaw.trim().toLowerCase();
+            if (!token) continue;
+            let q = 1;
+            for (const p of params) {
+                const m = /^\s*q=(\d+(?:\.\d+)?)\s*$/i.exec(p);
+                if (m) q = parseFloat(m[1]);
+            }
+            qValues.set(token, q);
+        }
+        const star = qValues.get('*');
         for (const enc of compressionConfig.encodings) {
-            if (acceptEncoding.includes(enc)) return enc;
+            let q = qValues.get(enc);
+            if (q === undefined) q = star;   // not listed → fall back to "*" if present
+            if (q === undefined) continue;   // not listed and no "*" → not offered
+            if (q > 0) return enc;           // acceptable → pick it (server preference order)
         }
         return null;
     }
@@ -1188,11 +1540,26 @@ module.exports = function koaClassicServer(
         const urlToUse = options.useOriginalUrl ? ctx.originalUrl : ctx.url;
         const _origin  = ctx.protocol + '://' + ctx.host;
         const fullUrl  = _origin + urlToUse;
+
+        // Whether the client's request path ends with "/" — captured from the
+        // raw originalUrl BEFORE the trailing slash is stripped for URL parsing
+        // below. Drives the canonical trailing-slash redirect / 404 in the
+        // directory / file branch. "/" (root) counts as ending with a slash, so
+        // it is already canonical and never redirects.
+        const _rawOriginalPath = ctx.originalUrl.split('?')[0];
+        const _pathEndsWithSlash = _rawOriginalPath.endsWith('/');
+        // 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
@@ -1211,7 +1578,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)
@@ -1225,167 +1597,291 @@ module.exports = function koaClassicServer(
             }
         }
 
-        // Path traversal protection: build and validate safe file path
-        let requestedPath = "";
-        if (pageHrefOutPrefix.pathname === "/") {
-            requestedPath = "";
-        } else {
-            requestedPath = decodeURIComponent(pageHrefOutPrefix.pathname);
-        }
-
-        // 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';
-            return;
-        }
+        // From this point on the middleware OWNS the request: every early
+        // pass-through above has already returned, and no next() is called below
+        // (the template render's next goes through tryRenderTemplate's own catch).
+        // Last-resort net: an unexpected failure on any unguarded path must not
+        // leak to Koa's default handler (a plain-text 500 without the middleware's
+        // security headers, logged outside the operator's `logger`). Errors from
+        // downstream middleware are NOT masked — they never reach this try.
+        try {
+            // Path traversal protection: build and validate safe file path
+            let requestedPath = "";
+            if (pageHrefOutPrefix.pathname === "/") {
+                requestedPath = "";
+            } else {
+                // 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;
+                }
+            }
 
-        const normalizedPath = path.normalize(requestedPath);
-        const fullPath = path.join(normalizedRootDir, normalizedPath);
+            // 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')) {
+                sendBadRequest(ctx);
+                return;
+            }
 
-        // Security check: ensure resolved path is within rootDir.
-        // 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';
-            return;
-        }
+            const normalizedPath = path.normalize(requestedPath);
+            const fullPath = path.join(normalizedRootDir, normalizedPath);
+
+            // 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).
+            // 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;
+            }
 
-        // Hidden check: block requests that traverse a hidden directory.
-        // Stops at length-1 because the leaf (the file or dir being served) is
-        // checked separately by the file/listing path with its real stat.isDirectory().
-        if (requestedPath !== '') {
-            const segments = normalizedPath.split(path.sep).filter(Boolean);
-            for (let i = 0; i < segments.length - 1; i++) {
-                const segName = segments[i];
-                const segRelPath = segments.slice(0, i + 1).join('/');
-                if (isHiddenEntry(segName, segRelPath, true)) {
-                    sendNotFound(ctx);
-                    return;
+            // Hidden check: block requests that traverse a hidden directory.
+            // Stops at length-1 because the leaf (the file or dir being served) is
+            // checked separately by the file/listing path with its real stat.isDirectory().
+            if (requestedPath !== '') {
+                const segments = normalizedPath.split(path.sep).filter(Boolean);
+                for (let i = 0; i < segments.length - 1; i++) {
+                    const segName = segments[i];
+                    const segRelPath = segments.slice(0, i + 1).join('/');
+                    if (isHiddenEntry(segName, segRelPath, true)) {
+                        sendNotFound(ctx);
+                        return;
+                    }
                 }
             }
-        }
 
-        let toOpen = fullPath;
-
-        // hideExtension logic: redirect URLs with extension and resolve clean URLs
-        if (options.hideExtension) {
-            const hideExt = options.hideExtension.ext;
-            const hideRedirect = options.hideExtension.redirect;
-
-            // Trailing slash check via string — avoids a full new URL() construction
-            const rawPath = urlToUse.split('?')[0];
-            const hadTrailingSlash = rawPath.length > 1 && rawPath.endsWith('/');
-
-            // Strip a trailing slash before the extension check so URLs like /foo.html/
-            // still match (the slash is URL formality, not part of the filename) — without
-            // this, /foo.html/ would skip the redirect and 404 trying to open it as a dir.
-            const pathForExtCheck = hadTrailingSlash ? rawPath.slice(0, -1) : requestedPath;
-            if (pathForExtCheck.endsWith(hideExt)) {
-                // Build redirect target using ctx.originalUrl (always, regardless of useOriginalUrl)
-                const originalUrlObj = new URL(_origin + ctx.originalUrl);
-                let redirectPath = originalUrlObj.pathname;
-
-                // Collapse leading slashes: a Location header starting with "//" (or "/\")
-                // is a protocol-relative URL and would let "GET //evil.com/foo.ejs" redirect
-                // off-origin. path.normalize() upstream already collapses these for the
-                // filesystem check, so the source-of-truth URL has a single leading slash.
-                if (redirectPath.length > 1 && (redirectPath.charCodeAt(1) === 0x2F || redirectPath.charCodeAt(1) === 0x5C)) {
-                    redirectPath = '/' + redirectPath.replace(/^[/\\]+/, '');
-                }
+            let toOpen = fullPath;
+
+            // hideExtension logic: redirect URLs with extension and resolve clean URLs
+            if (options.hideExtension) {
+                const hideExt = options.hideExtension.ext;
+                const hideRedirect = options.hideExtension.redirect;
+
+                // Trailing slash check via string — avoids a full new URL() construction
+                const rawPath = urlToUse.split('?')[0];
+                const hadTrailingSlash = rawPath.length > 1 && rawPath.endsWith('/');
+
+                // Model B (V4): an extension URL is canonicalized to its clean form only when it
+                // has NO trailing slash. A trailing slash means directory intent, so /foo.ejs/
+                // falls through to the file/dir dispatch, where a file requested with a trailing
+                // slash is a 404 (finding #3). We gate on _pathEndsWithSlash — the very flag that
+                // #3's file-branch 404 uses — so "skip the redirect" and "404 downstream" are the
+                // same condition. requestedPath is decoded (and already slash-stripped by the URL
+                // parse), so a percent-encoded dot (/foo%2Eejs → /foo.ejs) matches consistently (#14),
+                // while /foo%2Eejs/ is excluded here by _pathEndsWithSlash and 404s downstream.
+                if (!_pathEndsWithSlash && requestedPath.endsWith(hideExt)) {
+                    // Build redirect target using ctx.originalUrl (always, regardless of
+                    // useOriginalUrl). With useOriginalUrl: false the URL-parsing prologue
+                    // validated ctx.url (the rewritten one), NOT originalUrl — a malformed
+                    // originalUrl (e.g. an absolute-form request target, legal in HTTP/1.1)
+                    // makes this constructor throw. Same treatment as the other malformed
+                    // client input: 400 Bad Request, not an unhandled error.
+                    let originalUrlObj;
+                    try {
+                        originalUrlObj = new URL(_origin + ctx.originalUrl);
+                    } catch {
+                        sendBadRequest(ctx);
+                        return;
+                    }
 
-                redirectPath = redirectPath.slice(0, redirectPath.length - hideExt.length);
-
-                // Special case: /index.ejs → /, /sezione/index.ejs → /sezione/
-                const baseName = path.basename(redirectPath);
-                // Check if the remaining path points to an index file
-                if (options.index && options.index.length > 0) {
-                    for (const pattern of options.index) {
-                        if (typeof pattern === 'string' && (baseName + hideExt) === pattern) {
-                            // Redirect to the directory (with trailing slash)
-                            redirectPath = redirectPath.slice(0, redirectPath.length - baseName.length);
-                            break;
+                    // Build the clean target in DECODED space: the extension may be percent-encoded
+                    // in the raw URL (e.g. "%2Eejs"), so decoding first makes it literal and
+                    // sliceable, then we re-encode per segment (#14, #20). The URL constructor
+                    // already validated the encoding, so decodeURIComponent cannot throw — but
+                    // guard for symmetry with the other malformed-client-input guards.
+                    let decodedPath;
+                    try {
+                        decodedPath = decodeURIComponent(originalUrlObj.pathname);
+                    } catch {
+                        sendBadRequest(ctx);
+                        return;
+                    }
+
+                    let cleanPath = decodedPath.slice(0, decodedPath.length - hideExt.length);
+
+                    // Special case: /index.ejs → /, /sezione/index.ejs → /sezione/
+                    const baseName = path.basename(cleanPath);
+                    if (options.index && options.index.length > 0) {
+                        for (const pattern of options.index) {
+                            if (typeof pattern === 'string' && (baseName + hideExt) === pattern) {
+                                // Redirect to the directory (with trailing slash)
+                                cleanPath = cleanPath.slice(0, cleanPath.length - baseName.length);
+                                break;
+                            }
                         }
                     }
-                }
 
-                // Preserve query string
-                const redirectUrl = redirectPath + (originalUrlObj.search || '');
+                    // Re-encode per path segment: round-trips spaces, "%", etc. back into a valid
+                    // URL. encodeURIComponent may over-encode sub-delims in exotic filenames, but
+                    // the result always resolves to the same path.
+                    let redirectPath = cleanPath.split('/').map(encodeURIComponent).join('/');
+
+                    // Open-redirect guard LAST: a Location starting with "//" (or "/\") is a
+                    // protocol-relative URL that would navigate off-origin ("GET //evil.com/foo.ejs").
+                    // Placed after re-encoding because a decoded "%2F" can reintroduce a leading
+                    // "//"; collapse any run of leading slashes/backslashes to a single slash.
+                    if (redirectPath.length > 1 && (redirectPath.charCodeAt(1) === 0x2F || redirectPath.charCodeAt(1) === 0x5C)) {
+                        redirectPath = '/' + redirectPath.replace(/^[/\\]+/, '');
+                    }
 
-                ctx.status = hideRedirect;
-                ctx.redirect(redirectUrl);
-                return;
-            }
+                    // Preserve query string
+                    const redirectUrl = redirectPath + (originalUrlObj.search || '');
+
+                    ctx.status = hideRedirect;
+                    ctx.redirect(redirectUrl);
+                    return;
+                }
 
-            // Check if URL has no extension → try adding the configured extension
-            // Skip if original URL had trailing slash (trailing slash = directory intent)
-            const extOfRequested = path.extname(requestedPath);
-            if (!extOfRequested && requestedPath !== '' && !requestedPath.endsWith('/') && !hadTrailingSlash) {
-                const pathWithExt = fullPath + hideExt;
+                // Check if URL has no extension → try adding the configured extension
+                // Skip if original URL had trailing slash (trailing slash = directory intent)
+                const extOfRequested = path.extname(requestedPath);
+                if (!extOfRequested && requestedPath !== '' && !requestedPath.endsWith('/') && !hadTrailingSlash) {
+                    const pathWithExt = fullPath + hideExt;
 
-                // Security check: ensure resolved path is still within rootDir
-                if (pathWithExt.startsWith(normalizedRootDir)) {
-                    try {
-                        const statWithExt = await fs.promises.stat(pathWithExt);
-                        if (statWithExt.isFile()) {
-                            // File with extension exists, serve it
-                            toOpen = pathWithExt;
+                    // 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()) {
+                                // File with extension exists, serve it
+                                toOpen = pathWithExt;
+                            }
+                        } catch {
+                            // File with extension doesn't exist, continue normal flow
                         }
-                    } catch {
-                        // File with extension doesn't exist, continue normal flow
                     }
                 }
             }
-        }
 
-        // Check if path exists
-        let stat;
-        try {
-            stat = await fs.promises.stat(toOpen);
-        } catch {
-            // File/directory doesn't exist or can't be accessed
-            sendNotFound(ctx);
-            return;
-        }
+            // Check if path exists
+            let stat;
+            try {
+                stat = await fs.promises.stat(toOpen);
+            } catch {
+                // File/directory doesn't exist or can't be accessed
+                sendNotFound(ctx);
+                return;
+            }
 
-        // Hidden check: block access to the requested file or directory itself
-        if (requestedPath !== '') {
-            const entryName = path.basename(toOpen);
-            const entryRelPath = path.relative(normalizedRootDir, toOpen).split(path.sep).join('/');
-            if (isHiddenEntry(entryName, entryRelPath, stat.isDirectory())) {
+            // Hidden check: block access to the requested file or directory itself
+            if (requestedPath !== '') {
+                const entryName = path.basename(toOpen);
+                const entryRelPath = path.relative(normalizedRootDir, toOpen).split(path.sep).join('/');
+                if (isHiddenEntry(entryName, entryRelPath, stat.isDirectory())) {
+                    sendNotFound(ctx);
+                    return;
+                }
+            }
+
+            // 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) {
-                // Search for index file matching configured patterns
-                if (options.index && options.index.length > 0) {
-                    const indexFile = await findIndexFile(toOpen, options.index);
-                    if (indexFile) {
-                        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);
-                            await loadFile(indexPath, indexFile.stat);
+            if (stat.isDirectory()) {
+                // Handle directory
+                if (options.dirListing.enabled) {
+                    // Canonical trailing-slash redirect (V4): a directory URL
+                    // without a trailing slash serves an index/listing whose
+                    // relative links would resolve against the parent. Redirect
+                    // /dir → /dir/ (301) BEFORE serving so the browser's base is
+                    // the directory itself.
+                    if (options.dirListing.trailingSlash && !_pathEndsWithSlash) {
+                        // Build the Location from the parsed originalUrl (same
+                        // defense as the hideExtension redirect): re-parsing forces
+                        // the target to be origin-relative — an absolute-form
+                        // request target (`GET http://evil/x`, legal in HTTP/1.1
+                        // and reachable under useOriginalUrl:false + rewriting)
+                        // would otherwise become an off-origin `Location` (open
+                        // redirect). .pathname keeps urlPrefix and percent-encoding.
+                        let originalUrlObj;
+                        try {
+                            originalUrlObj = new URL(_origin + ctx.originalUrl);
+                        } catch {
+                            sendBadRequest(ctx);
                             return;
                         }
+                        // Collapse a leading "//" / "/\" (protocol-relative) to a
+                        // single slash before appending the canonical trailing one.
+                        let redirectPath = originalUrlObj.pathname;
+                        if (redirectPath.length > 1 && (redirectPath.charCodeAt(1) === 0x2F || redirectPath.charCodeAt(1) === 0x5C)) {
+                            redirectPath = '/' + redirectPath.replace(/^[/\\]+/, '');
+                        }
+                        ctx.status = 301;
+                        ctx.redirect(redirectPath + '/' + originalUrlObj.search);
+                        return;
                     }
-                }
 
-                // No index file found, show directory listing
-                ctx.body = await show_dir(toOpen, ctx);
+                    // Search for index file matching configured patterns
+                    if (options.index && options.index.length > 0) {
+                        const indexFile = await findIndexFile(toOpen, options.index);
+                        if (indexFile) {
+                            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;
+                            }
+                        }
+                    }
+
+                    // No index file found, show directory listing
+                    ctx.body = await show_dir(toOpen, ctx);
+                } else {
+                    // Directory listing disabled
+                    sendNotFound(ctx);
+                }
+                return;
             } else {
-                // Directory listing disabled
-                sendNotFound(ctx);
+                // Canonical trailing-slash 404 (V4): a trailing slash means
+                // "directory", but this path resolved to a FILE — a file is only
+                // reachable at its slash-less URL. Return 404 (indistinguishable
+                // from not-found) rather than serving the file at a non-canonical
+                // URL. Disabled by dirListing.trailingSlash: false (v3 behavior).
+                if (options.dirListing.trailingSlash && _pathEndsWithSlash) {
+                    sendNotFound(ctx);
+                    return;
+                }
+                await loadFile(toOpen, stat);
+                return;
             }
-            return;
-        } else {
-            await loadFile(toOpen, stat);
-            return;
+        } catch (err) {
+            _logger.error('[koa-classic-server] Unexpected error while serving the request:', err);
+            if (ctx.headerSent || ctx.res.writableEnded) {
+                ctx.res.destroy(); // response already in flight — nothing sane left to send
+                return;
+            }
+            // Scrub representation/caching headers a partially-built response may
+            // have left behind: a stale Content-Encoding would corrupt the error
+            // page, a public Cache-Control could get the 500 cached by proxies.
+            for (const h of ['Content-Encoding', 'Content-Disposition', 'Content-Range', 'Vary', 'ETag', 'Last-Modified', 'Accept-Ranges']) {
+                ctx.remove(h);
+            }
+            ctx.set('Cache-Control', 'no-store');
+            ctx.set('Content-Type', 'text/html; charset=utf-8');
+            setGeneratedPageHeaders(ctx, NOT_FOUND_CSP);
+            ctx.status = 500;
+            ctx.body = _INTERNAL_ERROR_HTML;
         }
 
         // Internal functions
@@ -1419,13 +1915,23 @@ module.exports = function koaClassicServer(
                     rawBuffer = cached.buffer;
                 } else {
                     try {
-                        rawBuffer = await fs.promises.readFile(toOpen);
-                        refreshOrInsert(_rawFileCache, toOpen, {
-                            buffer: rawBuffer,
-                            mtime: fileStat.mtime.getTime(),
-                            size: fileStat.size,
-                            insertedAt: Date.now(),
-                        }, cached, staleByAge);
+                        // Single-flight: concurrent misses on the same path share one
+                        // readFile + cache insert; only the leader (the closure below)
+                        // runs, waiters await the same Promise. The key includes the
+                        // stat'd mtime+size so a request that observed a DIFFERENT
+                        // version of the file starts its own job instead of adopting
+                        // bytes that don't match the validators it will emit.
+                        const inflightKey = `${toOpen}:${fileStat.mtime.getTime()}:${fileStat.size}`;
+                        rawBuffer = await singleFlight(_inflightRawReads, inflightKey, async () => {
+                            const buf = await fs.promises.readFile(toOpen);
+                            refreshOrInsert(_rawFileCache, toOpen, {
+                                buffer: buf,
+                                mtime: fileStat.mtime.getTime(),
+                                size: fileStat.size,
+                                insertedAt: Date.now(),
+                            }, cached, staleByAge);
+                            return buf;
+                        });
                     } catch {
                         rawBuffer = null; // Fall through to disk reads later
                     }
@@ -1442,6 +1948,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`);
@@ -1464,6 +1979,67 @@ module.exports = function koaClassicServer(
                 }
             }
 
+            // Determine MIME type and compression encoding for the full-file response
+            const mimeType = mime.lookup(toOpen) || 'application/octet-stream';
+            const filename = path.basename(toOpen);
+
+            // Resolve compression: enabled + compressible MIME + meets minFileSize + client supports it
+            let encoding = null; // 'br' | 'gzip' | null
+            let potentiallyCompressible = false; // response content-negotiates on Accept-Encoding
+            if (compressionConfig.enabled && compressionConfig.encodings.length > 0) {
+                const isCompressibleMime = compressionConfig.mimeTypes.has(mimeType);
+                const meetsMinSize = compressionConfig.minFileSize === false
+                    || fileStat.size >= compressionConfig.minFileSize;
+                if (isCompressibleMime && meetsMinSize) {
+                    potentiallyCompressible = true; // even if this client gets identity
+                    encoding = getClientEncoding(ctx.get('Accept-Encoding'));
+                }
+            }
+
+            // fullEtag is encoding-specific to avoid false 304 hits across representations.
+            // Proxies use Vary: Accept-Encoding to cache separate versions per encoding.
+            const etagSuffix = encoding === 'br' ? '-br' : encoding === 'gzip' ? '-gz' : '';
+            const fullEtag = `"${fileStat.mtime.getTime()}-${fileStat.size}${etagSuffix}"`;
+
+            // Vary: Accept-Encoding as soon as the resource is *potentially* compressible —
+            // regardless of whether THIS client gets a compressed variant, and regardless
+            // of browserCacheEnabled. RFC 9110 §15.4.5: the 304 below must carry the same
+            // Vary the 200 would; and a shared proxy must not serve the identity variant to
+            // a client that would have received the compressed one (#7).
+            if (potentiallyCompressible) {
+                ctx.set('Vary', 'Accept-Encoding');
+            }
+
+            // Preconditions are evaluated BEFORE the Range branch: RFC 9110 §13.2.2 gives the
+            // validators precedence over Range (steps 3/4 before step 5), so a conditional
+            // request that matches returns 304 (Not Modified), not 206 (Partial Content).
+            // Comparison uses fullEtag (the encoding-specific representation a full GET would
+            // return); a 206 below re-tags itself with baseEtag (the identity partial it serves).
+            if (options.browserCacheEnabled) {
+                ctx.set('ETag', fullEtag);
+                ctx.set('Last-Modified', fileStat.mtime.toUTCString());
+
+                // If-None-Match: "*" | comma-list, weak comparison (RFC 9110 §13.1.2).
+                if (ifNoneMatchSatisfied(ctx.get('If-None-Match'), fullEtag)) {
+                    ctx.status = 304;
+                    return;
+                }
+
+                // If-Modified-Since (date validation). The mtime is truncated to whole seconds
+                // before comparing: Last-Modified is emitted via toUTCString() (second precision
+                // — HTTP dates have no milliseconds), so a client echoing that header back would
+                // otherwise never match a sub-second mtime (e.g. 22:13:20.500 <= 22:13:20.000).
+                const clientModifiedSince = ctx.get('If-Modified-Since');
+                if (clientModifiedSince) {
+                    const clientDate = new Date(clientModifiedSince);
+                    const mtimeSeconds = Math.floor(fileStat.mtime.getTime() / 1000) * 1000;
+                    if (mtimeSeconds <= clientDate.getTime()) {
+                        ctx.status = 304;
+                        return;
+                    }
+                }
+            }
+
             // Range request handling (HTTP 206 Partial Content — compression skipped for ranges)
             const rangeHeader = ctx.get('Range');
             if (rangeHeader) {
@@ -1483,10 +2059,11 @@ module.exports = function koaClassicServer(
                     if (!ifRange || ifRange === baseEtag) {
                         const { start, end } = parsed;
                         const rangeLength = end - start + 1;
-                        const mimeType = mime.lookup(toOpen) || 'application/octet-stream';
-                        const filename = path.basename(toOpen);
 
                         ctx.status = 206;
+                        // 206 returns identity bytes → tag with baseEtag, not the encoding-specific
+                        // fullEtag set above. Last-Modified is already set (browserCacheEnabled).
+                        if (options.browserCacheEnabled) ctx.set('ETag', baseEtag);
                         ctx.set('Content-Range', `bytes ${start}-${end}/${fileSize}`);
                         ctx.set('Content-Type', mimeType);
                         ctx.set('Content-Length', String(rangeLength));
@@ -1494,8 +2071,9 @@ module.exports = function koaClassicServer(
 
                         if (ctx.method !== 'HEAD') {
                             if (rawBuffer) {
-                                // Serve range slice from in-memory buffer — zero disk I/O
-                                ctx.body = rawBuffer.slice(start, end + 1);
+                                // Serve range slice from in-memory buffer — zero disk I/O.
+                                // subarray(): zero-copy view; Buffer.slice is deprecated (DEP0158).
+                                ctx.body = rawBuffer.subarray(start, end + 1);
                             } else {
                                 const src = fs.createReadStream(toOpen, { start, end });
                                 src.on('error', (err) => {
@@ -1520,59 +2098,23 @@ module.exports = function koaClassicServer(
                 // Invalid Range → fall through to full 200 response
             }
 
-            // Determine MIME type and compression encoding for the full-file response
-            const mimeType = mime.lookup(toOpen) || 'application/octet-stream';
-            const filename = path.basename(toOpen);
-
-            // Resolve compression: enabled + compressible MIME + meets minFileSize + client supports it
-            let encoding = null; // 'br' | 'gzip' | null
-            if (compressionConfig.enabled && compressionConfig.encodings.length > 0) {
-                const isCompressibleMime = compressionConfig.mimeTypes.has(mimeType);
-                const meetsMinSize = compressionConfig.minFileSize === false
-                    || fileStat.size >= compressionConfig.minFileSize;
-                if (isCompressibleMime && meetsMinSize) {
-                    encoding = getClientEncoding(ctx.get('Accept-Encoding'));
-                }
-            }
-
-            // fullEtag is encoding-specific to avoid false 304 hits across representations.
-            // Proxies use Vary: Accept-Encoding to cache separate versions per encoding.
-            const etagSuffix = encoding === 'br' ? '-br' : encoding === 'gzip' ? '-gz' : '';
-            const fullEtag = `"${fileStat.mtime.getTime()}-${fileStat.size}${etagSuffix}"`;
-
-            // ETag, Last-Modified, and 304 check — deferred until encoding is known
-            if (options.browserCacheEnabled) {
-                ctx.set('ETag', fullEtag);
-                ctx.set('Last-Modified', fileStat.mtime.toUTCString());
-
-                // Check If-None-Match (ETag validation)
-                const clientEtag = ctx.get('If-None-Match');
-                if (clientEtag && clientEtag === fullEtag) {
-                    ctx.status = 304;
-                    return;
-                }
-
-                // Check If-Modified-Since (date validation)
-                const clientModifiedSince = ctx.get('If-Modified-Since');
-                if (clientModifiedSince) {
-                    const clientDate = new Date(clientModifiedSince);
-                    if (fileStat.mtime.getTime() <= clientDate.getTime()) {
-                        ctx.status = 304;
-                        return;
-                    }
-                }
-            }
-
             // Common response headers
             ctx.set('Content-Type', mimeType);
             ctx.set('Content-Disposition', buildContentDisposition(filename));
 
             if (encoding) {
                 // ── Compressed response ───────────────────────────────────────────────
+                // Vary: Accept-Encoding is already set above (potentiallyCompressible).
                 ctx.set('Content-Encoding', encoding);
-                ctx.set('Vary', 'Accept-Encoding'); // Required so proxies cache per-encoding
 
-                if (serverCacheConfig.compressedFile.enabled) {
+                // Safety net (#4): the buffered path reads the WHOLE file into RAM and
+                // compresses at max quality — fine for web assets, catastrophic for a
+                // multi-GB log/CSV. Above compression.maxFileSize the bounded-RAM
+                // streaming mode below is used instead (still compressed, not cached).
+                const withinCompressCap = compressionConfig.maxFileSize === false
+                    || fileStat.size <= compressionConfig.maxFileSize;
+
+                if (serverCacheConfig.compressedFile.enabled && withinCompressCap) {
                     // compressedFile cache mode: compress once → buffer in RAM → Content-Length known
                     const cacheKey = `${toOpen}:${encoding}`;
                     const cached = _compressedFileCache.peek(cacheKey);
@@ -1589,21 +2131,34 @@ module.exports = function koaClassicServer(
                         buf = cached.buffer; // Serve from cache
                     } else {
                         try {
-                            // Use rawFile buffer if available — avoids redundant disk read
-                            const rawData = rawBuffer || await fs.promises.readFile(toOpen);
-                            buf = await compressBuffer(rawData, encoding);
-
-                            refreshOrInsert(_compressedFileCache, cacheKey, {
-                                buffer: buf,
-                                mtime: fileStat.mtime.getTime(),
-                                size: fileStat.size,
-                                insertedAt: Date.now(),
-                            }, cached, staleByAge);
+                            // Single-flight: concurrent misses on the same path+encoding
+                            // share one read+compress+insert instead of N parallel brotli
+                            // jobs for identical content. A rejection is shared too: all
+                            // waiters land in this catch and use the uncompressed fallback.
+                            // The key includes the stat'd mtime+size so a request that
+                            // observed a DIFFERENT version of the file starts its own job
+                            // (its ETag/Last-Modified must describe the bytes it serves).
+                            const inflightKey = `${cacheKey}:${fileStat.mtime.getTime()}:${fileStat.size}`;
+                            buf = await singleFlight(_inflightCompressions, inflightKey, async () => {
+                                // Use rawFile buffer if available — avoids redundant disk read
+                                const rawData = rawBuffer || await fs.promises.readFile(toOpen);
+                                const compressed = await compressBuffer(rawData, encoding);
+                                refreshOrInsert(_compressedFileCache, cacheKey, {
+                                    buffer: compressed,
+                                    mtime: fileStat.mtime.getTime(),
+                                    size: fileStat.size,
+                                    insertedAt: Date.now(),
+                                }, cached, staleByAge);
+                                return compressed;
+                            });
                         } catch (err) {
                             _logger.error('Compression error:', err);
-                            // Fall back to uncompressed on any compression failure
+                            // Fall back to uncompressed on any compression failure. Vary STAYS
+                            // (the resource is still compressible), but the ETag must be reset to
+                            // the un-suffixed form: this identity body must not be cached by a
+                            // shared proxy under the -br/-gz validator (#7).
                             ctx.remove('Content-Encoding');
-                            ctx.remove('Vary');
+                            if (options.browserCacheEnabled) ctx.set('ETag', baseEtag);
                             if (rawBuffer) {
                                 ctx.set('Content-Length', String(rawBuffer.length));
                                 if (ctx.method !== 'HEAD') {
@@ -1645,20 +2200,28 @@ module.exports = function koaClassicServer(
                         const compress = encoding === 'br'
                             ? zlib.createBrotliCompress({ params: { [zlib.constants.BROTLI_PARAM_QUALITY]: 4 } })
                             : zlib.createGzip({ level: 6 });
-                        if (rawBuffer) {
-                            // Compress from in-memory buffer — no disk I/O
-                            const src = Readable.from(rawBuffer);
-                            ctx.body = src.pipe(compress);
-                        } else {
-                            const src = fs.createReadStream(toOpen);
-                            src.on('error', (err) => {
-                                _logger.error('Stream error:', err);
-                                if (!ctx.headerSent) { ctx.status = 500; ctx.body = 'Error reading file'; }
-                            });
-                            ctx.body = src.pipe(compress);
-                        }
+                        const src = rawBuffer
+                            ? Readable.from(rawBuffer) // compress from in-memory buffer — no disk I/O
+                            : fs.createReadStream(toOpen);
+                        // pipeline (NOT pipe): teardown propagates in BOTH directions.
+                        // When the client disconnects mid-transfer, Koa destroys the body
+                        // (`compress`) and pipeline destroys `src` too, closing its file
+                        // descriptor. A bare src.pipe(compress) leaves the ReadStream
+                        // paused with the fd open forever — fd leak under aborted
+                        // downloads. Client disconnects are a normal event and are not
+                        // logged (avoids client-driven log spam).
+                        ctx.body = pipeline(src, compress, (err) => {
+                            if (!err || err.code === 'ERR_STREAM_PREMATURE_CLOSE') return;
+                            _logger.error('Stream error:', err);
+                            if (!ctx.headerSent) { ctx.status = 500; ctx.body = 'Error reading file'; }
+                        });
+                    } else {
+                        // HEAD: mirror the GET status and headers (RFC 9110 §9.3.2) — no
+                        // Content-Length, since the compressed size is unknown without
+                        // running the compression. The explicit status is required: with
+                        // no body ever assigned, Koa would otherwise respond its default 404.
+                        ctx.status = 200;
                     }
-                    // HEAD + streaming: no Content-Length available; Koa sends headers only via res.end()
                 }
 
             } else {
@@ -1777,9 +2340,12 @@ module.exports = function koaClassicServer(
             parts.push("</thead>");
             parts.push("<tbody>");
 
-            // Parent directory link
+            // Parent directory link — omitted at the middleware's LOGICAL root
+            // (pageHrefOutPrefix.pathname === '/'), not only at the absolute root: with
+            // urlPrefix '/static', the listing of /static/ must not link to '/', which is
+            // outside the served tree (#13).
             const currentPath = pageHref.origin + pageHref.pathname;
-            if (currentPath !== pageHrefOutPrefix.origin + "/") {
+            if (pageHrefOutPrefix.pathname !== "/") {
                 // Build parent directory URL without query parameters
                 const a_pD = currentPath.split("/");
                 a_pD.pop();
@@ -1788,8 +2354,9 @@ module.exports = function koaClassicServer(
                 parts.push(`<tr><td><a href="${escapeHtml(parentDirectory)}"><b>.. Parent Directory</b></a></td><td>DIR</td><td>-</td></tr>`);
             }
 
+            const emptyFolderRow = `<tr><td>empty folder</td><td></td><td></td></tr>`;
             if (dir.length === 0) {
-                parts.push(`<tr><td>empty folder</td><td></td><td></td></tr>`);
+                parts.push(emptyFolderRow);
             } else {
                 const _listingBaseUrl = pageHref.origin + pageHref.pathname;
                 const _listingOriginPrefix = pageHref.origin + options.urlPrefix;
@@ -1838,10 +2405,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) {
@@ -1862,6 +2437,7 @@ module.exports = function koaClassicServer(
                                 effectiveType,
                                 isSymlink: type === 3,
                                 isBrokenSymlink,
+                                isBlockedSymlink,
                                 mimeType,
                                 sizeStr,
                                 sizeBytes,
@@ -1874,6 +2450,13 @@ module.exports = function koaClassicServer(
                 }
                 const items = rawItems.filter(Boolean);
 
+                // Every entry was filtered out as hidden (dotfiles / alwaysHide / blacklist):
+                // show the same "empty folder" row as a physically empty directory (#16), not a
+                // header-only empty table (which would also hint that hidden files exist).
+                if (items.length === 0) {
+                    parts.push(emptyFolderRow);
+                }
+
                 // Places directories before non-directories; falls back to `tieBreaker`
                 // when both items are in the same bucket. `effectiveType === 2` covers plain
                 // dirs and dir-resolved symlinks, matching the rest of the listing logic.
@@ -1923,14 +2506,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>`);