npm - koa-classic-server - Versions diffs - 3.0.0-alpha.0 → 3.0.0 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (33) hide show

package/CLAUDE.md +101 -0
package/README.md +550 -635
package/__tests__/benchmark-results-v3.0.0.txt +372 -0
package/__tests__/benchmark.js +1 -1
package/__tests__/compression.test.js +17 -3
package/__tests__/customTest/serversToLoad.util.js +4 -4
package/__tests__/demo-regex-index.js +4 -4
package/__tests__/directory-sorting-links.test.js +1 -1
package/__tests__/dt-unknown.test.js +19 -19
package/__tests__/ejs.test.js +1 -1
package/__tests__/hidden-option.test.js +48 -63
package/__tests__/hideExtension.test.js +70 -13
package/__tests__/index.test.js +6 -6
package/__tests__/listing.test.js +437 -0
package/__tests__/logger.test.js +232 -0
package/__tests__/range.test.js +2 -2
package/__tests__/security-headers.test.js +20 -8
package/__tests__/security.test.js +5 -5
package/__tests__/server-cache.test.js +178 -7
package/__tests__/symlink.test.js +10 -10
package/__tests__/template-timeout.test.js +321 -0
package/docs/CHANGELOG.md +209 -4
package/docs/CODE_REVIEW.md +2 -0
package/docs/DOCUMENTATION.md +259 -32
package/docs/EXAMPLES_INDEX_OPTION.md +1 -1
package/docs/FLOW_DIAGRAM.md +2 -0
package/docs/INDEX_OPTION_PRIORITY.md +2 -2
package/docs/OPTIMIZATION_HTTP_CACHING.md +2 -0
package/docs/security_improvement_for_V3.md +421 -0
package/docs/template-engine/TEMPLATE_ENGINE_GUIDE.md +5 -5
package/docs/template-engine/esempi-incrementali.js +1 -1
package/index.cjs +551 -178
package/package.json +6 -1

package/index.cjs CHANGED Viewed

@@ -4,15 +4,21 @@ const fs = require("fs");
 const path = require("path");
 const crypto = require("crypto");
 const zlib = require("zlib");
+const util = require("util");
 const mime = require("mime-types");
 const { Readable } = require('stream');
+const _brotliCompressAsync = util.promisify(zlib.brotliCompress);
+const _gzipAsync           = util.promisify(zlib.gzip);
 // Pre-computed module-level constants
 const _LOG_1024 = Math.log(1024);
-// Emitted at most once per process lifetime when hidden.dotFiles.default or
-// hidden.dotDirs.default are not explicitly set by the caller.
-let _hiddenDefaultWarnEmitted = false;
+// Emitted at most once per process lifetime when the caller passes the v2-era
+// `showDirContents` option instead of the v3 `dirListing.enabled`. The old
+// name is accepted as a backward-compatibility alias and may be removed in a
+// future major version.
+let _showDirContentsDeprecationWarned = false;
 // Default list of MIME types that benefit from compression.
 // User-provided compression.mimeTypes replaces this list entirely.
@@ -73,6 +79,36 @@ const LISTING_CSS = `
     th:nth-child(1), td:nth-child(1) { width: 50%; }
     th:nth-child(2), td:nth-child(2) { width: 30%; }
     th:nth-child(3), td:nth-child(3) { width: 20%; text-align: right; }
+    .kcs-banner {
+        max-width: 800px;
+        margin: 10px 0;
+        padding: 10px 14px;
+        background-color: #fff7e0;
+        border-left: 4px solid #e0a800;
+        font-size: 14px;
+        color: #5a4a00;
+    }
+    .kcs-pagination {
+        max-width: 800px;
+        margin: 16px 0;
+        font-size: 14px;
+    }
+    .kcs-pagination a, .kcs-pagination span {
+        display: inline-block;
+        padding: 4px 8px;
+        margin-right: 4px;
+    }
+    .kcs-pagination .kcs-page-current {
+        font-weight: bold;
+        background-color: #f0f0f0;
+        border-radius: 3px;
+    }
+    .kcs-pagination .kcs-page-ellipsis {
+        color: #888;
+    }
+    .kcs-pagination .kcs-page-disabled {
+        color: #bbb;
+    }
 `;
 // SHA-256 hash of the listing CSS, computed once at startup (zero per-request overhead).
@@ -94,20 +130,27 @@ function setGeneratedPageHeaders(ctx, csp) {
     ctx.set('Permissions-Policy', 'camera=(), microphone=(), geolocation=(), payment=()');
 }
-// Pre-computed 404 HTML body — identical on every call, no need to regenerate.
-const _NOT_FOUND_HTML = `<!DOCTYPE html>
+// Builds a minimal error page used by the middleware (404 / 500 / 504).
+// Each page is pre-computed once at module load and reused on every request.
+function buildErrorHtml(title, heading, message) {
+    return `<!DOCTYPE html>
 <html>
 <head>
   <meta charset="UTF-8">
   <meta http-equiv="X-UA-Compatible" content="IE=edge">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>URL not found</title>
+  <title>${title}</title>
 </head>
 <body>
-  <h1>Not Found</h1>
-  <h3>The requested URL was not found on this server.</h3>
+  <h1>${heading}</h1>
+  <h3>${message}</h3>
 </body>
 </html>`;
+}
+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.');
 function sendNotFound(ctx) {
     setGeneratedPageHeaders(ctx, NOT_FOUND_CSP);
@@ -115,6 +158,108 @@ function sendNotFound(ctx) {
     ctx.body = _NOT_FOUND_HTML;
 }
+// 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.
+function normalizeLogger(logger) {
+    if (logger === undefined) return console;
+    if (!logger || typeof logger !== 'object' || Array.isArray(logger)) {
+        throw new Error(
+            '[koa-classic-server] options.logger must be an object exposing error() and warn() methods.'
+        );
+    }
+    if (typeof logger.error !== 'function' || typeof logger.warn !== 'function') {
+        throw new Error(
+            '[koa-classic-server] options.logger must implement both error() and warn() methods.'
+        );
+    }
+    return logger;
+}
+// Yellow ANSI wrap, but only when writing to the actual console TTY. Structured
+// loggers (pino/winston/...) would otherwise receive escape bytes as noise.
+function warnPayload(logger, message) {
+    return logger === console
+        ? ['\x1b[33m%s\x1b[0m', message]
+        : [message];
+}
+// 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).
+function sendTemplateError(ctx, status, html, logMsg, err, logger) {
+    logger.error(logMsg, err);
+    if (ctx.headerSent || ctx.res.writableEnded) {
+        ctx.res.destroy();
+        return;
+    }
+    setGeneratedPageHeaders(ctx, NOT_FOUND_CSP);
+    ctx.status = status;
+    ctx.body = html;
+}
+// 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
+// normal file serving).
+//
+// The render function is invoked with (ctx, next, filePath, rawBuffer, signal).
+// The signal aborts on timeout (when templateOpts.renderTimeout > 0) and on
+// client disconnect. Cooperative renders that propagate the signal to fetch/db
+// release backend resources promptly; non-cooperative renders still get a 504
+// response, but their work continues in the background.
+async function tryRenderTemplate(ctx, next, filePath, rawBuffer, templateOpts, logger) {
+    if (templateOpts.ext.length === 0 || !templateOpts.render) return false;
+    const fileExt = path.extname(filePath).slice(1);
+    if (!fileExt || !templateOpts.ext.includes(fileExt)) return false;
+    const controller = new AbortController();
+    const onClientClose = () => controller.abort();
+    ctx.req.on('close', onClientClose);
+    const timeoutMs = templateOpts.renderTimeout;
+    let timer = null;
+    let timedOut = false;
+    const renderPromise = Promise.resolve().then(() =>
+        templateOpts.render(ctx, next, filePath, rawBuffer, controller.signal)
+    );
+    renderPromise.catch(() => {}); // swallow rejections that arrive after we've already responded
+    try {
+        if (timeoutMs > 0) {
+            await Promise.race([
+                renderPromise,
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => {
+                        timedOut = true;
+                        controller.abort();
+                        const err = new Error('Template render timeout');
+                        err.code = 'ETEMPLATETIMEOUT';
+                        reject(err);
+                    }, timeoutMs);
+                })
+            ]);
+        } else {
+            await renderPromise;
+        }
+    } catch (error) {
+        if (timedOut || error.code === 'ETEMPLATETIMEOUT') {
+            sendTemplateError(ctx, 504, _GATEWAY_TIMEOUT_HTML,
+                'Template render timeout after ' + timeoutMs + 'ms:', filePath, logger);
+        } else {
+            sendTemplateError(ctx, 500, _TEMPLATE_ERROR_HTML,
+                'Template rendering error:', error, logger);
+        }
+    } finally {
+        if (timer) clearTimeout(timer);
+        ctx.req.removeListener('close', onClientClose);
+    }
+    return true;
+}
 // Single-pass HTML escaping — one regex scan, one allocation, lookup table compiled once.
 const _HTML_ESCAPE_MAP = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#039;' };
 const _HTML_ESCAPE_RE  = /[&<>"']/g;
@@ -204,12 +349,13 @@ function parseRangeHeader(rangeHeader, fileSize) {
 // set(key, entry) — insert, evicting LFU entries if needed
 // delete(key) — remove explicitly (e.g. stale entry before re-insert)
 class LFUCache {
-    constructor(maxSize, warnInterval, cacheLabel) {
+    constructor(maxSize, warnInterval, cacheLabel, logger) {
         this.maxSize     = maxSize;
         this.warnInterval = warnInterval;
         this.cacheLabel  = cacheLabel;
+        this.logger      = logger || console;
         this.currentSize = 0;
-        this._keyMap     = new Map(); // key → { buffer, mtime, size, freq }
+        this._keyMap     = new Map(); // key → { buffer, mtime, size, insertedAt, freq }
         this._freqMap    = new Map(); // freq → Set<key>
         this._minFreq    = 0;
         this._lastWarnAt = 0;
@@ -241,6 +387,26 @@ class LFUCache {
         this._minFreq = 1;
     }
+    // In-place update of an existing entry that preserves its current frequency.
+    // Used when refreshing a stale-by-maxAge entry so popular files don't fall to
+    // the bottom of the LFU bucket just because they got re-read from disk.
+    // Returns true on success, false if the new buffer doesn't fit in maxSize
+    // (caller can fall back to delete + set in that case).
+    refresh(key, fields) {
+        const entry = this._keyMap.get(key);
+        if (!entry) return false;
+        const sizeDelta = fields.buffer.length - entry.buffer.length;
+        if (this.currentSize + sizeDelta > this.maxSize) return false;
+        entry.buffer = fields.buffer;
+        if (fields.mtime !== undefined)      entry.mtime = fields.mtime;
+        if (fields.size !== undefined)       entry.size = fields.size;
+        if (fields.insertedAt !== undefined) entry.insertedAt = fields.insertedAt;
+        this.currentSize += sizeDelta;
+        return true;
+    }
     delete(key) {
         if (!this._keyMap.has(key)) return;
         const { freq, buffer } = this._keyMap.get(key);
@@ -272,7 +438,6 @@ class LFUCache {
         if (!this._freqMap.has(freq)) this._freqMap.set(freq, new Set());
         this._freqMap.get(freq).add(key);
     }
     _evictOne() {
         // Recover from stale _minFreq (can happen after consecutive evictions)
         while (this._freqMap.size > 0 && (!this._freqMap.has(this._minFreq) || this._freqMap.get(this._minFreq).size === 0)) {
@@ -293,13 +458,28 @@ class LFUCache {
         if (this.warnInterval !== false) {
             const now = Date.now();
             if (now - this._lastWarnAt >= this.warnInterval) {
-                console.warn(`[koa-classic-server] serverCache.${this.cacheLabel}: maxSize reached, evicting LFU entries. Consider increasing maxSize.`);
+                this.logger.warn(`[koa-classic-server] serverCache.${this.cacheLabel}: maxSize reached, evicting LFU entries. Consider increasing maxSize.`);
                 this._lastWarnAt = now;
             }
         }
     }
 }
+// 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.
+// Otherwise falls back to delete + set (frequency resets to 1).
+function refreshOrInsert(cache, key, newEntry, cached, staleByAge) {
+    const canRefreshInPlace = cached
+        && staleByAge
+        && cached.mtime === newEntry.mtime
+        && cached.size === newEntry.size;
+    if (!canRefreshInPlace || !cache.refresh(key, newEntry)) {
+        if (cached) cache.delete(key);
+        cache.set(key, newEntry);
+    }
+}
 module.exports = function koaClassicServer(
     rootDir,
     opts = {}
@@ -307,7 +487,26 @@ module.exports = function koaClassicServer(
     opts STRUCTURE
      opts = {
         method: ['GET'], // Supported methods, otherwise next() will be called
-        showDirContents: true, // Show or hide directory contents
+        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.
+                                        //   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
+                                        //   restriction on what the operator can serve. 99% of legitimate
+                                        //   deployments never hit this cap. Excess entries are not shown:
+                                        //   a banner + the X-Dir-Truncated response header advertise the
+                                        //   truncation. Bounds the rendering / CPU cost, NOT the size of the
+                                        //   initial readdir() allocation.
+                                        //   Must be a finite integer >= 0; 0 = disabled (no cap).
+                                        //   For directories writable by untrusted parties, see the v3.1
+                                        //   TODO [F-1] in docs/security_improvement_for_V3.md (`readMode`).
+            entriesPerPage: 100,        // Entries per page in the listing UI. Pagination kicks in only
+                                        //   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).
+        },
         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]
@@ -316,8 +515,13 @@ module.exports = function koaClassicServer(
         urlPrefix: "", // URL path prefix
         urlsReserved: [], // Reserved paths (first level only)
         template: {
-            render: undefined, // Template rendering function: async (ctx, next, filePath) => {}
+            render: undefined, // Template rendering function: async (ctx, next, filePath, rawBuffer, signal) => {}
             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
+                                  // AbortSignal as 5th argument; propagate it to fetch/db/fs to free
+                                  // backend resources. The signal also aborts on client disconnect,
+                                  // even when renderTimeout is 0.
         },
         browserCacheMaxAge: 3600, // Browser Cache-Control max-age in seconds (default: 1 hour)
         browserCacheEnabled: false, // Enable browser HTTP caching headers (ETag, Last-Modified)
@@ -331,8 +535,10 @@ module.exports = function koaClassicServer(
             redirect: 301    // HTTP redirect code for URLs with extension (optional, default: 301)
         },
         hidden: {            // Block files/dirs from listing and serving (HTTP 404)
-            dotFiles: {      // Dot-files (names starting with '.'): hidden by default
-                default: 'hidden',   // 'hidden' | 'visible' — system default: 'hidden'
+            dotFiles: {      // Dot-files (names starting with '.'): visible by default — design philosophy
+                default: 'visible',  // 'hidden' | 'visible' — system default: 'visible'
+                                     //   To protect .env / .git / etc., set 'hidden' explicitly OR add to
+                                     //   `blacklist` / `alwaysHide`. See README "Security Checklist".
                 whitelist: [],       // Always visible (string exact/glob or RegExp). Overrides default and alwaysHide.
                 blacklist: [],       // Always hidden (string or RegExp). Overrides whitelist.
             },
@@ -350,21 +556,31 @@ module.exports = function koaClassicServer(
                 enabled: false,               // enable in-memory cache of raw file buffers
                 maxSize: 52428800,            // max total RAM used by this cache (bytes; default: 50 MB)
                 maxFileSize: 1048576,         // files larger than this are never cached (bytes; default: 1 MB)
+                maxAge: 0,                    // ms after insertion to consider an entry stale; 0 = disabled.
+                                              // Useful on NFS/SMB/overlay FS where mtime+size may not reflect
+                                              // remote changes within the OS attribute-cache window. Limits but
+                                              // does not eliminate staleness — combine with low actimeo on the
+                                              // mount for stricter freshness.
                 warnInterval: 60000,          // ms between "maxSize reached" warnings; 0 = always; false = never
             },
             compressedFile: {                 // cache for HTTP br/gzip responses — not for .zip/.tar files on disk
                 enabled: true,               // enable in-memory cache of compressed response buffers
                 maxSize: 104857600,          // max total RAM used by this cache (bytes; default: 100 MB)
+                maxAge: 0,                   // ms after insertion to consider an entry stale; 0 = disabled. See rawFile.maxAge.
                 warnInterval: 60000,         // ms between "maxSize reached" warnings; 0 = always; false = never
             },
         },
         compression: {       // Response compression (gzip / brotli) — to enable/disable caching → serverCache.compressedFile
             enabled: true,                // master switch (false = disable all compression)
             encodings: ['br', 'gzip'],    // algorithms in priority order; [] = disable
-            minSize: 1024,                // min file size in bytes to compress; false = no minimum
+            minFileSize: 1024,            // min file size in bytes to compress; false = no minimum
             mimeTypes: [],                // compressible MIME types (replaces default list if provided)
         },
         // compression: false            // shorthand to disable all compression
+        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.
+                            // Default: the global console.
     }
     */
@@ -381,8 +597,80 @@ module.exports = function koaClassicServer(
     const options = opts || {};
     options.template = opts.template || {};
+    const _logger = normalizeLogger(options.logger);
     options.method = Array.isArray(options.method) ? options.method : ['GET'];
-    options.showDirContents = typeof options.showDirContents === 'boolean' ? options.showDirContents : true;
+    // ── V3 breaking-change guards: helpful errors for V3-alpha-only renamed options ──
+    // These were introduced in v3.0.0-alpha.0 only; no v2 user can have them in production.
+    if (opts.maxDirEntries !== undefined) {
+        throw new Error(
+            '[koa-classic-server] options.maxDirEntries was relocated in v3.0.0.\n' +
+            `  Replace with: dirListing: { maxEntries: ${opts.maxDirEntries} }`
+        );
+    }
+    if (opts.pageSize !== undefined) {
+        throw new Error(
+            '[koa-classic-server] options.pageSize was relocated and renamed in v3.0.0.\n' +
+            `  Replace with: dirListing: { entriesPerPage: ${opts.pageSize} }`
+        );
+    }
+    function validateNonNegativeInt(value, optionName, defaultValue) {
+        if (value === undefined) return defaultValue;
+        if (typeof value !== 'number' || !Number.isFinite(value) || value < 0 || !Number.isInteger(value)) {
+            throw new Error(
+                `[koa-classic-server] options.${optionName} must be a non-negative integer. ` +
+                'Use 0 to disable. Got: ' + String(value)
+            );
+        }
+        return value;
+    }
+    // ── dirListing namespace (V3+) — single source of truth for listing config ──
+    const userDirListing = opts.dirListing;
+    if (userDirListing !== undefined && (typeof userDirListing !== 'object' || userDirListing === null || Array.isArray(userDirListing))) {
+        throw new Error('[koa-classic-server] options.dirListing must be an object.');
+    }
+    // V3 backward-compat alias: showDirContents (v2-stable) maps to dirListing.enabled.
+    // The alias may be removed in a future major version. Emits a one-time deprecation
+    // warning per process. Throws if both names are passed (the user picked one of them
+    // by mistake — surface the conflict rather than silently choosing one).
+    let aliasEnabled; // undefined unless showDirContents was passed
+    if (opts.showDirContents !== undefined) {
+        if (userDirListing && userDirListing.enabled !== undefined) {
+            throw new Error(
+                '[koa-classic-server] options.showDirContents and options.dirListing.enabled are both set.\n' +
+                '  These configure the same thing — pick one.'
+            );
+        }
+        if (!_showDirContentsDeprecationWarned) {
+            _showDirContentsDeprecationWarned = true;
+            _logger.warn(...warnPayload(_logger,
+                '[koa-classic-server] DEPRECATION: options.showDirContents was renamed to dirListing.enabled in v3.0.0.\n' +
+                '  The old name is currently accepted as an alias and may be removed in a future major version.\n' +
+                `  Replace with: dirListing: { enabled: ${opts.showDirContents} }`
+            ));
+        }
+        aliasEnabled = !!opts.showDirContents;
+    }
+    options.dirListing = {
+        enabled: userDirListing && userDirListing.enabled !== undefined
+            ? !!userDirListing.enabled
+            : (aliasEnabled !== undefined ? aliasEnabled : true),
+        maxEntries: validateNonNegativeInt(
+            userDirListing && userDirListing.maxEntries,
+            'dirListing.maxEntries',
+            10000
+        ),
+        entriesPerPage: validateNonNegativeInt(
+            userDirListing && userDirListing.entriesPerPage,
+            'dirListing.entriesPerPage',
+            100
+        ),
+    };
     // Normalize index option to array format
     if (typeof options.index === 'string') {
@@ -411,6 +699,19 @@ module.exports = function koaClassicServer(
     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 : [];
+    if (options.template.renderTimeout === undefined) {
+        options.template.renderTimeout = 30000;
+    } else if (
+        typeof options.template.renderTimeout !== 'number' ||
+        !Number.isFinite(options.template.renderTimeout) ||
+        options.template.renderTimeout < 0
+    ) {
+        throw new Error(
+            '[koa-classic-server] template.renderTimeout must be a finite number >= 0 (ms). ' +
+            'Use 0 to disable. Got: ' + String(options.template.renderTimeout)
+        );
+    }
     // v3.0.0: removed legacy option names — throw to surface the breaking change clearly
     if ('cacheMaxAge' in opts) {
         throw new Error(
@@ -439,13 +740,12 @@ module.exports = function koaClassicServer(
         }
         // Normalize ext: add leading dot if missing
         if (!options.hideExtension.ext.startsWith('.')) {
-            console.warn(
-                '\x1b[33m%s\x1b[0m',
+            _logger.warn(...warnPayload(_logger,
                 '[koa-classic-server] WARNING: hideExtension.ext should start with a dot.\n' +
                 `  Current usage: ext: "${options.hideExtension.ext}"\n` +
                 `  Corrected to:  ext: ".${options.hideExtension.ext}"\n` +
                 '  Please update your configuration.'
-            );
+            ));
             options.hideExtension.ext = '.' + options.hideExtension.ext;
         }
         // Validate redirect code
@@ -462,7 +762,7 @@ module.exports = function koaClassicServer(
     function normalizeHiddenConfig(hidden) {
         if (!hidden || typeof hidden !== 'object' || Array.isArray(hidden)) {
             return {
-                dotFiles: { default: 'hidden', whitelist: [], blacklist: [] },
+                dotFiles: { default: 'visible', whitelist: [], blacklist: [] },
                 dotDirs:  { default: 'visible', whitelist: [], blacklist: [] },
                 alwaysHide: []
             };
@@ -490,7 +790,7 @@ module.exports = function koaClassicServer(
         }
         return {
-            dotFiles: normalizeCategory(hidden.dotFiles, 'hidden', 'dotFiles'),
+            dotFiles: normalizeCategory(hidden.dotFiles, 'visible', 'dotFiles'),
             dotDirs:  normalizeCategory(hidden.dotDirs,  'visible', 'dotDirs'),
             alwaysHide: filterPatternList(hidden.alwaysHide),
         };
@@ -498,66 +798,53 @@ module.exports = function koaClassicServer(
     const hiddenConfig = normalizeHiddenConfig(options.hidden);
-    // One-time per-process warning when the caller relies on implicit defaults for
-    // hidden.dotFiles.default or hidden.dotDirs.default.  Since v3.0.0 dotFiles are
-    // hidden by default ('hidden') while dotDirs are visible by default ('visible').
-    // Explicitly declaring the values makes intent clear and silences the warning.
-    if (!_hiddenDefaultWarnEmitted) {
-        const dotFilesImplicit = opts.hidden?.dotFiles?.default === undefined;
-        const dotDirsImplicit  = opts.hidden?.dotDirs?.default  === undefined;
-        if (dotFilesImplicit || dotDirsImplicit) {
-            _hiddenDefaultWarnEmitted = true;
-            console.warn(
-                '\x1b[33m%s\x1b[0m',
-                '[koa-classic-server] WARNING: hidden.dotFiles.default and/or hidden.dotDirs.default are not explicitly set.\n' +
-                '  Since v3.0.0 the defaults are: dotFiles → "hidden", dotDirs → "visible".\n' +
-                '  To suppress this warning, add to your configuration:\n' +
-                '    hidden: { dotFiles: { default: \'hidden\' }, dotDirs: { default: \'visible\' } }\n' +
-                '  (adjust values to match your desired behaviour)'
-            );
-        }
-    }
-    // Returns true if `name` matches any pattern in the list.
-    // Patterns are matched against the bare filename (case-sensitive).
-    // Each entry can be a string (exact match or simple glob with * and ?) or a RegExp.
-    function matchesNameList(name, patterns) {
+    // Returns true if `value` matches any pattern in the list.
+    // RegExp patterns are tested directly; string patterns go through `globMatch`.
+    // Non-string non-RegExp entries are ignored (defensive — config validation should reject them).
+    function matchesPatternList(value, patterns, globMatch) {
         for (const pattern of patterns) {
             if (pattern instanceof RegExp) {
-                if (pattern.test(name)) return true;
+                if (pattern.test(value)) return true;
             } else if (typeof pattern === 'string') {
-                if (nameGlobMatch(name, pattern)) return true;
+                if (globMatch(value, pattern)) return true;
             }
         }
         return false;
     }
+    // Match against a list using filename-glob semantics (case-sensitive, no path component).
+    function matchesNameList(name, patterns) {
+        return matchesPatternList(name, patterns, nameGlobMatch);
+    }
+    // Compiled-RegExp caches for glob patterns. Patterns come from `hidden.*` config and are
+    // immutable after factory init, so memoization is bounded by the operator's config size
+    // and avoids recompiling the same regex on every directory entry during a listing.
+    const _nameGlobRegexCache = new Map();
+    const _pathGlobRegexCache = new Map();
     // Matches a bare filename against a simple glob pattern (* = any chars except /, ? = one char).
     function nameGlobMatch(name, pattern) {
         if (!pattern.includes('*') && !pattern.includes('?')) {
             return name === pattern;
         }
-        const regexStr = '^' +
-            pattern
-                .replace(/[.+^${}()|[\]\\]/g, '\\$&')
-                .replace(/\*/g, '[^/]*')
-                .replace(/\?/g, '[^/]')
-            + '$';
-        return new RegExp(regexStr).test(name);
+        let re = _nameGlobRegexCache.get(pattern);
+        if (re === undefined) {
+            const regexStr = '^' +
+                pattern
+                    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+                    .replace(/\*/g, '[^/]*')
+                    .replace(/\?/g, '[^/]')
+                + '$';
+            re = new RegExp(regexStr);
+            _nameGlobRegexCache.set(pattern, re);
+        }
+        return re.test(name);
     }
-    // Returns true if `relPath` matches any pattern in the list.
-    // Patterns are matched against the full relative path from rootDir (case-sensitive).
-    // Each entry can be a string glob or a RegExp.
+    // Match against a list using path-aware glob semantics (anchored to rootDir, supports **).
     function matchesPathList(relPath, patterns) {
-        for (const pattern of patterns) {
-            if (pattern instanceof RegExp) {
-                if (pattern.test(relPath)) return true;
-            } else if (typeof pattern === 'string') {
-                if (pathGlobMatch(relPath, pattern)) return true;
-            }
-        }
-        return false;
+        return matchesPatternList(relPath, patterns, pathGlobMatch);
     }
     /**
@@ -569,19 +856,24 @@ module.exports = function koaClassicServer(
      *   - '?'  matches any single character except '/'
      */
     function pathGlobMatch(relPath, pattern) {
-        const hasSlash = pattern.includes('/');
-        const escaped = pattern
-            .replace(/[.+^${}()|[\]\\]/g, '\\$&')
-            .replace(/\*\*/g, '\x00')
-            .replace(/\*/g, '[^/]*')
-            .replace(/\?/g, '[^/]')
-            .replace(/\x00/g, '.*');
-        const regexStr = hasSlash
-            ? '^' + escaped + '($|/)'    // path-anchored from root
-            : '(^|/)' + escaped + '$';   // basename match at any depth
-        return new RegExp(regexStr).test(relPath);
+        let re = _pathGlobRegexCache.get(pattern);
+        if (re === undefined) {
+            const hasSlash = pattern.includes('/');
+            const escaped = pattern
+                .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+                .replace(/\*\*/g, '\x00')
+                .replace(/\*/g, '[^/]*')
+                .replace(/\?/g, '[^/]')
+                .replace(/\x00/g, '.*');
+            const regexStr = hasSlash
+                ? '^' + escaped + '($|/)'    // path-anchored from root
+                : '(^|/)' + escaped + '$';   // basename match at any depth
+            re = new RegExp(regexStr);
+            _pathGlobRegexCache.set(pattern, re);
+        }
+        return re.test(relPath);
     }
     /**
@@ -657,11 +949,19 @@ module.exports = function koaClassicServer(
             return {
                 enabled: true,
                 encodings: ['br', 'gzip'],              // priority order: brotli first, gzip as fallback
-                minSize: 1024,                          // bytes; skip compression for files smaller than this
+                minFileSize: 1024,                      // bytes; skip compression for files smaller than this
                 mimeTypes: new Set(DEFAULT_COMPRESSIBLE_MIME_TYPES),
             };
         }
+        // V3 breaking-change guard: catch the v2-alpha name minSize with a helpful migration hint.
+        if (compression.minSize !== undefined) {
+            throw new Error(
+                '[koa-classic-server] options.compression.minSize was renamed in v3.0.0.\n' +
+                `  Replace with: compression: { minFileSize: ${compression.minSize} }`
+            );
+        }
         const enabled = typeof compression.enabled === 'boolean' ? compression.enabled : true;
         if (!enabled) return { enabled: false };
@@ -669,14 +969,14 @@ module.exports = function koaClassicServer(
             ? compression.encodings.filter(e => e === 'br' || e === 'gzip')
             : ['br', 'gzip'];
-        const minSize = compression.minSize === false ? false
-            : (typeof compression.minSize === 'number' && compression.minSize >= 0 ? compression.minSize : 1024);
+        const minFileSize = compression.minFileSize === false ? false
+            : (typeof compression.minFileSize === 'number' && compression.minFileSize >= 0 ? compression.minFileSize : 1024);
         const mimeTypes = Array.isArray(compression.mimeTypes) && compression.mimeTypes.length > 0
             ? compression.mimeTypes
             : DEFAULT_COMPRESSIBLE_MIME_TYPES;
-        return { enabled, encodings, minSize, mimeTypes: new Set(mimeTypes) };
+        return { enabled, encodings, minFileSize, mimeTypes: new Set(mimeTypes) };
     }
     // Normalize and validate the serverCache option into a clean internal structure.
@@ -685,14 +985,27 @@ module.exports = function koaClassicServer(
             enabled: false,
             maxSize: 52428800,      // 50 MB
             maxFileSize: 1048576,   // 1 MB
+            maxAge: 0,
             warnInterval: 60000,
         };
         const defaultCompressedFile = {
             enabled: true,
             maxSize: 104857600,     // 100 MB
+            maxAge: 0,
             warnInterval: 60000,
         };
+        function validateMaxAge(value, cacheName) {
+            if (value === undefined) return 0;
+            if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+                throw new Error(
+                    `[koa-classic-server] serverCache.${cacheName}.maxAge must be a finite number >= 0 (ms). ` +
+                    'Use 0 to disable. Got: ' + String(value)
+                );
+            }
+            return value;
+        }
         if (!serverCache || typeof serverCache !== 'object' || Array.isArray(serverCache)) {
             return { rawFile: defaultRawFile, compressedFile: defaultCompressedFile };
         }
@@ -702,6 +1015,7 @@ module.exports = function koaClassicServer(
             enabled: typeof rf.enabled === 'boolean' ? rf.enabled : false,
             maxSize: typeof rf.maxSize === 'number' && rf.maxSize > 0 ? rf.maxSize : 52428800,
             maxFileSize: typeof rf.maxFileSize === 'number' && rf.maxFileSize > 0 ? rf.maxFileSize : 1048576,
+            maxAge: validateMaxAge(rf.maxAge, 'rawFile'),
             warnInterval: rf.warnInterval === false ? false : (typeof rf.warnInterval === 'number' ? rf.warnInterval : 60000),
         };
@@ -709,6 +1023,7 @@ module.exports = function koaClassicServer(
         const compressedFile = (!cf || typeof cf !== 'object' || Array.isArray(cf)) ? defaultCompressedFile : {
             enabled: typeof cf.enabled === 'boolean' ? cf.enabled : true,
             maxSize: typeof cf.maxSize === 'number' && cf.maxSize > 0 ? cf.maxSize : 104857600,
+            maxAge: validateMaxAge(cf.maxAge, 'compressedFile'),
             warnInterval: cf.warnInterval === false ? false : (typeof cf.warnInterval === 'number' ? cf.warnInterval : 60000),
         };
@@ -723,7 +1038,8 @@ module.exports = function koaClassicServer(
     const _rawFileCache = new LFUCache(
         serverCacheConfig.rawFile.maxSize,
         serverCacheConfig.rawFile.warnInterval,
-        'rawFile'
+        'rawFile',
+        _logger
     );
     // In-memory LFU cache for compressed file buffers (serverCache.compressedFile).
@@ -731,7 +1047,8 @@ module.exports = function koaClassicServer(
     const _compressedFileCache = new LFUCache(
         serverCacheConfig.compressedFile.maxSize,
         serverCacheConfig.compressedFile.warnInterval,
-        'compressedFile'
+        'compressedFile',
+        _logger
     );
     // Returns the client's preferred encoding based on Accept-Encoding header,
@@ -745,23 +1062,14 @@ module.exports = function koaClassicServer(
     }
     // Compress a Buffer using the given encoding ('br' or 'gzip').
-    // Uses maximum quality — appropriate for serverCache mode (cost paid once).
+    // Quality is maxed out: serverCache pays this cost once per file, not per request.
     function compressBuffer(data, encoding) {
-        return new Promise((resolve, reject) => {
-            if (encoding === 'br') {
-                zlib.brotliCompress(
-                    data,
-                    { params: { [zlib.constants.BROTLI_PARAM_QUALITY]: 11 } },
-                    (err, result) => { if (err) reject(err); else resolve(result); }
-                );
-            } else {
-                zlib.gzip(
-                    data,
-                    { level: zlib.constants.Z_BEST_COMPRESSION },
-                    (err, result) => { if (err) reject(err); else resolve(result); }
-                );
-            }
-        });
+        if (encoding === 'br') {
+            return _brotliCompressAsync(data, {
+                params: { [zlib.constants.BROTLI_PARAM_QUALITY]: 11 }
+            });
+        }
+        return _gzipAsync(data, { level: zlib.constants.Z_BEST_COMPRESSION });
     }
     /**
@@ -816,7 +1124,7 @@ module.exports = function koaClassicServer(
                         );
                         fileNames = checkResults.filter(e => e.isFile).map(e => e.name);
                     } catch (error) {
-                        console.error('Error finding index file:', error);
+                        _logger.error('Error finding index file:', error);
                         return null;
                     }
                 }
@@ -909,7 +1217,9 @@ module.exports = function koaClassicServer(
             return;
         }
-        // Hidden check: block requests that traverse a hidden directory
+        // 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++) {
@@ -933,14 +1243,23 @@ module.exports = function koaClassicServer(
             const rawPath = urlToUse.split('?')[0];
             const hadTrailingSlash = rawPath.length > 1 && rawPath.endsWith('/');
-            // Check if URL ends with the configured extension → redirect to clean URL
-            // Use the original path (before trailing slash stripping) for accurate matching
+            // 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(/^[/\\]+/, '');
+                }
                 redirectPath = redirectPath.slice(0, redirectPath.length - hideExt.length);
                 // Special case: /index.ejs → /, /sezione/index.ejs → /sezione/
@@ -1007,7 +1326,7 @@ module.exports = function koaClassicServer(
         if (stat.isDirectory()) {
             // Handle directory
-            if (options.showDirContents) {
+            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);
@@ -1042,7 +1361,7 @@ module.exports = function koaClassicServer(
                 try {
                     fileStat = await fs.promises.stat(toOpen);
                 } catch (error) {
-                    console.error('File stat error:', error);
+                    _logger.error('File stat error:', error);
                     sendNotFound(ctx);
                     return;
                 }
@@ -1053,54 +1372,32 @@ module.exports = function koaClassicServer(
             let rawBuffer = null;
             if (serverCacheConfig.rawFile.enabled && fileStat.size <= serverCacheConfig.rawFile.maxFileSize) {
                 const cached = _rawFileCache.peek(toOpen);
-                if (cached && cached.mtime === fileStat.mtime.getTime() && cached.size === fileStat.size) {
+                const maxAge = serverCacheConfig.rawFile.maxAge;
+                const staleByAge = maxAge > 0 && cached && (Date.now() - cached.insertedAt) >= maxAge;
+                const fresh = cached
+                    && cached.mtime === fileStat.mtime.getTime()
+                    && cached.size === fileStat.size
+                    && !staleByAge;
+                if (fresh) {
                     _rawFileCache.get(toOpen); // increment frequency
                     rawBuffer = cached.buffer;
                 } else {
                     try {
                         rawBuffer = await fs.promises.readFile(toOpen);
-                        if (cached) _rawFileCache.delete(toOpen); // remove stale entry before re-inserting
-                        _rawFileCache.set(toOpen, {
+                        refreshOrInsert(_rawFileCache, toOpen, {
                             buffer: rawBuffer,
                             mtime: fileStat.mtime.getTime(),
                             size: fileStat.size,
-                        });
+                            insertedAt: Date.now(),
+                        }, cached, staleByAge);
                     } catch {
                         rawBuffer = null; // Fall through to disk reads later
                     }
                 }
             }
-            // Template rendering — rawBuffer passed as optional 4th param so render functions
-            // can skip their own fs.readFile() call when the file is already in memory.
-            if (options.template.ext.length > 0 && options.template.render) {
-                const fileExt = path.extname(toOpen).slice(1); // Remove leading dot
-                if (fileExt && options.template.ext.includes(fileExt)) {
-                    try {
-                        await options.template.render(ctx, next, toOpen, rawBuffer);
-                        return;
-                    } catch (error) {
-                        console.error('Template rendering error:', error);
-                        setGeneratedPageHeaders(ctx, NOT_FOUND_CSP);
-                        ctx.status = 500;
-                        ctx.body = `
-                            <!DOCTYPE html>
-                            <html>
-                            <head>
-                                <meta charset="UTF-8">
-                                <meta name="viewport" content="width=device-width, initial-scale=1.0">
-                                <title>Internal Server Error</title>
-                            </head>
-                            <body>
-                                <h1>Internal Server Error</h1>
-                                <h3>Template rendering failed for the requested resource.</h3>
-                            </body>
-                            </html>
-                        `;
-                        return;
-                    }
-                }
+            if (await tryRenderTemplate(ctx, next, toOpen, rawBuffer, options.template, _logger)) {
+                return;
             }
             // baseEtag — encoding-independent; used only for If-Range (Range requests skip compression)
@@ -1125,7 +1422,7 @@ module.exports = function koaClassicServer(
                 try {
                     await fs.promises.access(toOpen, fs.constants.R_OK);
                 } catch (error) {
-                    console.error('File access error:', error);
+                    _logger.error('File access error:', error);
                     sendNotFound(ctx);
                     return;
                 }
@@ -1166,7 +1463,7 @@ module.exports = function koaClassicServer(
                             } else {
                                 const src = fs.createReadStream(toOpen, { start, end });
                                 src.on('error', (err) => {
-                                    console.error('Stream error:', err);
+                                    _logger.error('Stream error:', err);
                                     if (!ctx.headerSent) {
                                         ctx.status = 500;
                                         ctx.body = 'Error reading file';
@@ -1191,12 +1488,12 @@ module.exports = function koaClassicServer(
             const mimeType = mime.lookup(toOpen) || 'application/octet-stream';
             const filename = path.basename(toOpen);
-            // Resolve compression: enabled + compressible MIME + meets minSize + client supports it
+            // 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.minSize === false
-                    || fileStat.size >= compressionConfig.minSize;
+                const meetsMinSize = compressionConfig.minFileSize === false
+                    || fileStat.size >= compressionConfig.minFileSize;
                 if (isCompressibleMime && meetsMinSize) {
                     encoding = getClientEncoding(ctx.get('Accept-Encoding'));
                 }
@@ -1243,9 +1540,12 @@ module.exports = function koaClassicServer(
                     // compressedFile cache mode: compress once → buffer in RAM → Content-Length known
                     const cacheKey = `${toOpen}:${encoding}`;
                     const cached = _compressedFileCache.peek(cacheKey);
+                    const maxAge = serverCacheConfig.compressedFile.maxAge;
+                    const staleByAge = maxAge > 0 && cached && (Date.now() - cached.insertedAt) >= maxAge;
                     const stale = !cached
                         || cached.mtime !== fileStat.mtime.getTime()
-                        || cached.size !== fileStat.size;
+                        || cached.size !== fileStat.size
+                        || staleByAge;
                     let buf;
                     if (!stale) {
@@ -1257,14 +1557,14 @@ module.exports = function koaClassicServer(
                             const rawData = rawBuffer || await fs.promises.readFile(toOpen);
                             buf = await compressBuffer(rawData, encoding);
-                            if (cached) _compressedFileCache.delete(cacheKey); // remove stale entry before re-inserting
-                            _compressedFileCache.set(cacheKey, {
+                            refreshOrInsert(_compressedFileCache, cacheKey, {
                                 buffer: buf,
                                 mtime: fileStat.mtime.getTime(),
                                 size: fileStat.size,
-                            });
+                                insertedAt: Date.now(),
+                            }, cached, staleByAge);
                         } catch (err) {
-                            console.error('Compression error:', err);
+                            _logger.error('Compression error:', err);
                             // Fall back to uncompressed on any compression failure
                             ctx.remove('Content-Encoding');
                             ctx.remove('Vary');
@@ -1281,7 +1581,7 @@ module.exports = function koaClassicServer(
                                 if (ctx.method !== 'HEAD') {
                                     const src = fs.createReadStream(toOpen);
                                     src.on('error', (streamErr) => {
-                                        console.error('Stream error:', streamErr);
+                                        _logger.error('Stream error:', streamErr);
                                         if (!ctx.headerSent) { ctx.status = 500; ctx.body = 'Error reading file'; }
                                     });
                                     ctx.body = src;
@@ -1316,7 +1616,7 @@ module.exports = function koaClassicServer(
                         } else {
                             const src = fs.createReadStream(toOpen);
                             src.on('error', (err) => {
-                                console.error('Stream error:', err);
+                                _logger.error('Stream error:', err);
                                 if (!ctx.headerSent) { ctx.status = 500; ctx.body = 'Error reading file'; }
                             });
                             ctx.body = src.pipe(compress);
@@ -1341,7 +1641,7 @@ module.exports = function koaClassicServer(
                     if (ctx.method !== 'HEAD') {
                         const src = fs.createReadStream(toOpen);
                         src.on('error', (err) => {
-                            console.error('Stream error:', err);
+                            _logger.error('Stream error:', err);
                             if (!ctx.headerSent) { ctx.status = 500; ctx.body = 'Error reading file'; }
                         });
                         ctx.body = src;
@@ -1356,11 +1656,23 @@ module.exports = function koaClassicServer(
         async function show_dir(toOpen, ctx) {
+            // Read the full directory in one syscall, then cap the result.
+            // `dirListing.maxEntries` bounds the visible / sorted / stat'd entries, but
+            // does NOT bound the size of the initial readdir() allocation — see the
+            // adversarial-directory caveat tracked for v3.1 [F-1].
+            const maxDirEntries = options.dirListing.maxEntries; // 0 = disabled (no cap)
             let dir;
+            let truncated = false;
             try {
-                dir = await fs.promises.readdir(toOpen, { withFileTypes: true });
+                const all = await fs.promises.readdir(toOpen, { withFileTypes: true });
+                if (maxDirEntries > 0 && all.length > maxDirEntries) {
+                    truncated = true;
+                    dir = all.slice(0, maxDirEntries);
+                } else {
+                    dir = all;
+                }
             } catch (error) {
-                console.error('Directory read error:', error);
+                _logger.error('Directory read error:', error);
                 ctx.status = 500;
                 setGeneratedPageHeaders(ctx, NOT_FOUND_CSP);
                 return `
@@ -1386,10 +1698,17 @@ module.exports = function koaClassicServer(
             const sortBy = ctx.query.sort || 'name';
             const sortOrder = ctx.query.order || 'asc';
-            // Build base URL for sorting links (without query params)
             const baseUrl = pageHrefOutPrefix.pathname;
-            // Helper to create sorting URL
+            // Preserves sort/order while overriding `page`; omits page when 0.
+            function buildQueryUrl(targetPage) {
+                const params = [];
+                if (ctx.query.sort)  params.push(`sort=${encodeURIComponent(ctx.query.sort)}`);
+                if (ctx.query.order) params.push(`order=${encodeURIComponent(ctx.query.order)}`);
+                if (targetPage > 0)  params.push(`page=${targetPage}`);
+                return params.length ? `${baseUrl}?${params.join('&')}` : baseUrl;
+            }
             function getSortUrl(column) {
                 let newOrder = 'asc';
                 if (sortBy === column && sortOrder === 'asc') {
@@ -1398,7 +1717,6 @@ module.exports = function koaClassicServer(
                 return `${baseUrl}?sort=${column}&order=${newOrder}`;
             }
-            // Helper to get sort indicator
             function getSortIndicator(column) {
                 if (sortBy === column) {
                     return sortOrder === 'asc' ? ' ↑' : ' ↓';
@@ -1407,6 +1725,12 @@ module.exports = function koaClassicServer(
             }
             const parts = [];
+            let totalPages = 1;     // populated in the non-empty branch below
+            let currentPage = 0;
+            if (truncated) {
+                parts.push(`<div class="kcs-banner">⚠ Showing first ${maxDirEntries} entries (cap reached). More files exist but are not listed. Adjust <code>dirListing.maxEntries</code> to see more.</div>`);
+                ctx.set('X-Dir-Truncated', `${maxDirEntries}`);
+            }
             parts.push("<table>");
             parts.push("<thead>");
             parts.push("<tr>");
@@ -1514,37 +1838,45 @@ module.exports = function koaClassicServer(
                 }
                 const items = rawItems.filter(Boolean);
-                // Sort items based on query parameters
+                // 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.
+                const compareDirsFirst = (a, b, tieBreaker) => {
+                    const aIsDir = a.effectiveType === 2;
+                    const bIsDir = b.effectiveType === 2;
+                    if (aIsDir !== bIsDir) return aIsDir ? -1 : 1;
+                    return tieBreaker(a, b);
+                };
                 items.sort((a, b) => {
                     let comparison = 0;
                     if (sortBy === 'name') {
                         comparison = a.name.localeCompare(b.name);
                     } else if (sortBy === 'type') {
-                        // Sort directories first, then by mime type (using effectiveType for symlinks)
-                        if (a.effectiveType === 2 && b.effectiveType !== 2) {
-                            comparison = -1;
-                        } else if (a.effectiveType !== 2 && b.effectiveType === 2) {
-                            comparison = 1;
-                        } else {
-                            comparison = a.mimeType.localeCompare(b.mimeType);
-                        }
+                        comparison = compareDirsFirst(a, b, (x, y) => x.mimeType.localeCompare(y.mimeType));
                     } else if (sortBy === 'size') {
-                        // Directories always at top when sorting by size (using effectiveType for symlinks)
-                        if (a.effectiveType === 2 && b.effectiveType !== 2) {
-                            comparison = -1;
-                        } else if (a.effectiveType !== 2 && b.effectiveType === 2) {
-                            comparison = 1;
-                        } else {
-                            comparison = a.sizeBytes - b.sizeBytes;
-                        }
+                        comparison = compareDirsFirst(a, b, (x, y) => x.sizeBytes - y.sizeBytes);
                     }
                     return sortOrder === 'desc' ? -comparison : comparison;
                 });
+                // Pagination — slice the sorted items into the requested page (0-based).
+                const pageSize = options.dirListing.entriesPerPage; // 0 disables pagination
+                totalPages = pageSize > 0 ? Math.max(1, Math.ceil(items.length / pageSize)) : 1;
+                const rawPage = parseInt(ctx.query.page, 10);
+                const requestedPage = Number.isFinite(rawPage) && rawPage >= 0 ? rawPage : 0;
+                currentPage = Math.min(requestedPage, totalPages - 1); // silent clamp
+                const visibleItems = (pageSize > 0 && items.length > pageSize)
+                    ? items.slice(currentPage * pageSize, (currentPage + 1) * pageSize)
+                    : items;
+                if (totalPages > 1) {
+                    ctx.set('X-Dir-Pagination', `${currentPage}/${totalPages - 1}`);
+                }
                 // Generate HTML for sorted items
-                for (const item of items) {
+                for (const item of visibleItems) {
                     let rowStart = '';
                     if (item.effectiveType === 1) {
                         rowStart = `<tr><td> FILE `;
@@ -1573,6 +1905,47 @@ module.exports = function koaClassicServer(
             parts.push("</tbody>");
             parts.push("</table>");
+            // Numbered paginator with First/Prev/Next/Last and ellipsis around the current page.
+            // Only emitted when pagination is meaningful (computed above; reuses currentPage/totalPages).
+            if (totalPages > 1) {
+                const pageWindow = 2;
+                const pagesToShow = new Set([0, totalPages - 1]);
+                for (let i = Math.max(0, currentPage - pageWindow); i <= Math.min(totalPages - 1, currentPage + pageWindow); i++) {
+                    pagesToShow.add(i);
+                }
+                const sortedPages = [...pagesToShow].sort((a, b) => a - b);
+                const pager = ['<nav class="kcs-pagination" aria-label="Pagination">'];
+                if (currentPage > 0) {
+                    pager.push(`<a href="${escapeHtml(buildQueryUrl(0))}">« First</a>`);
+                    pager.push(`<a href="${escapeHtml(buildQueryUrl(currentPage - 1))}">‹ Prev</a>`);
+                } else {
+                    pager.push(`<span class="kcs-page-disabled">« First</span>`);
+                    pager.push(`<span class="kcs-page-disabled">‹ Prev</span>`);
+                }
+                let prev = -1;
+                for (const p of sortedPages) {
+                    if (prev !== -1 && p - prev > 1) {
+                        pager.push(`<span class="kcs-page-ellipsis">…</span>`);
+                    }
+                    if (p === currentPage) {
+                        pager.push(`<span class="kcs-page-current">${p}</span>`);
+                    } else {
+                        pager.push(`<a href="${escapeHtml(buildQueryUrl(p))}">${p}</a>`);
+                    }
+                    prev = p;
+                }
+                if (currentPage < totalPages - 1) {
+                    pager.push(`<a href="${escapeHtml(buildQueryUrl(currentPage + 1))}">Next ›</a>`);
+                    pager.push(`<a href="${escapeHtml(buildQueryUrl(totalPages - 1))}">Last »</a>`);
+                } else {
+                    pager.push(`<span class="kcs-page-disabled">Next ›</span>`);
+                    pager.push(`<span class="kcs-page-disabled">Last »</span>`);
+                }
+                pager.push('</nav>');
+                parts.push(pager.join(''));
+            }
             const tableHtml = parts.join('');
             const html = `