tezx 2.0.11 → 3.0.0

package/middleware/secure-headers copy.js

@@ -0,0 +1,136 @@
+import crypto from "crypto";
+const joinSrc = (v) => typeof v === "string" ? v : v.join(" ");
+const buildCSPString = (cspObj) => {
+    const parts = [];
+    for (const key in cspObj) {
+        parts.push(`${key} ${joinSrc(cspObj[key])}`);
+    }
+    return parts.join("; ");
+};
+const defaultPresets = {
+    strict: {
+        preset: "strict",
+        hsts: true,
+        hstsMaxAge: 63072000,
+        frameGuard: "DENY",
+        noSniff: true,
+        xssProtection: true,
+        referrerPolicy: "strict-origin-when-cross-origin",
+        permissionsPolicy: "geolocation=(), microphone=(), camera=(), usb=()",
+        csp: {
+            "default-src": ["'self'"],
+            "script-src": ["'self'"],
+            "style-src": ["'self'", "'unsafe-inline'"],
+            "img-src": ["'self'", "data:", "blob:"],
+            "font-src": ["'self'"],
+            "connect-src": ["'self'"],
+            "object-src": ["'none'"],
+            "frame-ancestors": ["'none'"],
+        },
+        cspReportOnly: false,
+    },
+    balanced: {
+        preset: "balanced",
+        hsts: true,
+        hstsMaxAge: 31536000,
+        frameGuard: "SAMEORIGIN",
+        noSniff: true,
+        xssProtection: true,
+        referrerPolicy: "no-referrer-when-downgrade",
+        permissionsPolicy: "geolocation=(), microphone=()",
+        csp: {
+            "default-src": ["'self'"],
+            "script-src": ["'self'", "https://cdn.jsdelivr.net"],
+            "style-src": [
+                "'self'",
+                "'unsafe-inline'",
+                "https://fonts.googleapis.com",
+            ],
+            "img-src": ["'self'", "data:", "https://images.example.com"],
+            "connect-src": ["'self'", "https://api.example.com"],
+        },
+        cspReportOnly: true,
+    },
+    dev: {
+        preset: "dev",
+        hsts: false,
+        frameGuard: "SAMEORIGIN",
+        noSniff: false,
+        xssProtection: false,
+        referrerPolicy: "no-referrer",
+        permissionsPolicy: "",
+        csp: {
+            "default-src": [
+                "'self'",
+                "'unsafe-inline'",
+                "'unsafe-eval'",
+                "http://localhost:3000",
+            ],
+            "img-src": ["'self'", "data:", "blob:"],
+        },
+        cspReportOnly: true,
+    },
+};
+const setHeader = (ctx, name, value) => {
+    if (typeof ctx.setHeader === "function")
+        ctx.setHeader(name, value);
+    else if (ctx.response?.setHeader)
+        ctx.response.setHeader(name, value);
+    else if (ctx.headersOut)
+        ctx.headersOut[name] = value;
+};
+export const secureHeaders = (userOpts = {}) => {
+    const preset = userOpts.preset ?? "balanced";
+    const base = {
+        ...(defaultPresets[preset] || defaultPresets.balanced),
+        ...userOpts,
+    };
+    const hstsHeader = base.hsts
+        ? `max-age=${base.hstsMaxAge || 31536000}; includeSubDomains; preload`
+        : "";
+    const frameHeader = base.frameGuard || "SAMEORIGIN";
+    const noSniffHeader = base.noSniff ? "nosniff" : "";
+    const xssHeader = base.xssProtection ? "1; mode=block" : "0";
+    const referrerHeader = base.referrerPolicy || "no-referrer";
+    const permissionsHeader = base.permissionsPolicy || "";
+    let cspStatic = null;
+    let cspNeedsNonce = !!base.cspUseNonce;
+    if (typeof base.csp === "string")
+        cspStatic = base.csp;
+    else if (base.csp && typeof base.csp === "object")
+        cspStatic = buildCSPString(base.csp);
+    if (base.ultraFastMode)
+        cspNeedsNonce = false;
+    const cspReportOnly = !!base.cspReportOnly;
+    return async (ctx, next) => {
+        try {
+            if (base.hsts)
+                setHeader(ctx, "Strict-Transport-Security", hstsHeader);
+            setHeader(ctx, "X-Frame-Options", frameHeader);
+            setHeader(ctx, "X-Content-Type-Options", noSniffHeader);
+            setHeader(ctx, "X-XSS-Protection", xssHeader);
+            setHeader(ctx, "Referrer-Policy", referrerHeader);
+            if (permissionsHeader)
+                setHeader(ctx, "Permissions-Policy", permissionsHeader);
+            if (cspNeedsNonce) {
+                const nonce = crypto.randomBytes(12).toString("base64");
+                let cspHeader = cspStatic || `default-src 'self'; script-src 'self' 'nonce-${nonce}'`;
+                if (cspReportOnly)
+                    setHeader(ctx, "Content-Security-Policy-Report-Only", cspHeader);
+                else
+                    setHeader(ctx, "Content-Security-Policy", cspHeader);
+                ctx.cspNonce = nonce;
+            }
+            else if (cspStatic) {
+                if (cspReportOnly)
+                    setHeader(ctx, "Content-Security-Policy-Report-Only", cspStatic);
+                else
+                    setHeader(ctx, "Content-Security-Policy", cspStatic);
+            }
+            return await next();
+        }
+        catch {
+            return await next();
+        }
+    };
+};

package/middleware/secure-headers.d.ts

@@ -0,0 +1,132 @@
+import { Middleware } from "../types/index.js";
+/**
+ * Options for HTTP Strict Transport Security (HSTS) header.
+ */
+export interface HstsOptions {
+    /**
+     * Max age in seconds for the `Strict-Transport-Security` header.
+     * Example: 31536000 (1 year)
+     */
+    maxAge?: number;
+    /**
+     * Apply HSTS to subdomains by adding `includeSubDomains` directive.
+     * Default: false
+     */
+    includeSubDomains?: boolean;
+    /**
+     * Add `preload` directive for browser preload lists.
+     * Default: false
+     */
+    preload?: boolean;
+    /**
+     * Only apply HSTS on HTTPS requests.
+     * If true, HTTP requests will not receive the HSTS header.
+     * Default: false
+     */
+    hstsOnlyOnHttps?: boolean;
+}
+/**
+ * Options for the secureHeaders middleware.
+ */
+export type SecureHeadersOptions = {
+    /**
+     * Built-in preset to use.
+     * - "strict": strongest defaults for production.
+     * - "balanced": reasonable defaults for most apps (report-only CSP by default).
+     * - "dev": permissive settings useful for local development.
+     *
+     * @default "balanced"
+     */
+    preset?: "strict" | "balanced" | "dev";
+    /**
+     * HSTS (HTTP Strict Transport Security) options.
+     * If provided, the middleware will set the `Strict-Transport-Security` header.
+     *
+     * @example
+     * { maxAge: 31536000, includeSubDomains: true, preload: true }
+     */
+    hsts?: HstsOptions;
+    /**
+     * Value for `X-Frame-Options` header.
+     * Common values: "DENY", "SAMEORIGIN".
+     *
+     * @default "SAMEORIGIN"
+     */
+    frameGuard?: "DENY" | "SAMEORIGIN" | string;
+    /**
+     * If true, sets `X-Content-Type-Options: nosniff`.
+     *
+     * @default true (depends on preset)
+     */
+    noSniff?: boolean;
+    /**
+     * If true, sets `X-XSS-Protection: 1; mode=block`.
+     * Note: modern browsers use CSP; this header is legacy but harmless.
+     *
+     * @default true (depends on preset)
+     */
+    xssProtection?: boolean;
+    /**
+     * Value for `Referrer-Policy` header.
+     * Examples: "no-referrer", "strict-origin-when-cross-origin".
+     *
+     * @default "no-referrer" (depends on preset)
+     */
+    referrerPolicy?: string;
+    /**
+     * Value for `Permissions-Policy` (formerly Feature-Policy).
+     * Example: 'geolocation=(), microphone=()'
+     *
+     * @default '' (empty string = not set)
+     */
+    permissionsPolicy?: string;
+    /**
+     * Content Security Policy (CSP).
+     * - Pass a raw header string to use it unchanged.
+     * - Or pass an object mapping directives to sources (object will be prebuilt at init).
+     *
+     * Example object:
+     * {
+     *   "default-src": ["'self'"],
+     *   "script-src": ["'self'", "https://cdn.example.com"]
+     * }
+     */
+    csp?: string | Record<string, string | string[]>;
+    /**
+     * If true, send `Content-Security-Policy-Report-Only` instead of enforcement header.
+     * Useful when first testing policies.
+     *
+     * @default false
+     */
+    cspReportOnly?: boolean;
+    /**
+     * If true, middleware will generate a per-request nonce (string) and inject it
+     * into the `script-src` directive so inline scripts with that nonce are allowed.
+     * Note: nonce generation allocates a small string per-request unless `ultraFastMode` is enabled.
+     *
+     * @default false
+     */
+    cspUseNonce?: boolean;
+    /**
+     * Ultra-fast mode disables per-request allocations (e.g., nonce generation).
+     * Use this in high-QPS environments where inline scripts are not required.
+     *
+     * @default false
+     */
+    ultraFastMode?: boolean;
+};
+/**
+ * secureHeaders middleware
+ *
+ * Precomputes static headers (HSTS, static CSP, X-Frame-Options, etc.) at
+ * middleware creation time. Optionally supports per-request CSP nonces
+ * (disabled in ultraFastMode).
+ *
+ * @template T,Path
+ * @param {SecureHeadersOptions} [userOpts={}] - configuration overrides
+ * @returns {Middleware<T,Path>} TezX-compatible middleware
+ *
+ * @example
+ * app.use(secureHeaders({ preset: 'strict', cspUseNonce: true }));
+ */
+export declare const secureHeaders: <T extends Record<string, any> = {}, Path extends string = any>(userOpts?: SecureHeadersOptions) => Middleware<T, Path>;

package/middleware/secure-headers.js

@@ -0,0 +1,153 @@
+import { generateRandomBase64, GlobalConfig } from "../helper/index.js";
+const joinSrc = (v) => typeof v === "string" ? v : v.join(" ");
+const buildCSPString = (cspObj) => {
+    const parts = [];
+    for (const key in cspObj)
+        parts.push(`${key} ${joinSrc(cspObj[key])}`);
+    return parts.join("; ");
+};
+export const secureHeaders = (userOpts = {}) => {
+    const defaultPresets = {
+        strict: {
+            preset: "strict",
+            hsts: { maxAge: 63072000, includeSubDomains: true, preload: true },
+            frameGuard: "DENY",
+            noSniff: true,
+            xssProtection: true,
+            referrerPolicy: "strict-origin-when-cross-origin",
+            permissionsPolicy: "geolocation=(), microphone=(), camera=(), usb=()",
+            csp: {
+                "default-src": ["'self'"],
+                "script-src": ["'self'"],
+                "style-src": ["'self'", "'unsafe-inline'"],
+                "img-src": ["'self'", "data:", "blob:"],
+                "font-src": ["'self'"],
+                "connect-src": ["'self'"],
+                "object-src": ["'none'"],
+                "frame-ancestors": ["'none'"],
+            },
+            cspReportOnly: false,
+        },
+        balanced: {
+            preset: "balanced",
+            hsts: { maxAge: 31536000, includeSubDomains: true, preload: true },
+            frameGuard: "SAMEORIGIN",
+            noSniff: true,
+            xssProtection: true,
+            referrerPolicy: "no-referrer-when-downgrade",
+            permissionsPolicy: "geolocation=(), microphone=()",
+            csp: {
+                "default-src": ["'self'"],
+                "script-src": ["'self'", "https://cdn.jsdelivr.net"],
+                "style-src": [
+                    "'self'",
+                    "'unsafe-inline'",
+                    "https://fonts.googleapis.com",
+                ],
+                "img-src": ["'self'", "data:", "https://images.example.com"],
+                "connect-src": ["'self'", "https://api.example.com"],
+            },
+            cspReportOnly: true,
+        },
+        dev: {
+            preset: "dev",
+            hsts: undefined,
+            frameGuard: "SAMEORIGIN",
+            noSniff: false,
+            xssProtection: false,
+            referrerPolicy: "no-referrer",
+            permissionsPolicy: "",
+            csp: {
+                "default-src": [
+                    "'self'",
+                    "'unsafe-inline'",
+                    "'unsafe-eval'",
+                    "http://localhost:3000",
+                ],
+                "img-src": ["'self'", "data:", "blob:"],
+            },
+            cspReportOnly: true,
+        },
+    };
+    const preset = userOpts.preset ?? "balanced";
+    const base = {
+        ...(defaultPresets[preset] || defaultPresets.balanced),
+        ...userOpts,
+    };
+    const frameHeader = base.frameGuard || "SAMEORIGIN";
+    const xssHeader = base.xssProtection ? "1; mode=block" : "0";
+    const noSniffHeader = base.noSniff ? "nosniff" : "";
+    const permissionsHeader = base.permissionsPolicy || "";
+    const referrerHeader = base.referrerPolicy || "no-referrer";
+    const hstsParts = [`max-age=${base.hsts?.maxAge || 31536000}`];
+    if (base.hsts?.includeSubDomains)
+        hstsParts.push("includeSubDomains");
+    if (base.hsts?.preload)
+        hstsParts.push("preload");
+    const hstsHeader = hstsParts.join("; ");
+    let cspStatic = null;
+    let cspNeedsNonce = !!base.cspUseNonce;
+    if (typeof base.csp === "string")
+        cspStatic = base.csp;
+    else if (base.csp)
+        cspStatic = buildCSPString(base.csp);
+    const cspReportOnly = !!base.cspReportOnly;
+    const ultraFast = !!base.ultraFastMode;
+    if (cspNeedsNonce && ultraFast) {
+        GlobalConfig.debugging.warn("secureHeaders: ultraFastMode disables CSP nonce support. Nonce will not be used.");
+    }
+    if (ultraFast)
+        cspNeedsNonce = false;
+    return async (ctx, next) => {
+        try {
+            if (base.hsts) {
+                const proto = (ctx.req?.header("x-forwarded-proto") || "").toString();
+                if (!base.hsts.hstsOnlyOnHttps || proto.includes("https")) {
+                    ctx.headers.set("Strict-Transport-Security", hstsHeader);
+                }
+            }
+            ctx.headers.set("X-Frame-Options", frameHeader);
+            ctx.headers.set("X-Content-Type-Options", noSniffHeader);
+            ctx.headers.set("X-XSS-Protection", xssHeader);
+            ctx.headers.set("Referrer-Policy", referrerHeader);
+            if (permissionsHeader)
+                ctx.headers.set("Permissions-Policy", permissionsHeader);
+            if (cspNeedsNonce) {
+                const nonce = generateRandomBase64();
+                let cspHeader = cspStatic;
+                if (!cspHeader) {
+                    cspHeader = `default-src 'self'; script-src 'self' 'nonce-${nonce}'`;
+                }
+                if (typeof base.csp === "object") {
+                    const idx = cspHeader.indexOf("script-src");
+                    if (idx >= 0) {
+                        const parts = [];
+                        parts.push(cspHeader.slice(0, idx + 10));
+                        parts.push(" 'nonce-" + nonce + "'");
+                        parts.push(cspHeader.slice(idx + 10));
+                        cspHeader = parts.join("");
+                    }
+                    else {
+                        cspHeader += "; script-src 'self' 'nonce-" + nonce + "'";
+                    }
+                }
+                ctx.cspNonce = nonce;
+                if (cspReportOnly)
+                    ctx.headers.set("Content-Security-Policy-Report-Only", cspHeader);
+                else
+                    ctx.headers.set("Content-Security-Policy", cspHeader);
+            }
+            else if (cspStatic) {
+                if (cspReportOnly)
+                    ctx.headers.set("Content-Security-Policy-Report-Only", cspStatic);
+                else
+                    ctx.headers.set("Content-Security-Policy", cspStatic);
+            }
+            return await next();
+        }
+        catch (err) {
+            console.error("secureHeaders middleware error", err);
+            return await next();
+        }
+    };
+};

package/middleware/{xssProtection.d.ts → xss-protection.d.ts}

@@ -40,4 +40,5 @@ export type XSSProtectionOptions = {
  *   fallbackCSP: "default-src 'self'"
  * }));
  */
-export declare const xssProtection: (options?: XSSProtectionOptions) => (ctx: Context, next: NextCallback) => Promise<any>;
+declare const xssProtection: (options?: XSSProtectionOptions) => (ctx: Context, next: NextCallback) => Promise<void>;
+export { xssProtection as default, xssProtection };

package/middleware/xss-protection.js

@@ -0,0 +1,19 @@
+const xssProtection = (options = {}) => {
+    const { enabled = true, mode = "block", fallbackCSP = "default-src 'self'; script-src 'self';", } = options;
+    return async function xssProtection(ctx, next) {
+        const isEnabled = typeof enabled === "function" ? enabled(ctx) : enabled;
+        if (!isEnabled) {
+            return await next();
+        }
+        const xssHeaderValue = mode === "block" ? "1; mode=block" : "1";
+        ctx.setHeader("X-XSS-Protection", xssHeaderValue);
+        if (fallbackCSP) {
+            const existingCSP = ctx.req.header("content-security-policy");
+            if (!existingCSP) {
+                ctx.setHeader("Content-Security-Policy", fallbackCSP);
+            }
+        }
+        return await next();
+    };
+};
+export { xssProtection as default, xssProtection };

package/node/env.js

@@ -1,11 +1,11 @@
-import { existsSync, readFileSync } from "node:fs";
-import { Environment } from "../core/environment.js";
+import { existsSync, readFileSync } from "fs";
+import { TezXError } from "../core/error.js";
 import { colorText } from "../utils/colors.js";
+import { runtime } from "../utils/runtime.js";
 function parseEnvFile(filePath, result) {
     try {
-        let runtime = Environment.getEnvironment;
         if (runtime !== "bun" && runtime !== "node") {
-            throw new Error(`Please use ${colorText(`import {loadEnv} from "tezx/${runtime}"`, "bgRed")} environment`);
+            throw new TezXError(`Please use ${colorText(`import {loadEnv} from "tezx/${runtime}"`, "bgRed")} environment`);
         }
         let fileExists = existsSync(filePath);
         if (!fileExists) {

package/node/getConnInfo.d.ts

@@ -0,0 +1,21 @@
+import { Middleware } from "../types/index.js";
+/**
+ * Middleware to extract and inject connection information into the request context.
+ *
+ * This middleware reads the socket's remote address information (like IP, port, and family)
+ * from the request object and attaches it to `ctx.req.remoteAddress`.
+ *
+ * @returns {Middleware<any>} The middleware function that sets `ctx.req.remoteAddress`.
+ *
+ * @example
+ * import { getConnInfo } from "tezx/node";
+ *
+ * app.use(getConnInfo());
+ *
+ * // Access later in route handler:
+ * router.get("/", (ctx) => {
+ *   const ip = ctx.req.remoteAddress?.address;
+ *   return new Response(`Your IP: ${ip}`);
+ * });
+ */
+export declare function getConnInfo<T extends Record<string, any> = {}, Path extends string = any>(): Middleware<T, Path>;

package/node/getConnInfo.js

@@ -0,0 +1,13 @@
+export function getConnInfo() {
+    return (ctx, next) => {
+        let request = ctx.args?.[0];
+        if (request && request.socket) {
+            ctx.req.remoteAddress = {
+                family: request.socket.remoteFamily,
+                address: request.socket.remoteAddress,
+                port: request.socket.remotePort,
+            };
+        }
+        return next();
+    };
+}

package/node/index.d.ts

@@ -1,9 +1,18 @@
-import { nodeAdapter } from "./adapter.js";
 import { loadEnv } from "./env.js";
-export * from "./adapter.js";
-export * from "./env.js";
+import { getConnInfo } from "./getConnInfo.js";
+import { mountTezXOnNode } from "./mount-node.js";
+import { serveStatic } from "./serveStatic.js";
+import { toWebRequest } from "./toWebRequest.js";
+import { upgradeWebSocket } from "./ws.js";
+export type { nodeWebSocketOptions } from "./ws.js";
+export type { ServeStatic, StaticServeOption, StaticFileArray, WebSocketCallback, WebSocketEvent, WebSocketOptions, } from "../types/index.js";
+export { serveStatic, upgradeWebSocket, getConnInfo, toWebRequest, loadEnv, mountTezXOnNode, };
 declare const _default: {
-    nodeAdapter: typeof nodeAdapter;
+    serveStatic: typeof serveStatic;
+    upgradeWebSocket: typeof upgradeWebSocket;
+    mountTezXOnNode: typeof mountTezXOnNode;
+    toWebRequest: typeof toWebRequest;
+    getConnInfo: typeof getConnInfo;
     loadEnv: typeof loadEnv;
 };
 export default _default;

package/node/index.js

@@ -1,8 +1,15 @@
-import { nodeAdapter } from "./adapter.js";
 import { loadEnv } from "./env.js";
-export * from "./adapter.js";
-export * from "./env.js";
+import { getConnInfo } from "./getConnInfo.js";
+import { mountTezXOnNode } from "./mount-node.js";
+import { serveStatic } from "./serveStatic.js";
+import { toWebRequest } from "./toWebRequest.js";
+import { upgradeWebSocket } from "./ws.js";
+export { serveStatic, upgradeWebSocket, getConnInfo, toWebRequest, loadEnv, mountTezXOnNode, };
 export default {
-    nodeAdapter,
+    serveStatic,
+    upgradeWebSocket,
+    mountTezXOnNode,
+    toWebRequest,
+    getConnInfo,
     loadEnv,
 };

package/node/mount-node.d.ts

@@ -0,0 +1,11 @@
+import { TezX } from "../core/server.js";
+/**
+ * Mounts a TezX app onto a native Node.js HTTP server.
+ *
+ * This bridges a TezX application (typically used in a Fetch API environment) with a native
+ * Node.js HTTP server by adapting the request/response interface and handling stream piping.
+ *
+ * @param {TezX} app - The TezX app instance that handles incoming requests and returns a Response object.
+ * @param {import('http').Server} server - A native Node.js HTTP server instance to attach the TezX handler to.
+ */
+export declare function mountTezXOnNode(app: TezX, server: any): void;

package/node/mount-node.js

@@ -0,0 +1,56 @@
+import { Readable } from "node:stream";
+import { GlobalConfig } from "../core/config.js";
+import { toWebRequest } from "./toWebRequest.js";
+function readableStreamToNodeStream(stream) {
+    const reader = stream.getReader();
+    return new Readable({
+        async read() {
+            try {
+                const { done, value } = await reader.read();
+                if (done) {
+                    this.push(null);
+                }
+                else {
+                    this.push(value);
+                }
+            }
+            catch (err) {
+                this.destroy(err);
+            }
+        },
+        destroy(err, callback) {
+            reader.cancel().then(() => callback(err), (cancelErr) => callback(cancelErr));
+        },
+    });
+}
+export function mountTezXOnNode(app, server) {
+    server.on("request", async (req, res) => {
+        try {
+            const request = toWebRequest(req, req.method);
+            const response = await app.serve(request, req, res, server);
+            if (res.writableEnded || res.headersSent)
+                return;
+            const { status = 200, statusText = "", headers = {}, body } = response;
+            const nodeHeaders = Object.fromEntries(headers instanceof Headers
+                ? headers.entries()
+                : Object.entries(headers));
+            res.writeHead(status, statusText, nodeHeaders);
+            if (!body) {
+                return res.end();
+            }
+            if (body instanceof Readable) {
+                return body.pipe(res);
+            }
+            if (typeof body.getReader === "function") {
+                return (Readable.fromWeb?.(body)?.pipe?.(res) ??
+                    readableStreamToNodeStream(body).pipe(res));
+            }
+            res.end(body);
+        }
+        catch (err) {
+            res.statusCode = 500;
+            GlobalConfig.debugging?.error?.(err?.message || "Unknown error");
+            res.end(err?.message || "Internal Server Error");
+        }
+    });
+}

package/node/serveStatic.d.ts

@@ -0,0 +1,36 @@
+import { ServeStatic, StaticFileArray, StaticServeOption } from "../types/index.js";
+/**
+ * Registers static files for serving from a folder, optionally under a specific route.
+ *
+ * There are two usage patterns:
+ *
+ * 1. `serveStatic(route: string, folder: string, option?: StaticServeOption)`
+ *    - Serves files in `folder` under the given `route`.
+ *    - Example: `serveStatic("/assets", "./public/assets")`
+ *
+ * 2. `serveStatic(folder: string, option?: StaticServeOption)`
+ *    - Serves files in `folder` under its own route (e.g., `./public` -> `/public`)
+ *    - Example: `serveStatic("./public")`
+ *
+ * @param args - Either [route, folder, option] or [folder, option]
+ * @returns A list of static files and their associated route paths.
+ */
+/**
+ * Universal ETag generator for Deno, Bun, and Node.js environments.
+ * Uses file size + modification time (mtimeMs) to create a unique hash-based ETag.
+ *
+ * @example
+ * const etag = await getETag("/path/to/file.txt");
+ * ctx.setHeader("ETag", etag);
+ */
+export declare function serveStatic(route: string, folder: string, option?: StaticServeOption): ServeStatic;
+export declare function serveStatic(folder: string, option?: StaticServeOption): ServeStatic;
+/**
+ * Recursively collects files from a directory, applying filters.
+ *
+ * @param dir - Directory to search.
+ * @param basePath - Route base path for constructing public paths.
+ * @param option - Options including extensions filter.
+ * @returns Array of file objects with file system and public paths.
+ */
+export declare function getFiles(dir: string, basePath?: string, option?: StaticServeOption): StaticFileArray;