skyguard-js 1.2.1 → 1.2.2

package/dist/http/response.js

@@ -11,6 +11,7 @@ const promises_1 = require("node:fs/promises");
 const node_path_1 = require("node:path");
 const mimeTypes_1 = require("../static/mimeTypes");
 const httpExceptions_1 = require("../exceptions/httpExceptions");
+const node_stream_1 = require("node:stream");
 /**
  * Represents an outgoing response sent to the client.
  *
@@ -115,6 +116,18 @@ class Response {
         this._content = content;
         return this;
     }
+    /**
+     * Sets a readable stream as the response body.
+     *
+     * Use this when you need to send large payloads in chunks without
+     * buffering the full content in memory first.
+     *
+     * @param stream - Node.js readable stream
+     * @returns The current {@link Response} instance
+     */
+    stream(stream) {
+        return this.setContent(stream);
+    }
     /**
      * Prepares the response before being sent to the client.
      *
@@ -131,14 +144,16 @@ class Response {
      */
     prepare() {
         if (!this._headers["content-type"] && this._content) {
-            if (Buffer.isBuffer(this._content)) {
+            if (Buffer.isBuffer(this._content) || this._content instanceof node_stream_1.Readable) {
                 this._headers["content-type"] = "application/octet-stream";
             }
             else {
                 this._headers["content-type"] = "text/plain";
             }
         }
-        if (this._content && !this._headers["content-length"]) {
+        if (this._content &&
+            !(this._content instanceof node_stream_1.Readable) &&
+            !this._headers["content-length"]) {
             const length = Buffer.isBuffer(this._content)
                 ? this._content.length
                 : Buffer.byteLength(this._content, "utf-8");
@@ -175,6 +190,19 @@ class Response {
     static text(data) {
         return new this().setContentType("text/plain").setContent(data);
     }
+    /**
+     * Creates a response whose body is streamed.
+     *
+     * @param stream - Node.js readable stream
+     * @param headers - Optional headers to include in the response
+     * @returns A {@link Response} configured for streaming
+     */
+    static stream(stream, headers) {
+        const response = new this().stream(stream);
+        if (headers)
+            response.setHeaders(headers);
+        return response;
+    }
     /**
      * Creates an HTTP redirect response.
      *

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { createApp } from "./app";
-export { Request, Response } from "./http";
+export { Request, Response, Context } from "./http";
 export type { Middleware, RouteHandler } from "./types";
 export { RouterGroup } from "./routing";
 export { FileSessionStorage, MemorySessionStorage, DatabaseSessionStorage, type SessionDatabaseAdapter, } from "./sessions";
@@ -9,5 +9,5 @@ export { StorageType } from "./storage/types";
 export { v, schema, validateRequest } from "./validators/validationSchema";
 export { Hasher, JWT } from "./crypto";
 export { sessions, cors, csrf, rateLimit } from "./middlewares";
+export type { RateLimitStore, RateLimitStoreEntry } from "./middlewares";
 export * from "./exceptions/httpExceptions";
-export * from "./helpers/http";

package/dist/index.js

@@ -14,12 +14,13 @@ 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.rateLimit = exports.csrf = exports.cors = exports.sessions = exports.JWT = exports.Hasher = exports.validateRequest = exports.schema = exports.v = exports.StorageType = exports.createUploader = exports.HttpMethods = exports.DatabaseSessionStorage = exports.MemorySessionStorage = exports.FileSessionStorage = exports.RouterGroup = exports.Response = exports.Request = exports.createApp = void 0;
+exports.rateLimit = exports.csrf = exports.cors = exports.sessions = exports.JWT = exports.Hasher = exports.validateRequest = exports.schema = exports.v = exports.StorageType = exports.createUploader = exports.HttpMethods = exports.DatabaseSessionStorage = exports.MemorySessionStorage = exports.FileSessionStorage = exports.RouterGroup = exports.Context = exports.Response = exports.Request = exports.createApp = void 0;
 var app_1 = require("./app");
 Object.defineProperty(exports, "createApp", { enumerable: true, get: function () { return app_1.createApp; } });
 var http_1 = require("./http");
 Object.defineProperty(exports, "Request", { enumerable: true, get: function () { return http_1.Request; } });
 Object.defineProperty(exports, "Response", { enumerable: true, get: function () { return http_1.Response; } });
+Object.defineProperty(exports, "Context", { enumerable: true, get: function () { return http_1.Context; } });
 var routing_1 = require("./routing");
 Object.defineProperty(exports, "RouterGroup", { enumerable: true, get: function () { return routing_1.RouterGroup; } });
 var sessions_1 = require("./sessions");
@@ -45,4 +46,3 @@ Object.defineProperty(exports, "cors", { enumerable: true, get: function () { re
 Object.defineProperty(exports, "csrf", { enumerable: true, get: function () { return middlewares_1.csrf; } });
 Object.defineProperty(exports, "rateLimit", { enumerable: true, get: function () { return middlewares_1.rateLimit; } });
 __exportStar(require("./exceptions/httpExceptions"), exports);
-__exportStar(require("./helpers/http"), exports);

package/dist/middlewares/cors.d.ts

@@ -1,22 +1,28 @@
-import { HttpMethods } from "../http";
+import { Context, HttpMethods } from "../http";
 import type { Middleware } from "../types";
+/**
+ * Callback contract for dynamic CORS allow/deny decisions.
+ *
+ * Return `true` to allow the current request origin, `false` to deny it.
+ */
+type CorsOriginResolver = (origin: string | undefined, context: Context) => boolean | Promise<boolean>;
 /**
  * CORS middleware configuration options.
  *
  * These options map to standard CORS response headers and preflight behavior.
  */
-interface CorsOptions {
+export 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.
+     * - A function implements custom allow/deny logic.
      *
      * Affects: `Access-Control-Allow-Origin`.
      */
-    origin?: string | string[] | ((origin: string | undefined) => string);
+    origin?: string | string[] | CorsOriginResolver;
     /**
      * HTTP methods allowed for cross-origin requests.
      *

package/dist/middlewares/cors.js

@@ -2,33 +2,50 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.cors = void 0;
 const http_1 = require("../http");
+/**
+ * Normalizes a header that may be represented as `string[]`.
+ *
+ * @param value - Header value.
+ * @returns A single header value or `undefined`.
+ */
+const getHeaderValue = (value) => Array.isArray(value) ? value[0] : value;
 /**
  * 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)
+ * @param context - Current HTTP context.
+ * @param requestOrigin - Incoming `Origin` header value.
+ * @param config - CORS config.
+ * @returns Allowed origin value or `null` when denied/not configured.
  */
-function resolveOrigin(requestOrigin, config) {
+async function resolveOrigin(context, requestOrigin, config) {
     if (!requestOrigin)
         return null;
     const cleanOrigin = (origin) => origin.endsWith("/") ? origin.slice(0, -1) : origin;
     if (typeof config.origin === "function") {
-        return config.origin(requestOrigin) ? requestOrigin : null;
+        const result = config.origin(requestOrigin, context);
+        const isAllowed = result instanceof Promise ? await result : result;
+        return isAllowed ? requestOrigin : null;
+    }
+    if (!config.origin) {
+        return null;
+    }
+    if (typeof config.origin !== "string" && !Array.isArray(config.origin)) {
+        return null;
+    }
+    if (typeof config.origin === "string") {
+        if (config.origin === "*") {
+            return config.credentials ? requestOrigin : "*";
+        }
+        return cleanOrigin(config.origin) === cleanOrigin(requestOrigin)
+            ? requestOrigin
+            : null;
     }
     if (Array.isArray(config.origin)) {
         return config.origin.map(cleanOrigin).includes(cleanOrigin(requestOrigin))
             ? requestOrigin
             : null;
     }
-    if (config.origin === "*") {
-        return config.credentials ? requestOrigin : "*";
-    }
-    return cleanOrigin(config.origin) === cleanOrigin(requestOrigin)
-        ? requestOrigin
-        : null;
+    return null;
 }
 /**
  * Native CORS middleware, generates a CORS configuration for the server.
@@ -50,7 +67,7 @@ function resolveOrigin(requestOrigin, config) {
  */
 const cors = (options = {}) => {
     const config = {
-        origin: options.origin ?? "*",
+        origin: options.origin,
         methods: options.methods ?? [
             http_1.HttpMethods.get,
             http_1.HttpMethods.post,
@@ -65,8 +82,8 @@ const cors = (options = {}) => {
         maxAge: options.maxAge ?? 86400,
         preflightContinue: options.preflightContinue ?? false,
     };
-    return async (request, next) => {
-        const allowedOrigin = resolveOrigin(request.headers.origin, config);
+    return async (context, next) => {
+        const allowedOrigin = await resolveOrigin(context, getHeaderValue(context.headers.origin), config);
         const corsHeaders = {};
         if (allowedOrigin) {
             corsHeaders["Access-Control-Allow-Origin"] = allowedOrigin;
@@ -78,7 +95,7 @@ const cors = (options = {}) => {
         if (config.exposedHeaders.length)
             corsHeaders["Access-Control-Expose-Headers"] =
                 config.exposedHeaders.join(", ");
-        if (request.method === http_1.HttpMethods.options) {
+        if (context.req.method === http_1.HttpMethods.options) {
             corsHeaders["Access-Control-Allow-Methods"] = config.methods.join(", ");
             corsHeaders["Access-Control-Allow-Headers"] =
                 config.allowedHeaders.join(", ");
@@ -89,7 +106,7 @@ const cors = (options = {}) => {
                     .setContent(null)
                     .setHeaders(corsHeaders);
         }
-        const response = await next(request);
+        const response = await next(context);
         for (const [key, value] of Object.entries(corsHeaders)) {
             response.setHeader(key, value);
         }

package/dist/middlewares/csrf.js

@@ -16,7 +16,7 @@ const defaultTokenGenerator = () => (0, node_crypto_1.randomBytes)(32).toString(
  * Normalizes an origin-like string by removing trailing slashes.
  *
  * This helps make origin comparisons stable across minor formatting differences
- * (e.g. `https://example.com/` vs `https://example.com`).
+ * (e.g. `scheme://host/` vs `scheme://host`).
  *
  * @param value - Origin string to normalize.
  * @returns Normalized origin string without trailing slashes.
@@ -61,8 +61,8 @@ const buildConfig = (options) => ({
  * @param headerName - Header key to read (as stored in `request.headers`).
  * @returns The header value if exactly one is present, otherwise `null`.
  */
-function getSingleHeaderValue(request, headerName) {
-    const value = request.headers[headerName];
+function getSingleHeaderValue(context, headerName) {
+    const value = context.headers[headerName];
     if (!value)
         return null;
     if (Array.isArray(value)) {
@@ -86,8 +86,8 @@ function getSingleHeaderValue(request, headerName) {
  * @param headerName - Header key to inspect.
  * @returns `true` if duplicates/invalid array form exist, otherwise `false`.
  */
-const hasInvalidDuplicateHeader = (request, headerName) => Array.isArray(request.headers[headerName]) &&
-    request.headers[headerName].length !== 1;
+const hasInvalidDuplicateHeader = (context, headerName) => Array.isArray(context.headers[headerName]) &&
+    context.headers[headerName].length !== 1;
 /**
  * Extracts a CSRF token from the first matching header in `headerNames`.
  *
@@ -98,9 +98,9 @@ const hasInvalidDuplicateHeader = (request, headerName) => Array.isArray(request
  * @param headerNames - List of candidate header names to check.
  * @returns The token value if found, otherwise `null`.
  */
-function getHeaderToken(request, headerNames) {
+function getHeaderToken(context, headerNames) {
     for (const headerName of headerNames) {
-        const value = getSingleHeaderValue(request, headerName);
+        const value = getSingleHeaderValue(context, headerName);
         if (value)
             return value;
     }
@@ -135,11 +135,11 @@ function safeCompare(a, b) {
  * @param request - Incoming request.
  * @returns `true` if HTTPS is inferred, otherwise `false`.
  */
-function isHttpsRequest(request) {
-    const forwardedProto = getSingleHeaderValue(request, "x-forwarded-proto");
+function isHttpsRequest(context) {
+    const forwardedProto = getSingleHeaderValue(context, "x-forwarded-proto");
     if (forwardedProto?.split(",")[0]?.trim().toLowerCase() === "https")
         return true;
-    const forwarded = getSingleHeaderValue(request, "forwarded");
+    const forwarded = getSingleHeaderValue(context, "forwarded");
     if (forwarded?.toLowerCase().includes("proto=https"))
         return true;
     return false;
@@ -152,10 +152,10 @@ function isHttpsRequest(request) {
  *
  * @param request - Incoming request.
  * @param isHttps - Whether the request is considered HTTPS.
- * @returns An origin string like `https://example.com`, or `null` if `Host` is missing.
+ * @returns An origin string like `scheme://host`, or `null` if `Host` is missing.
  */
-function inferRequestOrigin(request, isHttps) {
-    const host = getSingleHeaderValue(request, "host");
+function inferRequestOrigin(context, isHttps) {
+    const host = getSingleHeaderValue(context, "host");
     if (!host)
         return null;
     return `${isHttps ? "https" : "http"}://${host}`;
@@ -164,7 +164,7 @@ function inferRequestOrigin(request, isHttps) {
  * Extracts the origin (scheme + host + port) from a Referer header value.
  *
  * @param referer - The raw Referer header.
- * @returns The parsed origin (e.g., `https://example.com`) or `null` if invalid.
+ * @returns The parsed origin (e.g., `scheme://host`) or `null` if invalid.
  */
 function extractOriginFromReferer(referer) {
     try {
@@ -185,12 +185,12 @@ function extractOriginFromReferer(referer) {
  * @param headerNames - Token header names to validate for duplication.
  * @returns An error message string, or `null` if headers look safe.
  */
-function validateDuplicateSecurityHeaders(request, headerNames) {
-    if (headerNames.some(headerName => hasInvalidDuplicateHeader(request, headerName))) {
+function validateDuplicateSecurityHeaders(context, headerNames) {
+    if (headerNames.some(headerName => hasInvalidDuplicateHeader(context, headerName))) {
         return "Invalid CSRF token header format";
     }
-    if (hasInvalidDuplicateHeader(request, "origin") ||
-        hasInvalidDuplicateHeader(request, "referer")) {
+    if (hasInvalidDuplicateHeader(context, "origin") ||
+        hasInvalidDuplicateHeader(context, "referer")) {
         return "Invalid Origin/Referer headers";
     }
     return null;
@@ -202,15 +202,15 @@ function validateDuplicateSecurityHeaders(request, headerNames) {
  * @param config - Resolved CSRF configuration.
  * @returns An error message string, or `null` if origin is acceptable.
  */
-function validateOriginHeaders(request, config) {
+function validateOriginHeaders(context, config) {
     if (!config.validateOrigin)
         return null;
-    const httpsRequest = isHttpsRequest(request);
-    const inferredOrigin = inferRequestOrigin(request, httpsRequest);
+    const httpsRequest = isHttpsRequest(context);
+    const inferredOrigin = inferRequestOrigin(context, httpsRequest);
     const allowedOrigins = config.allowedOrigins ??
         (inferredOrigin ? [normalizeOrigin(inferredOrigin)] : []);
-    const originHeader = getSingleHeaderValue(request, "origin");
-    const refererHeader = getSingleHeaderValue(request, "referer");
+    const originHeader = getSingleHeaderValue(context, "origin");
+    const refererHeader = getSingleHeaderValue(context, "referer");
     if (!originHeader &&
         httpsRequest &&
         config.requireRefererOnHttps &&
@@ -245,9 +245,9 @@ function validateOriginHeaders(request, config) {
  * @param expectedToken - The server-issued token (typically from cookie or generator).
  * @returns An error message string, or `null` if the token is valid.
  */
-function validateCsrfToken(request, config, expectedToken) {
-    const tokenFromHeader = getHeaderToken(request, config.headerNames);
-    const tokenFromBody = request.body[config.bodyField];
+function validateCsrfToken(context, config, expectedToken) {
+    const tokenFromHeader = getHeaderToken(context, config.headerNames);
+    const tokenFromBody = context.body[config.bodyField];
     const providedToken = tokenFromHeader ?? tokenFromBody;
     if (typeof providedToken !== "string" ||
         !safeCompare(expectedToken, providedToken)) {
@@ -290,9 +290,9 @@ const buildForbiddenResponse = (message) => {
  */
 const csrf = (options = {}) => {
     const config = buildConfig(options);
-    return async (request, next) => {
-        const methodRequiresCheck = config.protectedMethods.includes(request.method);
-        const tokenFromCookie = request.cookies[config.cookieName];
+    return async (context, next) => {
+        const methodRequiresCheck = config.protectedMethods.includes(context.req.method);
+        const tokenFromCookie = context.cookies[config.cookieName];
         const issuedToken = tokenFromCookie || config.tokenGenerator();
         const appendCsrfCookie = (response) => {
             if (!tokenFromCookie) {
@@ -301,14 +301,14 @@ const csrf = (options = {}) => {
             return response;
         };
         if (methodRequiresCheck) {
-            const validationError = validateDuplicateSecurityHeaders(request, config.headerNames) ??
-                validateOriginHeaders(request, config) ??
-                validateCsrfToken(request, config, issuedToken);
+            const validationError = validateDuplicateSecurityHeaders(context, config.headerNames) ??
+                validateOriginHeaders(context, config) ??
+                validateCsrfToken(context, config, issuedToken);
             if (validationError) {
                 return appendCsrfCookie(buildForbiddenResponse(validationError));
             }
         }
-        const response = await next(request);
+        const response = await next(context);
         return appendCsrfCookie(response);
     };
 };

package/dist/middlewares/index.d.ts

@@ -1,4 +1,4 @@
 export { cors } from "./cors";
 export { sessions } from "./session";
 export { csrf } from "./csrf";
-export { rateLimit } from "./rateLimiter";
+export { rateLimit, type RateLimitStore, type RateLimitStoreEntry, } from "./rateLimiter";

package/dist/middlewares/rateLimiter.d.ts

@@ -1,9 +1,41 @@
-import { Request, Response } from "../http";
-import type { Middleware } from "../types";
+import { Context } from "../http";
+import type { Middleware, RouteHandler } from "../types";
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * Mutable counter entry for a single rate-limit key.
+ */
+export interface RateLimitStoreEntry {
+    /** Requests performed in the current window. */
+    count: number;
+    /** Absolute timestamp (ms) when the current window expires. */
+    resetTime: number;
+}
+/**
+ * Pluggable store contract for rate limiting.
+ *
+ * Use a shared implementation (e.g. Redis) in multi-instance deployments.
+ */
+export interface RateLimitStore {
+    /**
+     * Increments the counter for `key` in the active window.
+     *
+     * @param key - Unique client key.
+     * @param windowMs - Active window size in milliseconds.
+     * @param now - Current unix timestamp in milliseconds.
+     * @returns Updated counter entry for the key.
+     */
+    increment(key: string, windowMs: number, now: number): MaybePromise<RateLimitStoreEntry>;
+    /**
+     * Optional cleanup hook for removing expired entries.
+     *
+     * @param now - Current unix timestamp in milliseconds.
+     */
+    cleanup?(now: number): MaybePromise<void>;
+}
 /**
  * Rate limit middleware configuration.
  */
-interface RateLimitOptions {
+export interface RateLimitOptions {
     /**
      * Time window in milliseconds where requests are counted.
      * @default 60000
@@ -26,11 +58,31 @@ interface RateLimitOptions {
     /**
      * Resolves the identity key used for counting requests.
      */
-    keyGenerator?: (request: Request) => string;
+    keyGenerator?: (context: Context) => string;
+    /**
+     * Trusts proxy-provided IP headers (`x-forwarded-for`, `x-real-ip`,
+     * `cf-connecting-ip`) in the default key generator.
+     * @default false
+     */
+    trustProxy?: boolean;
+    /**
+     * Custom store implementation. Defaults to in-memory store.
+     */
+    store?: RateLimitStore;
+    /**
+     * Periodic cleanup interval for stores that support `cleanup`.
+     * @default windowMs
+     */
+    cleanupIntervalMs?: number;
+    /**
+     * Max number of keys retained by the built-in in-memory store.
+     * @default 50000
+     */
+    maxKeys?: number;
     /**
      * Optional predicate to skip rate limiting for selected requests.
      */
-    skip?: (request: Request) => boolean | Promise<boolean>;
+    skip?: (context: Context) => boolean | Promise<boolean>;
     /**
      * Includes `RateLimit-*` response headers.
      * @default true
@@ -44,7 +96,7 @@ interface RateLimitOptions {
     /**
      * Optional custom handler executed when the limit is exceeded.
      */
-    handler?: (request: Request) => Response | Promise<Response>;
+    handler?: RouteHandler;
 }
 /**
  * Creates a configurable request rate-limiting middleware.