skyguard-js 1.0.0

package/dist/middlewares/cors.d.ts

@@ -0,0 +1,103 @@
+import { HttpMethods } from "../http";
+import type { Middleware } from "../types";
+/**
+ * CORS origin matcher type.
+ *
+ * Controls how the middleware determines the value of
+ * `Access-Control-Allow-Origin` for a given request.
+ *
+ * Supported forms:
+ * - `string`: a single allowed origin (e.g. `"https://example.com"`) or `"*"` for public access
+ * - `string[]`: a whitelist of allowed origins
+ * - `function`: a custom resolver that receives the request Origin and decides what to allow
+ *
+ * Notes:
+ * - If `credentials: true` is enabled, `"*"` cannot be used as the final
+ *   `Access-Control-Allow-Origin` value. In that case this middleware will
+ *   reflect the request origin when allowed.
+ */
+type CorsOrigin = string | string[] | ((origin: string | undefined) => string);
+/**
+ * CORS middleware configuration options.
+ *
+ * These options map to standard CORS response headers and preflight behavior.
+ */
+interface CorsOptions {
+    /**
+     * Allowed origin(s) for cross-origin requests.
+     *
+     * - `"*"` allows any origin (public).
+     * - A specific origin (string) restricts access to that origin.
+     * - An array provides a whitelist.
+     * - A function can implement custom allow/deny logic.
+     *
+     * Affects: `Access-Control-Allow-Origin`.
+     */
+    origin?: CorsOrigin;
+    /**
+     * HTTP methods allowed for cross-origin requests.
+     *
+     * Used in preflight responses.
+     *
+     * Affects: `Access-Control-Allow-Methods`.
+     */
+    methods?: HttpMethods[];
+    /**
+     * Request headers the browser is allowed to send in cross-origin requests.
+     *
+     * Used in preflight responses (especially when the client sends custom headers
+     * such as `Authorization`).
+     *
+     * Affects: `Access-Control-Allow-Headers`.
+     */
+    allowedHeaders?: string[];
+    /**
+     * Response headers that should be exposed to browser JavaScript.
+     *
+     * By default, browsers do not allow JS to read non-safelisted headers.
+     *
+     * Affects: `Access-Control-Expose-Headers`.
+     */
+    exposedHeaders?: string[];
+    /**
+     * Whether the response can be exposed when credentials are included.
+     *
+     * Enables sending/receiving cookies and authenticated requests across origins.
+     *
+     * Affects: `Access-Control-Allow-Credentials`.
+     *
+     * Important:
+     * - When enabled, the final `Access-Control-Allow-Origin` value must not be `"*"`.
+     */
+    credentials?: boolean;
+    /**
+     * How long (in seconds) the browser may cache a successful preflight response.
+     *
+     * Improves performance by reducing repeated OPTIONS requests.
+     *
+     * Affects: `Access-Control-Max-Age`.
+     */
+    maxAge?: number;
+    /**
+     * If `false` (default), the middleware ends OPTIONS requests immediately with 204.
+     * If `true`, the request continues down the middleware/handler chain after setting
+     * the preflight headers.
+     */
+    preflightContinue?: boolean;
+}
+/**
+ * Native CORS middleware.
+ *
+ * Behavior overview:
+ * - Resolves the allowed origin from the request `Origin` header using `resolveOrigin`.
+ * - Sets `Access-Control-Allow-Origin` (and `Vary: Origin` when not `"*"`).
+ * - Optionally sets `Access-Control-Allow-Credentials` and `Access-Control-Expose-Headers`.
+ * - For OPTIONS requests, returns a 204 response (unless `preflightContinue` is enabled),
+ *   including `Access-Control-Allow-Methods`, `Access-Control-Allow-Headers`, and
+ *   `Access-Control-Max-Age`.
+ *
+ * @param options - CORS configuration.
+ * @returns A `Middleware` function that applies CORS headers to the response.
+ */
+export declare const cors: (options?: CorsOptions) => Middleware;
+export {};

package/dist/middlewares/cors.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cors = void 0;
+const http_1 = require("../http");
+/**
+ * Resolves the effective `Access-Control-Allow-Origin` value for a request.
+ *
+ * @param requestOrigin - The `Origin` header value from the incoming request.
+ * @returns The origin to allow:
+ * - `"*"` for public access when credentials are disabled
+ * - the request origin when it is allowed (whitelist or custom resolver)
+ * - `null` if the origin is not allowed (no CORS headers will be applied)
+ */
+function resolveOrigin(requestOrigin, config) {
+    if (!requestOrigin)
+        return null;
+    if (typeof config.origin === "function") {
+        const out = config.origin(requestOrigin);
+        return out ? requestOrigin : null;
+    }
+    if (Array.isArray(config.origin))
+        return config.origin.includes(requestOrigin) ? requestOrigin : null;
+    if (config.origin === "*")
+        return config.credentials ? requestOrigin : "*";
+    return config.origin;
+}
+/**
+ * Native CORS middleware.
+ *
+ * Behavior overview:
+ * - Resolves the allowed origin from the request `Origin` header using `resolveOrigin`.
+ * - Sets `Access-Control-Allow-Origin` (and `Vary: Origin` when not `"*"`).
+ * - Optionally sets `Access-Control-Allow-Credentials` and `Access-Control-Expose-Headers`.
+ * - For OPTIONS requests, returns a 204 response (unless `preflightContinue` is enabled),
+ *   including `Access-Control-Allow-Methods`, `Access-Control-Allow-Headers`, and
+ *   `Access-Control-Max-Age`.
+ *
+ * @param options - CORS configuration.
+ * @returns A `Middleware` function that applies CORS headers to the response.
+ */
+const cors = (options = {}) => {
+    const config = {
+        origin: options.origin ?? "*",
+        methods: options.methods ?? [
+            http_1.HttpMethods.get,
+            http_1.HttpMethods.post,
+            http_1.HttpMethods.put,
+            http_1.HttpMethods.patch,
+            http_1.HttpMethods.delete,
+            http_1.HttpMethods.options,
+        ],
+        allowedHeaders: options.allowedHeaders ?? ["Content-Type", "Authorization"],
+        exposedHeaders: options.exposedHeaders ?? [],
+        credentials: options.credentials ?? false,
+        maxAge: options.maxAge ?? 86400,
+        preflightContinue: options.preflightContinue ?? false,
+    };
+    return async (request, next) => {
+        const allowedOrigin = resolveOrigin(request.getHeaders.origin, config);
+        const corsHeaders = {};
+        if (allowedOrigin) {
+            corsHeaders["Access-Control-Allow-Origin"] = allowedOrigin;
+            if (allowedOrigin !== "*")
+                corsHeaders["Vary"] = "Origin";
+        }
+        if (config.credentials)
+            corsHeaders["Access-Control-Allow-Credentials"] = "true";
+        if (config.exposedHeaders.length) {
+            corsHeaders["Access-Control-Expose-Headers"] =
+                config.exposedHeaders.join(", ");
+        }
+        if (request.getMethod === http_1.HttpMethods.options) {
+            corsHeaders["Access-Control-Allow-Methods"] = config.methods.join(", ");
+            corsHeaders["Access-Control-Allow-Headers"] =
+                config.allowedHeaders.join(", ");
+            corsHeaders["Access-Control-Max-Age"] = String(config.maxAge);
+            if (!config.preflightContinue) {
+                return new http_1.Response()
+                    .setStatus(204)
+                    .setContent(null)
+                    .setHeaders(corsHeaders);
+            }
+        }
+        const response = await next(request);
+        for (const [key, value] of Object.entries(corsHeaders)) {
+            response.setHeader(key, value);
+        }
+        return response;
+    };
+};
+exports.cors = cors;

package/dist/middlewares/session.d.ts

@@ -0,0 +1,26 @@
+import { type SessionStorage, type CookieOptions } from "../sessions";
+import type { Middleware } from "../types";
+/**
+ * Constructor type for `SessionStorage` implementations.
+ *
+ * Allows injecting different session storage strategies
+ * (memory, file, redis, etc.).
+ */
+type SessionStorageConstructor<T extends SessionStorage = SessionStorage> = new (...args: any[]) => T;
+/**
+ * Session lifecycle middleware implementation.
+ *
+ * @param StorageClass - `SessionStorage` implementation
+ * @param options - Session cookie configuration
+ * @returns Session middleware
+ *
+ * @example
+ * app.middlewares([
+ *   sessionMiddleware(MemorySessionStorage, {
+ *     cookieName: "sid",
+ *     maxAge: 86400,
+ *   }),
+ * ]);
+ */
+export declare const sessions: (StorageClass: SessionStorageConstructor, options?: CookieOptions) => Middleware;
+export {};

package/dist/middlewares/session.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sessions = void 0;
+const sessions_1 = require("../sessions");
+/**
+ * Parses the `Cookie` header into a key/value object.
+ *
+ * @param cookieHeader - Raw `Cookie` header value
+ * @returns Parsed cookies
+ *
+ * @example
+ * parseCookies("foo=bar; session_id=abc123");
+ * // { foo: "bar", session_id: "abc123" }
+ */
+function parseCookies(cookieHeader) {
+    if (!cookieHeader)
+        return {};
+    return Object.fromEntries(cookieHeader.split(";").map((cookie) => {
+        const [key, ...value] = cookie.trim().split("=");
+        return [key, decodeURIComponent(value.join("="))];
+    }));
+}
+/**
+ * Builds the `Set-Cookie` header value for the session.
+ *
+ * @param sessionId - Session identifier
+ * @param config - Fully resolved cookie configuration
+ * @returns Value ready to be used in `Set-Cookie`
+ *
+ * @example
+ * buildSessionCookie("abc123", config);
+ * // "session_id=abc123; Max-Age=86400; Path=/; SameSite=Lax; HttpOnly"
+ */
+function buildSessionCookie(sessionId, config) {
+    const parts = [
+        `${config.cookieName}=${encodeURIComponent(sessionId)}`,
+        `Max-Age=${config.maxAge}`,
+        `Path=${config.path}`,
+        `SameSite=${config.sameSite}`,
+    ];
+    if (config.httpOnly)
+        parts.push("HttpOnly");
+    if (config.secure)
+        parts.push("Secure");
+    return parts.join("; ");
+}
+/**
+ * Session lifecycle middleware implementation.
+ *
+ * @param StorageClass - `SessionStorage` implementation
+ * @param options - Session cookie configuration
+ * @returns Session middleware
+ *
+ * @example
+ * app.middlewares([
+ *   sessionMiddleware(MemorySessionStorage, {
+ *     cookieName: "sid",
+ *     maxAge: 86400,
+ *   }),
+ * ]);
+ */
+const sessions = (StorageClass, options = {}) => {
+    const timeMaxAge = 86400;
+    const config = {
+        cookieName: options.cookieName ?? "session_id",
+        maxAge: options.maxAge ?? timeMaxAge,
+        httpOnly: options.httpOnly ?? true,
+        secure: options.secure ?? false,
+        sameSite: options.sameSite ?? "Lax",
+        path: options.path ?? "/",
+    };
+    return async (request, next) => {
+        const cookies = parseCookies(request.getHeaders["cookie"] || "");
+        const sessionId = cookies[config.cookieName];
+        const storage = new StorageClass(options.maxAge || timeMaxAge);
+        if (sessionId)
+            storage.load(sessionId);
+        const session = new sessions_1.Session(storage);
+        request.setSession(session);
+        const response = await next(request);
+        if (storage.id() !== null) {
+            const cookieValue = buildSessionCookie(storage.id(), config);
+            response.setHeader("Set-Cookie", cookieValue);
+        }
+        return response;
+    };
+};
+exports.sessions = sessions;

package/dist/parsers/contentParser.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Contract for classes responsible for parsing HTTP request bodies.
+ *
+ * Implementations decide whether they can handle a given `Content-Type`
+ * and transform the raw body into a usable structure.
+ */
+export interface ContentParser {
+    /**
+     * Determines whether this parser can handle the given content type.
+     *
+     * @param contentType - Full `Content-Type` header value
+     * @returns `true` if the content type can be parsed by this parser
+     */
+    canParse(contentType: string): boolean;
+    /**
+     * Parses the raw request body.
+     *
+     * If the content cannot be parsed, implementations may return
+     * the original body.
+     *
+     * @param body - Raw request body
+     * @param contentType - Full `Content-Type` header value
+     * (may include charset, boundary, etc.)
+     * @returns Parsed content or the original body
+     */
+    parse(body: Buffer | string, contentType: string): unknown;
+}

package/dist/parsers/contentParser.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/parsers/contentParserManager.d.ts

@@ -0,0 +1,50 @@
+import { IncomingMessage } from "node:http";
+import type { ContentParser } from "./contentParser";
+/**
+ * Main request body parsing manager.
+ *
+ * Coordinates multiple {@link ContentParser} implementations and
+ * selects the appropriate one based on the request `Content-Type`.
+ */
+export declare class ContentParserManager {
+    private parsers;
+    constructor();
+    /**
+     * Registers a custom content parser.
+     *
+     * Parsers registered later take priority over existing ones.
+     *
+     * @param parser - Content parser implementation
+     *
+     * @example
+     * contentParserManager.registerParser(new CustomParser());
+     */
+    registerParser(parser: ContentParser): void;
+    /**
+     * Parses the request body using the appropriate parser.
+     *
+     * The parser is selected based on the `Content-Type` header.
+     * If no parser matches, the raw body is returned.
+     *
+     * @param req - Native incoming HTTP request
+     * @returns Parsed body content or raw body
+     *
+     * @example
+     * const data = await contentParserManager.parse(req);
+     */
+    parse(req: IncomingMessage): Promise<unknown>;
+    /**
+     * Reads the raw request body.
+     *
+     * @param req - Native incoming HTTP request
+     * @returns A promise that resolves to the full body buffer
+     */
+    private readBody;
+    /**
+     * Finds a parser capable of handling the given content type.
+     *
+     * @param contentType - Request `Content-Type` header
+     * @returns Matching parser or `null` if none is found
+     */
+    private findParser;
+}

package/dist/parsers/contentParserManager.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContentParserManager = void 0;
+const jsonParser_1 = require("./jsonParser");
+const multipartParser_1 = require("./multipartParser");
+const textParser_1 = require("./textParser");
+const urlEncodedParser_1 = require("./urlEncodedParser");
+const xmlParser_1 = require("./xmlParser");
+const contentParserException_1 = require("../exceptions/contentParserException");
+/**
+ * Main request body parsing manager.
+ *
+ * Coordinates multiple {@link ContentParser} implementations and
+ * selects the appropriate one based on the request `Content-Type`.
+ */
+class ContentParserManager {
+    parsers = [];
+    constructor() {
+        this.registerParser(new jsonParser_1.JsonParser());
+        this.registerParser(new multipartParser_1.MultipartParser());
+        this.registerParser(new urlEncodedParser_1.UrlEncodedParser());
+        this.registerParser(new textParser_1.TextParser());
+        this.registerParser(new xmlParser_1.XmlParser());
+    }
+    /**
+     * Registers a custom content parser.
+     *
+     * Parsers registered later take priority over existing ones.
+     *
+     * @param parser - Content parser implementation
+     *
+     * @example
+     * contentParserManager.registerParser(new CustomParser());
+     */
+    registerParser(parser) {
+        // Insert at the beginning to give higher priority
+        this.parsers.unshift(parser);
+    }
+    /**
+     * Parses the request body using the appropriate parser.
+     *
+     * The parser is selected based on the `Content-Type` header.
+     * If no parser matches, the raw body is returned.
+     *
+     * @param req - Native incoming HTTP request
+     * @returns Parsed body content or raw body
+     *
+     * @example
+     * const data = await contentParserManager.parse(req);
+     */
+    async parse(req) {
+        const body = await this.readBody(req);
+        if (body.length <= 0)
+            return {};
+        const contentType = req.headers["content-type"] || "text/plain";
+        const parser = this.findParser(contentType);
+        if (!parser)
+            return Buffer.isBuffer(body) ? body : Buffer.from(body);
+        return parser.parse(body, contentType);
+    }
+    /**
+     * Reads the raw request body.
+     *
+     * @param req - Native incoming HTTP request
+     * @returns A promise that resolves to the full body buffer
+     */
+    readBody(req) {
+        return new Promise((resolve, reject) => {
+            const chunks = [];
+            req.on("data", (chunk) => {
+                chunks.push(chunk);
+            });
+            req.on("end", () => {
+                resolve(Buffer.concat(chunks));
+            });
+            req.on("error", () => {
+                reject(new contentParserException_1.ReadBodyException());
+            });
+        });
+    }
+    /**
+     * Finds a parser capable of handling the given content type.
+     *
+     * @param contentType - Request `Content-Type` header
+     * @returns Matching parser or `null` if none is found
+     */
+    findParser(contentType) {
+        return this.parsers.find((parser) => parser.canParse(contentType)) || null;
+    }
+}
+exports.ContentParserManager = ContentParserManager;

package/dist/parsers/index.d.ts

@@ -0,0 +1,8 @@
+export { ContentParserManager } from "./contentParserManager";
+export { ContentParser } from "./contentParser";
+export { JsonParser } from "./jsonParser";
+export { MultipartParser } from "./multipartParser";
+export { TextParser } from "./textParser";
+export { UrlEncodedParser } from "./urlEncodedParser";
+export { XmlParser } from "./xmlParser";
+export * from "./parserInterface";

package/dist/parsers/index.js

@@ -0,0 +1,30 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.XmlParser = exports.UrlEncodedParser = exports.TextParser = exports.MultipartParser = exports.JsonParser = exports.ContentParserManager = void 0;
+var contentParserManager_1 = require("./contentParserManager");
+Object.defineProperty(exports, "ContentParserManager", { enumerable: true, get: function () { return contentParserManager_1.ContentParserManager; } });
+var jsonParser_1 = require("./jsonParser");
+Object.defineProperty(exports, "JsonParser", { enumerable: true, get: function () { return jsonParser_1.JsonParser; } });
+var multipartParser_1 = require("./multipartParser");
+Object.defineProperty(exports, "MultipartParser", { enumerable: true, get: function () { return multipartParser_1.MultipartParser; } });
+var textParser_1 = require("./textParser");
+Object.defineProperty(exports, "TextParser", { enumerable: true, get: function () { return textParser_1.TextParser; } });
+var urlEncodedParser_1 = require("./urlEncodedParser");
+Object.defineProperty(exports, "UrlEncodedParser", { enumerable: true, get: function () { return urlEncodedParser_1.UrlEncodedParser; } });
+var xmlParser_1 = require("./xmlParser");
+Object.defineProperty(exports, "XmlParser", { enumerable: true, get: function () { return xmlParser_1.XmlParser; } });
+__exportStar(require("./parserInterface"), exports);

package/dist/parsers/jsonParser.d.ts

@@ -0,0 +1,10 @@
+import type { ContentParser } from "./contentParser";
+/**
+ * JSON content parser.
+ *
+ * Handles `application/json` and `application/*+json` content types.
+ */
+export declare class JsonParser implements ContentParser {
+    canParse(contentType: string): boolean;
+    parse(body: Buffer | string): unknown;
+}

package/dist/parsers/jsonParser.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JsonParser = void 0;
+const contentParserException_1 = require("../exceptions/contentParserException");
+/**
+ * JSON content parser.
+ *
+ * Handles `application/json` and `application/*+json` content types.
+ */
+class JsonParser {
+    canParse(contentType) {
+        return (contentType.includes("application/json") || contentType.includes("+json"));
+    }
+    parse(body) {
+        try {
+            const text = Buffer.isBuffer(body) ? body.toString("utf-8") : body;
+            return JSON.parse(text);
+        }
+        catch {
+            throw new contentParserException_1.ContentParserException("Invalid JSON content");
+        }
+    }
+}
+exports.JsonParser = JsonParser;

package/dist/parsers/multipartParser.d.ts

@@ -0,0 +1,35 @@
+import type { ContentParser } from "./contentParser";
+import type { MultipartData } from "./parserInterface";
+/**
+ * `multipart/form-data` content parser.
+ *
+ * Parses multipart payloads into fields and files.
+ */
+export declare class MultipartParser implements ContentParser {
+    /**
+     * Checks whether the given content type is `multipart/form-data`.
+     *
+     * @param contentType - Raw `Content-Type` header value
+     * @returns `true` if the content type is multipart
+     */
+    canParse(contentType: string): boolean;
+    /**
+     * Parses a `multipart/form-data` body into a typed structure.
+     *
+     * @param body - Raw request body
+     * @param contentType - Full `Content-Type` header value
+     * @returns Parsed multipart data (fields and files)
+     * @throws {ContentParserException} If the multipart boundary is missing
+     *
+     * @example
+     * // Typically called through ContentParserManager based on Content-Type:
+     * const parsed = parser.parse(body, "multipart/form-data; boundary=---123");
+     * // parsed.fields / parsed.files
+     */
+    parse(body: Buffer | string, contentType: string): MultipartData;
+    private extractBoundary;
+    private parseMultipart;
+    private splitBuffer;
+    private parsePart;
+    private parseHeaders;
+}