skyguard-js 1.0.0

package/dist/static/contentDisposition.js

@@ -0,0 +1,159 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContentDisposition = void 0;
+const contentDispositionException_1 = require("../exceptions/contentDispositionException");
+/**
+ * Generates safe `Content-Disposition` values for file downloads.
+ *
+ * Implements RFC 6266 and RFC 8187 for broad browser compatibility.
+ * Prevents header injection and handles non-ASCII filenames correctly.
+ *
+ * @example
+ * const cd = new ContentDisposition();
+ *
+ * cd.attachment("report.pdf");
+ * // => 'attachment; filename="report.pdf"'
+ *
+ * cd.attachment("reporte año 2024.pdf");
+ * // => 'attachment; filename="reporte ano 2024.pdf"; filename*=UTF-8\'\'reporte%20a%C3%B1o%202024.pdf'
+ *
+ * cd.inline("image.jpg");
+ * // => 'inline; filename="image.jpg"'
+ */
+class ContentDisposition {
+    /**
+     * Builds a `Content-Disposition` value for file downloads.
+     *
+     * @param filename - File name
+     * @returns `Content-Disposition` value
+     */
+    attachment(filename) {
+        return this.create("attachment", filename);
+    }
+    /**
+     * Builds a `Content-Disposition` value for inline rendering.
+     *
+     * @param filename - File name
+     * @returns `Content-Disposition` value
+     */
+    inline(filename) {
+        return this.create("inline", filename);
+    }
+    create(type, filename) {
+        if (!filename || typeof filename !== "string") {
+            throw new contentDispositionException_1.ContentDispositionException();
+        }
+        const sanitized = this.sanitizeFilename(filename);
+        const needsEncoding = this.needsEncoding(sanitized);
+        let disposition = type;
+        if (needsEncoding) {
+            const fallback = this.createAsciiFallback(sanitized);
+            disposition += `; filename="${this.escapeQuotes(fallback)}"`;
+            const encoded = this.encodeRFC8187(sanitized);
+            disposition += `; filename*=UTF-8''${encoded}`;
+        }
+        else {
+            disposition += `; filename="${this.escapeQuotes(sanitized)}"`;
+        }
+        return disposition;
+    }
+    sanitizeFilename(filename) {
+        return filename
+            .replace(/[\x00-\x1F\x7F-\x9F]/g, "")
+            .replace(/["\r\n]/g, "")
+            .replace(/[/\\]/g, "")
+            .replace(/\s+/g, " ")
+            .trim();
+    }
+    needsEncoding(filename) {
+        return /[^\x20-\x7E]/.test(filename);
+    }
+    createAsciiFallback(filename) {
+        const charMap = {
+            á: "a",
+            é: "e",
+            í: "i",
+            ó: "o",
+            ú: "u",
+            ñ: "n",
+            Á: "A",
+            É: "E",
+            Í: "I",
+            Ó: "O",
+            Ú: "U",
+            Ñ: "N",
+            ü: "u",
+            Ü: "U",
+            ç: "c",
+            Ç: "C",
+            ß: "ss",
+            æ: "ae",
+            œ: "oe",
+            " ": " ",
+        };
+        let result = filename;
+        for (const [char, replacement] of Object.entries(charMap)) {
+            result = result.replace(new RegExp(char, "g"), replacement);
+        }
+        result = result.replace(/[^\x20-\x7E]/g, "");
+        return result;
+    }
+    escapeQuotes(filename) {
+        return filename.replace(/"/g, '\\"');
+    }
+    encodeRFC8187(filename) {
+        const attrChar = /[a-zA-Z0-9!#$&+.^_`|~-]/;
+        let encoded = "";
+        for (let i = 0; i < filename.length; i++) {
+            const char = filename[i];
+            if (attrChar.test(char)) {
+                encoded += char;
+            }
+            else {
+                const bytes = Buffer.from(char, "utf-8");
+                for (const byte of bytes) {
+                    encoded += "%" + byte.toString(16).toUpperCase().padStart(2, "0");
+                }
+            }
+        }
+        return encoded;
+    }
+    /**
+     * Parses an existing `Content-Disposition` header value.
+     *
+     * Supports both `filename=` and `filename*=` (RFC 8187).
+     *
+     * @param header - Raw `Content-Disposition` header value
+     * @returns Parsed disposition type and filename (if present)
+     *
+     * @example
+     * const cd = new ContentDisposition();
+     * cd.parse('attachment; filename="report.pdf"');
+     * // => { type: "attachment", filename: "report.pdf" }
+     */
+    parse(header) {
+        const parts = header.split(";").map((p) => p.trim());
+        const type = parts[0];
+        let filename = null;
+        for (let i = 1; i < parts.length; i++) {
+            const part = parts[i];
+            if (part.startsWith("filename*=")) {
+                const value = part.substring(10);
+                const match = value.match(/^UTF-8''(.+)$/i);
+                if (match) {
+                    filename = decodeURIComponent(match[1]);
+                    break;
+                }
+            }
+            if (part.startsWith("filename=") && !filename) {
+                let value = part.substring(9);
+                if (value.startsWith('"') && value.endsWith('"')) {
+                    value = value.slice(1, -1);
+                }
+                filename = value.replace(/\\"/g, '"');
+            }
+        }
+        return { type, filename };
+    }
+}
+exports.ContentDisposition = ContentDisposition;

package/dist/static/fileDownload.d.ts

@@ -0,0 +1,44 @@
+import { Response } from "../http/response";
+/**
+ * Helper utility for serving file downloads.
+ *
+ * Builds a {@link Response} configured with safe headers
+ * (`Content-Disposition`, `Content-Type`, `Content-Length`)
+ * to send files to the client.
+ */
+export declare class FileDownloadHelper {
+    private contentDisposition;
+    constructor();
+    /**
+     * Creates a file download response.
+     *
+     * Resolves the file path, validates that it is a file,
+     * reads its contents, and returns a {@link Response}
+     * ready to be sent to the client.
+     *
+     * @param filePath - Path to the file on disk
+     * @param filename - Optional custom filename for the download
+     * @param headers - Optional additional response headers
+     * @returns A {@link Response} configured for file download
+     *
+     * @throws {FileDownloadException}
+     * Thrown if the file does not exist, is not a file,
+     * or cannot be read.
+     *
+     * @example
+     * const helper = new FileDownloadHelper();
+     *
+     * app.get("/download", async () => {
+     *   return helper.download("./files/report.pdf");
+     * });
+     *
+     * // Custom filename and headers
+     * return helper.download(
+     *   "./files/data.csv",
+     *   "export.csv",
+     *   { "Cache-Control": "no-store" }
+     * );
+     */
+    download(filePath: string, filename?: string, headers?: Record<string, string>): Promise<Response>;
+    private getMimeType;
+}

package/dist/static/fileDownload.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileDownloadHelper = void 0;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const mimeTypes_1 = require("./mimeTypes");
+const contentDisposition_1 = require("./contentDisposition");
+const response_1 = require("../http/response");
+const fileDownloadException_1 = require("../exceptions/fileDownloadException");
+/**
+ * Helper utility for serving file downloads.
+ *
+ * Builds a {@link Response} configured with safe headers
+ * (`Content-Disposition`, `Content-Type`, `Content-Length`)
+ * to send files to the client.
+ */
+class FileDownloadHelper {
+    contentDisposition;
+    constructor() {
+        this.contentDisposition = new contentDisposition_1.ContentDisposition();
+    }
+    /**
+     * Creates a file download response.
+     *
+     * Resolves the file path, validates that it is a file,
+     * reads its contents, and returns a {@link Response}
+     * ready to be sent to the client.
+     *
+     * @param filePath - Path to the file on disk
+     * @param filename - Optional custom filename for the download
+     * @param headers - Optional additional response headers
+     * @returns A {@link Response} configured for file download
+     *
+     * @throws {FileDownloadException}
+     * Thrown if the file does not exist, is not a file,
+     * or cannot be read.
+     *
+     * @example
+     * const helper = new FileDownloadHelper();
+     *
+     * app.get("/download", async () => {
+     *   return helper.download("./files/report.pdf");
+     * });
+     *
+     * // Custom filename and headers
+     * return helper.download(
+     *   "./files/data.csv",
+     *   "export.csv",
+     *   { "Cache-Control": "no-store" }
+     * );
+     */
+    async download(filePath, filename, headers) {
+        try {
+            const fullPath = (0, node_path_1.resolve)(filePath);
+            const stats = await (0, promises_1.stat)(fullPath);
+            if (!stats.isFile()) {
+                throw new fileDownloadException_1.FileDownloadException(`Path is not a file: ${fullPath}`);
+            }
+            const content = await (0, promises_1.readFile)(fullPath);
+            const downloadName = filename || (0, node_path_1.basename)(fullPath);
+            const downloadHeaders = {
+                "Content-Disposition": this.contentDisposition.attachment(downloadName),
+                "Content-Length": content.length.toString(),
+                "Content-Type": this.getMimeType(fullPath),
+            };
+            if (headers) {
+                for (const [key, value] of Object.entries(headers)) {
+                    // Prevent overriding Content-Disposition
+                    if (key.toLowerCase() !== "content-disposition") {
+                        downloadHeaders[key] = value;
+                    }
+                }
+            }
+            return new response_1.Response()
+                .setStatus(200)
+                .setContent(content)
+                .setHeaders(downloadHeaders);
+        }
+        catch {
+            throw new fileDownloadException_1.FileDownloadException("Failed to download file");
+        }
+    }
+    getMimeType(filePath) {
+        const ext = (0, node_path_1.extname)(filePath).toLowerCase();
+        return mimeTypes_1.mimeTypesObject[ext] || "application/octet-stream";
+    }
+}
+exports.FileDownloadHelper = FileDownloadHelper;

package/dist/static/fileStaticHandler.d.ts

@@ -0,0 +1,61 @@
+import { Response } from "../http/response";
+/**
+ * Static file handler for a public directory.
+ *
+ * Resolves and serves files from a configured `publicPath` using a URL prefix
+ * derived from the directory name (e.g. `/public`).
+ *
+ * Includes basic path traversal protection and sets cache-related headers.
+ *
+ * @example
+ * const staticFiles = new StaticFileHandler("./public");
+ *
+ * // In your request pipeline:
+ * const response = await staticFiles.tryServeFile(request.getUrl);
+ * if (response) return response;
+ */
+export declare class StaticFileHandler {
+    private publicPath;
+    private urlPrefix;
+    private mimeTypes;
+    constructor(publicPath: string);
+    /**
+     * Returns the configured URL prefix.
+     *
+     * @returns URL prefix (e.g. `"/public"`)
+     */
+    getUrlPrefix(): string;
+    /**
+     * Checks whether the request path matches the static prefix.
+     *
+     * @param requestPath - Requested path
+     * @returns `true` if the path starts with the prefix
+     */
+    matchesPrefix(requestPath: string): boolean;
+    /**
+     * Attempts to serve a static file.
+     *
+     * Returns `null` if:
+     * - the request path does not match the prefix
+     * - the resolved path escapes the public directory
+     * - the file does not exist or is not a file
+     * - an I/O error occurs
+     *
+     * @param requestPath - Requested path (e.g. `"/public/css/style.css"`)
+     * @returns A {@link Response} containing the file, or `null` if not found
+     *
+     * @example
+     * const response = await staticFiles.tryServeFile("/public/app.js");
+     * if (response) return response;
+     */
+    tryServeFile(requestPath: string): Promise<Response | null>;
+    /**
+     * Checks whether a request path looks like a static file request.
+     *
+     * This is a fast heuristic: it requires a file extension and a known mime type.
+     *
+     * @param requestPath - Requested path
+     * @returns `true` if it looks like a static file request
+     */
+    isStaticFileRequest(requestPath: string): boolean;
+}

package/dist/static/fileStaticHandler.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StaticFileHandler = void 0;
+const node_path_1 = require("node:path");
+const promises_1 = require("node:fs/promises");
+const mimeTypes_1 = require("./mimeTypes");
+const response_1 = require("../http/response");
+/**
+ * Static file handler for a public directory.
+ *
+ * Resolves and serves files from a configured `publicPath` using a URL prefix
+ * derived from the directory name (e.g. `/public`).
+ *
+ * Includes basic path traversal protection and sets cache-related headers.
+ *
+ * @example
+ * const staticFiles = new StaticFileHandler("./public");
+ *
+ * // In your request pipeline:
+ * const response = await staticFiles.tryServeFile(request.getUrl);
+ * if (response) return response;
+ */
+class StaticFileHandler {
+    publicPath = "";
+    urlPrefix = "";
+    mimeTypes;
+    constructor(publicPath) {
+        this.publicPath = (0, node_path_1.normalize)(publicPath);
+        this.urlPrefix = "/" + (0, node_path_1.basename)(this.publicPath);
+        this.mimeTypes = mimeTypes_1.mimeTypesObject;
+    }
+    /**
+     * Returns the configured URL prefix.
+     *
+     * @returns URL prefix (e.g. `"/public"`)
+     */
+    getUrlPrefix() {
+        return this.urlPrefix;
+    }
+    /**
+     * Checks whether the request path matches the static prefix.
+     *
+     * @param requestPath - Requested path
+     * @returns `true` if the path starts with the prefix
+     */
+    matchesPrefix(requestPath) {
+        return requestPath.startsWith(this.urlPrefix);
+    }
+    /**
+     * Attempts to serve a static file.
+     *
+     * Returns `null` if:
+     * - the request path does not match the prefix
+     * - the resolved path escapes the public directory
+     * - the file does not exist or is not a file
+     * - an I/O error occurs
+     *
+     * @param requestPath - Requested path (e.g. `"/public/css/style.css"`)
+     * @returns A {@link Response} containing the file, or `null` if not found
+     *
+     * @example
+     * const response = await staticFiles.tryServeFile("/public/app.js");
+     * if (response) return response;
+     */
+    async tryServeFile(requestPath) {
+        try {
+            if (!this.matchesPrefix(requestPath))
+                return null;
+            const relativePath = requestPath.slice(this.urlPrefix.length);
+            const filePath = (0, node_path_1.resolve)(this.publicPath, relativePath.replace(/^[/\\]+/, ""));
+            // Prevent path traversal (must stay within publicPath)
+            if (!filePath.startsWith(this.publicPath + node_path_1.sep))
+                return null;
+            const stats = await (0, promises_1.stat)(filePath);
+            if (!stats.isFile())
+                return null;
+            const content = await (0, promises_1.readFile)(filePath);
+            const ext = (0, node_path_1.extname)(filePath).toLowerCase();
+            const contentType = this.mimeTypes[ext] || this.mimeTypes["default"];
+            return new response_1.Response()
+                .setContent(content)
+                .setHeaders({
+                "content-type": contentType,
+                "content-length": content.length.toString(),
+                "cache-control": "public, max-age=31536000",
+                "last-modified": stats.mtime.toUTCString(),
+                ETag: `"${stats.size}-${stats.mtime.getTime()}"`,
+            })
+                .setStatus(200);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Checks whether a request path looks like a static file request.
+     *
+     * This is a fast heuristic: it requires a file extension and a known mime type.
+     *
+     * @param requestPath - Requested path
+     * @returns `true` if it looks like a static file request
+     */
+    isStaticFileRequest(requestPath) {
+        if (!this.matchesPrefix(requestPath))
+            return false;
+        const ext = (0, node_path_1.extname)(requestPath);
+        return ext !== "" && ext in this.mimeTypes;
+    }
+}
+exports.StaticFileHandler = StaticFileHandler;

package/dist/static/index.d.ts

@@ -0,0 +1,4 @@
+export { ContentDisposition } from "./contentDisposition";
+export { FileDownloadHelper } from "./fileDownload";
+export { StaticFileHandler } from "./fileStaticHandler";
+export { mimeTypesObject } from "./mimeTypes";

package/dist/static/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mimeTypesObject = exports.StaticFileHandler = exports.FileDownloadHelper = exports.ContentDisposition = void 0;
+var contentDisposition_1 = require("./contentDisposition");
+Object.defineProperty(exports, "ContentDisposition", { enumerable: true, get: function () { return contentDisposition_1.ContentDisposition; } });
+var fileDownload_1 = require("./fileDownload");
+Object.defineProperty(exports, "FileDownloadHelper", { enumerable: true, get: function () { return fileDownload_1.FileDownloadHelper; } });
+var fileStaticHandler_1 = require("./fileStaticHandler");
+Object.defineProperty(exports, "StaticFileHandler", { enumerable: true, get: function () { return fileStaticHandler_1.StaticFileHandler; } });
+var mimeTypes_1 = require("./mimeTypes");
+Object.defineProperty(exports, "mimeTypesObject", { enumerable: true, get: function () { return mimeTypes_1.mimeTypesObject; } });

package/dist/static/mimeTypes.d.ts

@@ -0,0 +1 @@
+export declare const mimeTypesObject: Record<string, string>;

package/dist/static/mimeTypes.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mimeTypesObject = void 0;
+exports.mimeTypesObject = {
+    // Text
+    ".html": "text/html",
+    ".css": "text/css",
+    ".js": "text/javascript",
+    ".json": "application/json",
+    ".xml": "application/xml",
+    ".txt": "text/plain",
+    // Images
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".svg": "image/svg+xml",
+    ".webp": "image/webp",
+    ".ico": "image/x-icon",
+    // Fonts
+    ".woff": "font/woff",
+    ".woff2": "font/woff2",
+    ".ttf": "font/ttf",
+    ".otf": "font/otf",
+    ".eot": "application/vnd.ms-fontobject",
+    // Documents
+    ".pdf": "application/pdf",
+    ".doc": "application/msword",
+    ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    // Archives
+    ".zip": "application/zip",
+    ".rar": "application/x-rar-compressed",
+    // Audio/Video
+    ".mp3": "audio/mpeg",
+    ".mp4": "video/mp4",
+    ".webm": "video/webm",
+    ".ogg": "audio/ogg",
+    // Default
+    default: "application/octet-stream",
+};