expediate 0.0.3 → 1.0.0

package/dist/static.js

@@ -0,0 +1,703 @@
+/* Copyright 2021 Fabien Bavent
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a
+ * copy of this software and associated documentation files (the "Software"),
+ * to deal in the Software without restriction, including without limitation
+ * the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ * and/or sell copies of the Software, and to permit persons to whom the
+ * Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included
+ * in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+ * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ * DEALINGS IN THE SOFTWARE.
+ */
+'use strict';
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mime = void 0;
+exports.sendFile = sendFile;
+exports.serveStatic = serveStatic;
+exports.serveFile = serveFile;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const mime_types = new Map();
+const mime_extensions = new Map();
+function mime_define(map) {
+    for (var type in map) {
+        var exts = map[type];
+        for (var i = 0; i < exts.length; i++)
+            mime_types.set(exts[i], type);
+        if (!mime_extensions.has(type))
+            mime_extensions.set(type, exts[0]);
+    }
+}
+;
+exports.mime = {
+    lookup: (path, fallback = null) => mime_types.get(path.replace(/^.*[\.\/\\]/, '').toLowerCase()) ?? fallback ?? 'application/octet-stream',
+    charsets: (mimeType) => (/^text\/|^application\/(javascript|json)/).test(mimeType) ? 'UTF-8' : null,
+};
+mime_define(require('./mimetypes.json'));
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/**
+ * Regular expression that detects a directory-traversal component (`..`) in
+ * any position of a URL path, including encoded forms using back-slashes.
+ */
+const UP_PATH_REGEXP = /(?:^|[\\/])\.\.(?:[\\/]|$)/;
+/** Default security and caching options applied to every response. */
+const DEFAULT_OPTIONS = {
+    headers: {
+        'Content-Security-Policy': "default-src 'none'",
+        'X-Content-Type-Options': 'nosniff',
+    },
+    fallthrough: false,
+    maxage: 0,
+    immutable: false,
+    etag: true,
+    lastModified: true,
+    contentType: null,
+    dotfiles: 'hide',
+    redirect: true,
+    indexOf: false,
+};
+// ---------------------------------------------------------------------------
+// HTTP response helpers
+// ---------------------------------------------------------------------------
+/**
+ * Collection of pre-built HTTP error/success response helpers.
+ * Each helper sets the appropriate status code, merges the caller's custom
+ * headers, and terminates the response.
+ */
+const HTTP = {
+    /** 304 Not Modified — sent for conditional GET cache hits. */
+    NOT_MODIFIED: (res, opts) => { res.status(304, opts.headers).end(); },
+    /** 403 Forbidden — sent for denied dot-files or path traversal attempts. */
+    FORBIDDEN: (res, opts) => res.status(403, opts.headers).send('Forbidden'),
+    /** 404 Not Found — sent when the requested file does not exist. */
+    NOT_FOUND: (res, opts) => res.status(404, opts.headers).send('Not Found'),
+    /**
+     * 405 Method Not Allowed — sent when the HTTP method is neither GET nor
+     * HEAD and {@link ResolvedOptions.fallthrough} is `false`.
+     * Always includes an `Allow: GET, HEAD` header per RFC 7231 §6.5.5.
+     */
+    NOT_ALLOWED: (res, opts) => { res.status(405, { ...opts.headers, Allow: 'GET, HEAD' }).end(); },
+    /** 412 Precondition Failed — sent when `If-Match` / `If-Unmodified-Since` fails. */
+    PRECONDITION_FAILS: (res, opts) => res.status(412, opts.headers).send('Precondition Failed'),
+    /** 500 Internal Server Error — sent on unexpected filesystem or stream errors. */
+    INTERNAL_ERROR: (res, opts, err) => res.status(500, opts.headers).send(`Internal error: ${err}`),
+};
+// ---------------------------------------------------------------------------
+// Internal utilities
+// ---------------------------------------------------------------------------
+/**
+ * Safely destroy a `fs.ReadStream`, working around a Node.js core bug where
+ * streams that have not yet emitted `'open'` do not close their file
+ * descriptor when `destroy()` is called.
+ *
+ * @param stream - The readable stream to destroy.
+ */
+function destroyReadStream(stream) {
+    stream.destroy();
+    if (typeof stream.close === 'function') {
+        // Node.js core bug work-around: if the stream has not yet opened the file,
+        // `destroy()` will not close the fd. Listening for 'open' ensures we close
+        // it as soon as the fd becomes available.
+        stream.on('open', () => {
+            if (typeof stream.fd === 'number')
+                stream.close();
+        });
+    }
+}
+/**
+ * Remove all `Content-*` headers from the response, **except**
+ * `Content-Location`.
+ *
+ * Called before sending a 304 Not Modified response, as RFC 7232 §4.1
+ * requires that the response body and most content metadata headers be
+ * omitted in that case.
+ *
+ * @param res - The server response whose headers will be mutated.
+ */
+function removeContentHeaders(res) {
+    const keys = Object.keys(res.getHeaders() ?? {});
+    for (const key of keys) {
+        if (key.startsWith('content-') && key !== 'content-location')
+            res.removeHeader(key);
+    }
+}
+/**
+ * Build a weak ETag string from a file's `stat` metadata.
+ *
+ * The format is `W/"<size_hex>-<mtime_hex>"`, matching the convention used by
+ * Node's `serve-static` and compatible with all major HTTP clients.
+ *
+ * @param stat - The `fs.Stats` object for the file.
+ * @returns A weak ETag string.
+ */
+function createETag(stat) {
+    const mtime = stat.mtime.getTime().toString(16);
+    const size = stat.size.toString(16);
+    return `W/"${size}-${mtime}"`;
+}
+/**
+ * Parse a comma-separated HTTP token list (e.g. the value of an `ETag` or
+ * `Accept` header) into an array of trimmed token strings.
+ *
+ * Follows the token-list grammar from RFC 7230 §3.2.6: tokens are separated
+ * by commas, leading/trailing spaces around each token are ignored.
+ *
+ * @param str - The raw header value string.
+ * @returns An array of individual token strings (may be empty).
+ */
+function parseTokenList(str) {
+    const list = [];
+    let start = 0;
+    let end = 0;
+    for (let i = 0, len = str.length; i < len; i++) {
+        const ch = str.charCodeAt(i);
+        if (ch === 0x20 /* space */) {
+            if (start === end)
+                start = end = i + 1;
+        }
+        else if (ch === 0x2c /* comma */) {
+            list.push(str.substring(start, end));
+            start = end = i + 1;
+        }
+        else {
+            end = i + 1;
+        }
+    }
+    // Push the final token (there is always at least one).
+    list.push(str.substring(start, end));
+    return list;
+}
+/**
+ * Parse an HTTP-date string (e.g. `Thu, 01 Jan 1970 00:00:00 GMT`) into a
+ * Unix timestamp in milliseconds.
+ *
+ * @param date - The raw date string from an HTTP header.
+ * @returns A numeric timestamp, or `NaN` if parsing fails.
+ */
+function parseHttpDate(date) {
+    const timestamp = date ? Date.parse(date) : NaN;
+    return typeof timestamp === 'number' ? timestamp : NaN;
+}
+/**
+ * Return `true` when the request carries at least one conditional header
+ * (`If-Match`, `If-Unmodified-Since`, `If-None-Match`, or
+ * `If-Modified-Since`).
+ *
+ * @param headers - The incoming request's header map.
+ */
+function hasCondition(headers) {
+    return !!(headers['if-match'] ||
+        headers['if-unmodified-since'] ||
+        headers['if-none-match'] ||
+        headers['if-modified-since']);
+}
+/**
+ * Evaluate precondition headers (`If-Match` / `If-Unmodified-Since`) against
+ * the current response headers and return whether the precondition is
+ * satisfied.
+ *
+ * Used to decide whether to proceed with the response (`true`) or send
+ * 412 Precondition Failed (`false`).
+ *
+ * Implements the subset defined in RFC 7232 §6 (step 3 and step 5):
+ * - **`If-Match`** — matches when the response ETag equals the request ETag,
+ *   or when the request value is `*`.
+ * - **`If-Unmodified-Since`** — matches when the file has not been modified
+ *   since the given date.
+ *
+ * @param reqHeaders - Normalised (lowercase) request headers.
+ * @param resHeaders - Current response headers (as returned by
+ *                     `res.getHeaders()`).
+ * @returns `true` if the precondition is satisfied.
+ */
+function conditionMatch(reqHeaders, resHeaders) {
+    // --- If-Match ---
+    const match = reqHeaders['if-match'];
+    if (match) {
+        const etag = resHeaders['etag'];
+        if (match === '*' || match === etag)
+            return true;
+        for (const tag of parseTokenList(match)) {
+            if (tag === etag || `W/${tag}` === etag || tag === `W/${etag}`)
+                return true;
+        }
+        // If-Match was present but none of the tags matched → precondition failed.
+        return false;
+    }
+    // --- If-Unmodified-Since ---
+    // BUG FIX: the original code read req['if-modified-since'] here, which is
+    // the wrong header. The correct header for this precondition is
+    // 'if-unmodified-since'.
+    const lastModified = parseHttpDate(resHeaders['last-modified']);
+    const unmodifiedSince = parseHttpDate(reqHeaders['if-unmodified-since']);
+    if (!isNaN(unmodifiedSince) && !isNaN(lastModified))
+        return lastModified <= unmodifiedSince;
+    return false;
+}
+/**
+ * Determine whether a cached response is still fresh by evaluating the
+ * `If-None-Match` and `If-Modified-Since` conditional headers.
+ *
+ * Returns `true` only when the response can safely be replaced by a
+ * 304 Not Modified. Returns `false` (stale) when:
+ * - No conditional header is present (unconditional request).
+ * - `Cache-Control: no-cache` is set.
+ * - The ETag or modification time no longer matches.
+ *
+ * Implements RFC 7232 §6 (steps 4 and 5) and RFC 7234 §5.2.
+ *
+ * @param reqHeaders - Normalised (lowercase) request headers.
+ * @param resHeaders - Current response headers.
+ * @returns `true` if the cached response is fresh and a 304 should be sent.
+ */
+function isCacheFresh(reqHeaders, resHeaders) {
+    const CACHE_CONTROL_NO_CACHE_REGEXP = /(?:^|,)\s*?no-cache\s*?(?:,|$)/;
+    const modifiedSince = reqHeaders['if-modified-since'];
+    const noneMatch = reqHeaders['if-none-match'];
+    // Unconditional request — always treat as stale.
+    if (!modifiedSince && !noneMatch)
+        return false;
+    // Explicit no-cache directive forces revalidation even if ETags match.
+    const cacheControl = reqHeaders['cache-control'];
+    if (cacheControl && CACHE_CONTROL_NO_CACHE_REGEXP.test(cacheControl))
+        return false;
+    // --- If-None-Match ---
+    if (noneMatch && noneMatch !== '*') {
+        const etag = resHeaders['etag'];
+        if (!etag)
+            return false;
+        let etagStale = true;
+        for (const match of parseTokenList(noneMatch)) {
+            if (match === etag || `W/${match}` === etag || match === `W/${etag}`) {
+                etagStale = false;
+                break;
+            }
+        }
+        if (etagStale)
+            return false;
+    }
+    // --- If-Modified-Since ---
+    if (modifiedSince) {
+        const lastModified = resHeaders['last-modified'];
+        if (!lastModified)
+            return false;
+        if (!(parseHttpDate(lastModified) <= parseHttpDate(modifiedSince)))
+            return false;
+    }
+    return true;
+}
+// ---------------------------------------------------------------------------
+// Options resolution
+// ---------------------------------------------------------------------------
+/**
+ * Validate and resolve the `root` path and caller-supplied `options` into a
+ * fully populated {@link ResolvedOptions} object.
+ *
+ * Applies the following normalisation steps:
+ * - `root` is resolved to an absolute path via `path.resolve()`.
+ * - `fallthrough` and `redirect` default to `false` only when explicitly set
+ *   to `false`; any other value (including `undefined`) is treated as `true`.
+ * - `maxage` falls back to `maxAge` (camelCase alias) and then to `0`.
+ *
+ * @param root    - The root directory or file path to serve from.
+ * @param options - Caller-supplied options (partial, merged with defaults).
+ * @returns A fully resolved options object.
+ * @throws {TypeError} When `root` is falsy or not a string.
+ */
+function resolveOptions(root, options) {
+    if (!root)
+        throw new TypeError('root path required');
+    if (typeof root !== 'string')
+        throw new TypeError('root path must be a string');
+    // Deep-merge headers so caller-supplied headers *extend* the defaults
+    // rather than replacing them entirely.
+    const mergedHeaders = { ...DEFAULT_OPTIONS.headers, ...(options?.headers ?? {}) };
+    const opts = { ...DEFAULT_OPTIONS, ...options, headers: mergedHeaders };
+    opts.fallthrough = options?.fallthrough !== false;
+    opts.redirect = options?.redirect !== false;
+    opts.maxage = options?.maxage ?? options?.maxAge ?? 0;
+    opts.root = path_1.default.resolve(root);
+    return opts;
+}
+/**
+ * Asynchronously render an Apache-style directory-listing HTML page for the
+ * given directory and invoke `callback` with the result.
+ *
+ * The generated page lists every entry in `directoryPath`, with icons, names,
+ * last-modification timestamps, and file sizes. An optional parent-directory
+ * link is shown when `parentUrlPath` is provided.
+ *
+ * > **TODO** — Implement column sorting via `?C=N`, `?C=M`, `?C=S`, `?C=D`
+ * > (name / modified / size / description) combined with `?O=A` / `?O=D`
+ * > (ascending / descending). The current implementation always sorts by name
+ * > ascending.
+ *
+ * @param urlPath       - The URL path displayed in the page title and heading.
+ * @param directoryPath - Absolute filesystem path of the directory to list.
+ * @param parentUrlPath - URL of the parent directory, or `null` when at root.
+ * @param callback      - Called with `(html, null)` on success or
+ *                        `(null, err)` on failure.
+ */
+function writeIndexOf(urlPath, directoryPath, parentUrlPath, callback) {
+    // BUG FIX: the original signature had a `queries` parameter as first arg and
+    // a `path` parameter (shadowing the `path` module) as second. Both were
+    // unused or misused. The signature is corrected here: `urlPath` is the
+    // display path, `directoryPath` is the fs path, `parentUrlPath` is optional.
+    fs_1.default.readdir(directoryPath, (err, files) => {
+        if (err)
+            return callback(null, err);
+        let html = '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">\n';
+        html += '<html>\n';
+        html += `<head><title>Index of ${urlPath}</title></head>\n`;
+        html += `<body><h1>Index of ${urlPath}</h1><table>\n`;
+        html += '<tr>'
+            + '<th valign="top"><img src="/icons/blank.gif" alt="[ICO]"></th>'
+            + '<th><a href="?C=N;O=D">Name</a></th>'
+            + '<th><a href="?C=M;O=A">Last modified</a></th>'
+            + '<th><a href="?C=S;O=A">Size</a></th>'
+            + '<th><a href="?C=D;O=A">Description</a></th>'
+            + '</tr>\n';
+        html += '<tr><th colspan="5"><hr></th></tr>\n';
+        if (parentUrlPath)
+            html += `<tr>`
+                + `<td valign="top"><img src="/icons/back.gif" alt="[PARENTDIR]"></td>`
+                + `<td><a href="${parentUrlPath}">Parent Directory</a></td>`
+                + `<td>&nbsp;</td><td align="right">  - </td><td>&nbsp;</td>`
+                + `</tr>\n`;
+        for (const file of files) {
+            // BUG FIX: the original code passed `pathname` (undefined in this scope)
+            // to mime.lookup(). The correct argument is the full path of the entry.
+            // BUG FIX: the original code used `path.join(...)` where `path` was
+            // shadowed by the parameter name. Use `nodePath` (the imported module).
+            const fullPath = path_1.default.join(directoryPath, file);
+            let stat;
+            try {
+                stat = fs_1.default.statSync(fullPath);
+            }
+            catch {
+                continue; // skip entries that disappeared between readdir and stat
+            }
+            const mimeType = exports.mime.lookup(fullPath, '');
+            const mediaType = mimeType.includes('/') ? mimeType.split('/')[0] : '';
+            const alt = stat.isDirectory() ? 'folder' : (mediaType || 'unknown');
+            const icon = `/icons/${alt}.gif`;
+            const name = file + (stat.isDirectory() ? '/' : '');
+            // BUG FIX: `stat.modified` does not exist on `fs.Stats`.
+            // The correct property is `stat.mtime`.
+            const modified = stat.mtime.toUTCString();
+            const size = stat.isDirectory() ? '-' : String(stat.size);
+            html += `<tr>`
+                + `<td valign="top"><img src="${icon}" alt="[${alt.toUpperCase()}]"></td>`
+                + `<td><a href="${name}">${name}</a></td>` // BUG FIX: link text was empty in original
+                + `<td align="right">${modified}</td>`
+                + `<td align="right">${size}</td>`
+                + `<td>&nbsp;</td>`
+                + `</tr>\n`;
+        }
+        html += '<tr><th colspan="5"><hr></th></tr>\n';
+        html += '</table><address>Expediate/1.0.0</address></body></html>\n';
+        // BUG FIX: the original code called go(html) without `return`, so execution
+        // continued to HTTP.NOT_FOUND immediately after — the callback was invoked
+        // and then the caller would also receive NOT_FOUND.
+        return callback(html, null);
+    });
+}
+// ---------------------------------------------------------------------------
+// Core send logic
+// ---------------------------------------------------------------------------
+/**
+ * Set response headers and stream a file to the client.
+ *
+ * This is the inner send function shared by {@link sendFile} and the
+ * {@link serveStatic} middleware. It handles:
+ * - Custom and security headers from `opts`.
+ * - `Cache-Control` with optional `immutable` directive.
+ * - `Last-Modified` and `ETag` generation.
+ * - MIME-type detection via the `mime` package.
+ * - Conditional GET evaluation (`If-None-Match`, `If-Modified-Since`).
+ * - `HEAD` requests (headers sent, no body).
+ * - Streaming the file body with proper error handling and stream cleanup.
+ *
+ * @param req      - The incoming router request.
+ * @param res      - The outgoing router response.
+ * @param pathname - Absolute filesystem path of the file to send.
+ * @param stat     - Pre-fetched `fs.Stats` for `pathname`.
+ * @param opts     - Fully resolved static-serving options.
+ */
+function sendIt(req, res, pathname, stat, opts) {
+    const len = stat.size;
+    const etag = createETag(stat);
+    // Apply caller-supplied headers first so they can be overridden by the
+    // cache/content headers below if necessary.
+    if (opts.headers) {
+        for (const [key, value] of Object.entries(opts.headers))
+            res.setHeader(key, value);
+    }
+    // Cache-Control
+    if (!res.getHeader('Cache-Control') && opts.maxage) {
+        let cacheControl = `public, max-age=${Math.floor(opts.maxage / 1000)}`;
+        if (opts.immutable)
+            cacheControl += ', immutable';
+        res.setHeader('Cache-Control', cacheControl);
+    }
+    // Last-Modified
+    if (!res.getHeader('Last-Modified') && opts.lastModified !== false)
+        res.setHeader('Last-Modified', stat.mtime.toUTCString());
+    // ETag
+    if (!res.getHeader('ETag') && opts.etag !== false)
+        res.setHeader('ETag', etag);
+    // Content-Type
+    if (!res.getHeader('Content-Type')) {
+        if (opts.contentType) {
+            res.setHeader('Content-Type', opts.contentType);
+        }
+        else {
+            const type = exports.mime.lookup(pathname, '');
+            if (type) {
+                const charset = exports.mime.charsets(type);
+                res.setHeader('Content-Type', charset ? `${type}; charset=${charset}` : type);
+            }
+        }
+    }
+    // Conditional GET — two independent RFC 7232 mechanisms evaluated in order.
+    // 1. Cache-validation headers (If-None-Match / If-Modified-Since).
+    //    When the cached response is still fresh, respond with 304 Not Modified.
+    //    This must be tested BEFORE the precondition headers so that a browser
+    //    performing a normal ETag revalidation is not incorrectly rejected.
+    if (isCacheFresh(req.headers, res.getHeaders())) {
+        removeContentHeaders(res);
+        HTTP.NOT_MODIFIED(res, opts);
+        return;
+    }
+    // 2. Precondition headers (If-Match / If-Unmodified-Since).
+    //    Only evaluate when these specific headers are present; If-None-Match and
+    //    If-Modified-Since are handled above by isCacheFresh and must NOT trigger
+    //    a 412 when conditionMatch returns false (they are cache-validation headers,
+    //    not write-precondition headers per RFC 7232).
+    const hasPrecondition = !!(req.headers['if-match'] ||
+        req.headers['if-unmodified-since']);
+    if (hasPrecondition && !conditionMatch(req.headers, res.getHeaders())) {
+        HTTP.PRECONDITION_FAILS(res, opts);
+        return;
+    }
+    // --- Send the body ---
+    res.setHeader('Content-Length', len);
+    // HEAD requests: headers only, no body.
+    if (req.method === 'HEAD') {
+        res.end();
+        return;
+    }
+    let finished = false;
+    const stream = fs_1.default.createReadStream(pathname);
+    res.on('finish', () => {
+        finished = true;
+        destroyReadStream(stream);
+    });
+    stream.on('error', (err) => {
+        if (finished)
+            return;
+        console.warn('static stream error:', pathname, err);
+        HTTP.INTERNAL_ERROR(res, opts, err.code ?? 'UNKNOWN');
+        finished = true;
+        destroyReadStream(stream);
+    });
+    stream.on('end', () => res.end());
+    stream.pipe(res);
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Send a single file from the filesystem as an HTTP response.
+ *
+ * Unlike the {@link serveStatic} middleware, this function resolves the
+ * response for a **specific** `pathname` that has already been determined by
+ * the caller. It is useful for custom routing logic where the file path is
+ * computed dynamically.
+ *
+ * Behaviour:
+ * - When `pathname` refers to a **regular file**, it is served via
+ *   {@link sendIt} (including ETag, Last-Modified, conditional GET, and
+ *   MIME-type detection).
+ * - When `pathname` refers to a **directory** and `opts.indexOf` is `true`,
+ *   an Apache-style directory listing is rendered.
+ * - Otherwise, a 404 Not Found response is sent.
+ *
+ * @param req      - The incoming router request.
+ * @param res      - The outgoing router response.
+ * @param pathname - Absolute filesystem path of the file to send.
+ * @param opts     - Fully resolved static-serving options.
+ */
+function sendFile(req, res, pathname, opts) {
+    fs_1.default.stat(pathname, (err, stat) => {
+        if (err) {
+            if (err.code === 'ENOENT' ||
+                err.code === 'ENAMETOOLONG' ||
+                err.code === 'ENOTDIR')
+                return HTTP.NOT_FOUND(res, opts);
+            return HTTP.INTERNAL_ERROR(res, opts, err.code ?? 'UNKNOWN');
+        }
+        if (stat.isDirectory()) {
+            if (opts.indexOf) {
+                const parentUrl = req.path !== '/' ? path_1.default.dirname(req.path) : null;
+                return writeIndexOf(req.path, pathname, parentUrl, (html, indexErr) => {
+                    if (indexErr)
+                        return HTTP.INTERNAL_ERROR(res, opts, indexErr.code ?? 'UNKNOWN');
+                    // BUG FIX: the original code called `res.send(200, {...}).send(html)`.
+                    // `res.send()` does not accept a status code as first argument; the
+                    // correct call is `res.status(200, headers).send(html)`.
+                    return res.status(200, opts.headers).send(html);
+                });
+            }
+            // Directory listing is disabled — treat as not found.
+            return HTTP.NOT_FOUND(res, opts);
+        }
+        sendIt(req, res, pathname, stat, opts);
+    });
+}
+/**
+ * Middleware factory that serves files from a directory on the filesystem.
+ *
+ * Mount this middleware with a path prefix to expose a public directory:
+ * ```ts
+ * app.use('/public', serveStatic('./dist'));
+ * ```
+ *
+ * Features:
+ * - **Method filtering** — only `GET` and `HEAD` are served; other methods
+ *   receive 405 Method Not Allowed (or are forwarded to `next()` when
+ *   `fallthrough` is `true`).
+ * - **Directory traversal protection** — any path containing `..` is
+ *   rejected with 403 Forbidden.
+ * - **Dot-file handling** — configurable via the `dotfiles` option
+ *   (`'allow'`, `'deny'`, or `'hide'`).
+ * - **Directory redirect** — a path resolving to a directory is automatically
+ *   redirected to its `index.html` when `redirect` is `true`.
+ * - **Conditional GET** — ETag and Last-Modified headers enable browser and
+ *   proxy caching with proper revalidation.
+ * - **Cache-Control** — configurable via `maxage` / `immutable` options.
+ * - **MIME-type detection** — via the `mime` npm package.
+ *
+ * @param root    - Path to the directory containing the files to serve.
+ *                  Resolved to an absolute path internally.
+ * @param options - Optional configuration (see {@link StaticOptions}).
+ * @returns An Express-compatible middleware function.
+ * @throws {TypeError} When `root` is missing or not a string.
+ */
+function serveStatic(root, options) {
+    // BUG FIX: `static` is a reserved word in strict mode (`'use strict'`).
+    // The function has been renamed to `serveStatic`.
+    const opts = resolveOptions(root, options);
+    return function (req, res, next) {
+        if (req.method !== 'GET' && req.method !== 'HEAD') {
+            if (opts.fallthrough)
+                return next();
+            return HTTP.NOT_ALLOWED(res, opts);
+        }
+        // Decode the current path (after any prefix stripping by parent routers).
+        const originalUrl = decodeURIComponent(req.path ?? req.url ?? '/');
+        let pathname = originalUrl;
+        // When the URL ends without a trailing slash but the bare mount point was
+        // requested, clear the pathname so the root directory is considered.
+        if (pathname === '/' && !originalUrl.endsWith('/'))
+            pathname = '';
+        // Reject any path containing a directory-traversal component.
+        if (UP_PATH_REGEXP.test(pathname))
+            return HTTP.FORBIDDEN(res, opts);
+        // Resolve to an absolute filesystem path.
+        pathname = path_1.default.resolve(path_1.default.normalize(`${opts.root}/${pathname}`));
+        // Dot-file handling.
+        // BUG FIX: the original condition was `!opts.dotfiles != 'allow'` which
+        // always evaluates to `true` because `!opts.dotfiles` is a boolean and a
+        // boolean is never strictly/loosely equal to a string. The correct
+        // condition is `opts.dotfiles !== 'allow'`.
+        if (opts.dotfiles !== 'allow' && pathname.includes('/.')) {
+            if (opts.dotfiles === 'deny')
+                return HTTP.FORBIDDEN(res, opts);
+            return HTTP.NOT_FOUND(res, opts);
+        }
+        fs_1.default.stat(pathname, (err, stat) => {
+            if (err) {
+                if (err.code === 'ENOENT' ||
+                    err.code === 'ENAMETOOLONG' ||
+                    err.code === 'ENOTDIR') {
+                    if (opts.fallthrough)
+                        return next();
+                    return HTTP.NOT_FOUND(res, opts);
+                }
+                return HTTP.INTERNAL_ERROR(res, opts, err.code ?? 'UNKNOWN');
+            }
+            // When the resolved path is a directory, redirect to its index.html.
+            if (stat.isDirectory()) {
+                if (!opts.redirect)
+                    return HTTP.NOT_FOUND(res, opts);
+                return sendFile(req, res, path_1.default.join(pathname, 'index.html'), opts);
+            }
+            sendIt(req, res, pathname, stat, opts);
+        });
+    };
+}
+/**
+ * Middleware factory that serves a **single, fixed file** as the response to
+ * every request, regardless of the request path.
+ *
+ * Use this when you want every route to return the same file — for example,
+ * serving a compiled single-page application's `index.html` as a catch-all:
+ * ```ts
+ * app.get('/**', serveFile('./dist/index.html'));
+ * ```
+ *
+ * Features:
+ * - **Method filtering** — only `GET` and `HEAD` are served.
+ * - **Conditional GET** — ETag and Last-Modified are generated from the file
+ *   metadata on every request.
+ * - **MIME-type detection** — via the `mime` npm package.
+ *
+ * @param filePath - Path to the file to serve. Resolved to an absolute path.
+ * @param options  - Optional configuration (see {@link StaticOptions}).
+ * @returns An Express-compatible middleware function.
+ * @throws {TypeError} When `filePath` is missing or not a string.
+ */
+function serveFile(filePath, options) {
+    const opts = resolveOptions(filePath, options);
+    return function (req, res, next) {
+        // BUG FIX: the original `file()` function had the method-check logic
+        // inverted. `methOk` was set to `true` when the method was NOT GET/HEAD
+        // (i.e. the invalid case), and then `if (!methOk)` blocked valid methods.
+        // The corrected logic: reject when the method is NOT GET or HEAD.
+        if (req.method !== 'GET' && req.method !== 'HEAD') {
+            if (opts.fallthrough)
+                return next();
+            return HTTP.NOT_ALLOWED(res, opts);
+        }
+        const pathname = opts.root;
+        fs_1.default.stat(pathname, (err, stat) => {
+            if (err)
+                return HTTP.INTERNAL_ERROR(res, opts, err.code ?? 'UNKNOWN');
+            // BUG FIX: the original code referenced `err.code` inside the
+            // `stat.isDirectory()` branch, where `err` is guaranteed to be `null`
+            // (we only reach this branch when `fs.stat` succeeded). The correct
+            // response for a misconfigured directory path is a plain 500 with a
+            // descriptive message.
+            if (stat.isDirectory())
+                return HTTP.INTERNAL_ERROR(res, opts, 'EISDIR');
+            sendIt(req, res, pathname, stat, opts);
+        });
+    };
+}
+exports.default = { serveStatic, serveFile, sendFile };
+//# sourceMappingURL=static.js.map