skyguard-js 1.1.2 → 1.1.3

package/README.md

@@ -242,7 +242,20 @@ To handle sessions, you must use the framework’s built-in middleware. Dependin
 import { sessions } from "skyguard-js/middlewares";
 import { FileSessionStorage } from "skyguard-js";
 
-app.middlewares([sessions(FileSessionStorage)]);
+app.middlewares([
+  sessions(FileSessionStorage, {
+    name: "connect.sid",
+    rolling: true,
+    saveUninitialized: false,
+    cookie: {
+      maxAge: 60 * 60 * 24,
+      httpOnly: true,
+      sameSite: "Lax",
+      secure: false,
+      path: "/",
+    },
+  }),
+]);
 
 app.post("/login", (request: Request) => {
   const { username, password } = request.data;
@@ -300,10 +313,25 @@ app.post("/login", async (request: Request) => {
     throw new UnauthorizedError("Invalid credentials");
   }
 
-  const token = createJWT({ sub: user.id, role: user.role }, "1h");
+  const token = createJWT(
+    { sub: user.id, role: user.role },
+    "secret-key",
+    3600,
+  );
 
   return Response.json({ token });
 });
+
+app.get(
+  "/verify-jwt",
+  (request: Request) => {
+    // The request stores a user state; the middleware creates and assigns this state to the request.state object.
+    const user = request.state.user;
+
+    return json({ user });
+  },
+  [authJWT("secret-key")],
+);
 ```
 
 ---
@@ -318,7 +346,9 @@ import { createUploader, StorageType } from "skyguard-js";
 const uploader = createUploader({
   storageType: StorageType.DISK,
   storageOptions: {
-    destination: "./uploads",
+    disk: {
+      destination: "./uploads",
+    },
   },
 });
 
@@ -334,6 +364,8 @@ app.post(
 );
 ```
 
+Depending on the `Storage Type` you have selected, the storage options will contain two properties: `disk` and `memory`
+
 ---
 
 ## 📄 Views & Template Engine

package/dist/app.js

@@ -50,8 +50,8 @@ class App {
      */
     static bootstrap() {
         const app = container_1.Container.singleton(App);
-        app.router = new routing_1.Router();
-        app.logger = new http_1.Logger();
+        app.router = container_1.Container.singleton(routing_1.Router);
+        app.logger = container_1.Container.singleton(http_1.Logger);
         app.viewEngine = container_1.Container.singleton(engineTemplate_1.ViewEngine);
         return app;
     }
@@ -228,6 +228,7 @@ class App {
             statusCode: 500,
             message: "Internal Server Error",
         }).setStatusCode(500));
+        // eslint-disable-next-line no-console
         console.error(error);
     }
 }

package/dist/crypto/jwt.d.ts

@@ -8,24 +8,38 @@ interface JWTHeader {
     typ: string;
 }
 /**
- * Crea un JSON Web Token
- * @param payload - Datos a incluir en el token
- * @param secret - Clave secreta para firmar
- * @param expiresIn - Tiempo de expiración en segundos (opcional)
- * @returns JWT string
+ * Creates a JSON Web Token (JWT) signed using HMAC-SHA256 (HS256).
+ *
+ * Note:
+ * This implementation produces **stateless signed tokens** and does not
+ * encrypt the payload. Anyone can decode the payload, but only holders of
+ * the secret can generate a valid signature.
+ *
+ * @param payload - Custom claims to include in the token.
+ * @param secret - Secret key used to sign the token.
+ * @param expiresIn - Optional expiration time in seconds.
+ * @returns Signed JWT string.
  */
 export declare const createJWT: (payload: JWTPayload, secret: string, expiresIn?: number) => string;
 /**
- * Verifica y decodifica un JSON Web Token
- * @param token - JWT a verificar
- * @param secret - Clave secreta usada para firmar
- * @returns Payload decodificado o null si es inválido
+ * Verifies the integrity and validity of a JSON Web Token.
+ *
+ * If any validation step fails, the function returns `null`.
+ *
+ * @param token - JWT string to verify.
+ * @param secret - Secret used to sign the token.
+ * @returns Decoded payload if the token is valid, otherwise `null`.
  */
 export declare const verifyJWT: (token: string, secret: string) => JWTPayload | null;
 /**
- * Decodifica un JWT sin verificar la firma (útil para debugging)
- * @param token - JWT a decodificar
- * @returns Objeto con header y payload decodificados
+ * Decodes a JWT without verifying its signature.
+ *
+ * ⚠️ Security warning:
+ * This function MUST NOT be used for authentication or authorization.
+ * It is intended only for debugging, logging, or inspecting token contents.
+ *
+ * @param token - JWT string to decode.
+ * @returns Object containing decoded header and payload, or `null` if malformed.
  */
 export declare const decodeJWT: (token: string) => {
     header: JWTHeader;

package/dist/crypto/jwt.js

@@ -3,7 +3,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.decodeJWT = exports.verifyJWT = exports.createJWT = void 0;
 const node_crypto_1 = require("node:crypto");
 /**
- * Codifica en Base64URL (sin padding)
+ * Encodes a string using Base64URL encoding (RFC 7515).
+ *
+ * This format is required by JWT to ensure the token is URL-safe.
+ *
+ * @param str - UTF-8 string to encode.
+ * @returns Base64URL encoded string without padding.
  */
 function base64UrlEncode(str) {
     return Buffer.from(str)
@@ -13,7 +18,13 @@ function base64UrlEncode(str) {
         .replace(/=/g, "");
 }
 /**
- * Decodifica desde Base64URL
+ * Decodes a Base64URL string back to a UTF-8 string.
+ *
+ * The function restores the standard Base64 alphabet and padding
+ * before performing the decoding.
+ *
+ * @param str - Base64URL encoded string.
+ * @returns Decoded UTF-8 string.
  */
 function base64UrlDecode(str) {
     let base64 = str.replace(/-/g, "+").replace(/_/g, "/");
@@ -23,11 +34,17 @@ function base64UrlDecode(str) {
     return Buffer.from(base64, "base64").toString("utf-8");
 }
 /**
- * Crea un JSON Web Token
- * @param payload - Datos a incluir en el token
- * @param secret - Clave secreta para firmar
- * @param expiresIn - Tiempo de expiración en segundos (opcional)
- * @returns JWT string
+ * Creates a JSON Web Token (JWT) signed using HMAC-SHA256 (HS256).
+ *
+ * Note:
+ * This implementation produces **stateless signed tokens** and does not
+ * encrypt the payload. Anyone can decode the payload, but only holders of
+ * the secret can generate a valid signature.
+ *
+ * @param payload - Custom claims to include in the token.
+ * @param secret - Secret key used to sign the token.
+ * @param expiresIn - Optional expiration time in seconds.
+ * @returns Signed JWT string.
  */
 const createJWT = (payload, secret, expiresIn) => {
     const header = {
@@ -50,33 +67,37 @@ const createJWT = (payload, secret, expiresIn) => {
         .replace(/\+/g, "-")
         .replace(/\//g, "_")
         .replace(/=/g, "");
-    // Retornar JWT completo
     return `${data}.${signature}`;
 };
 exports.createJWT = createJWT;
 /**
- * Verifica y decodifica un JSON Web Token
- * @param token - JWT a verificar
- * @param secret - Clave secreta usada para firmar
- * @returns Payload decodificado o null si es inválido
+ * Verifies the integrity and validity of a JSON Web Token.
+ *
+ * If any validation step fails, the function returns `null`.
+ *
+ * @param token - JWT string to verify.
+ * @param secret - Secret used to sign the token.
+ * @returns Decoded payload if the token is valid, otherwise `null`.
  */
 const verifyJWT = (token, secret) => {
-    const parts = token.split(".");
-    if (parts.length !== 3)
-        return null;
-    const [encodedHeader, encodedPayload, signature] = parts;
-    const data = `${encodedHeader}.${encodedPayload}`;
-    const expectedSignature = (0, node_crypto_1.createHmac)("sha256", secret)
-        .update(data)
-        .digest("base64")
-        .replace(/\+/g, "-")
-        .replace(/\//g, "_")
-        .replace(/=/g, "");
-    const signatureBuffer = Buffer.from(signature);
-    const computedBuffer = Buffer.from(expectedSignature);
-    if (!(0, node_crypto_1.timingSafeEqual)(signatureBuffer, computedBuffer))
-        return null;
     try {
+        const parts = token.split(".");
+        if (parts.length !== 3)
+            return null;
+        const [encodedHeader, encodedPayload, signature] = parts;
+        const data = `${encodedHeader}.${encodedPayload}`;
+        const expectedSignature = (0, node_crypto_1.createHmac)("sha256", secret)
+            .update(data)
+            .digest("base64")
+            .replace(/\+/g, "-")
+            .replace(/\//g, "_")
+            .replace(/=/g, "");
+        const signatureBuffer = Buffer.from(signature);
+        const computedBuffer = Buffer.from(expectedSignature);
+        if (signatureBuffer.length !== computedBuffer.length)
+            return null;
+        if (!(0, node_crypto_1.timingSafeEqual)(signatureBuffer, computedBuffer))
+            return null;
         const payload = JSON.parse(base64UrlDecode(encodedPayload));
         if (!payload.exp)
             return null;
@@ -91,9 +112,14 @@ const verifyJWT = (token, secret) => {
 };
 exports.verifyJWT = verifyJWT;
 /**
- * Decodifica un JWT sin verificar la firma (útil para debugging)
- * @param token - JWT a decodificar
- * @returns Objeto con header y payload decodificados
+ * Decodes a JWT without verifying its signature.
+ *
+ * ⚠️ Security warning:
+ * This function MUST NOT be used for authentication or authorization.
+ * It is intended only for debugging, logging, or inspecting token contents.
+ *
+ * @param token - JWT string to decode.
+ * @returns Object containing decoded header and payload, or `null` if malformed.
  */
 const decodeJWT = (token) => {
     try {

package/dist/http/request.d.ts

@@ -55,6 +55,18 @@ export declare class Request {
     setData(data: Record<string, any>): this;
     get session(): Session;
     setSession(session: Session): void;
+    /**
+     * Returns all request cookies as a key-value object.
+     */
+    get cookies(): Record<string, string>;
+    /**
+     * Returns a cookie value by name.
+     */
+    getCookie(name: string): string | undefined;
+    /**
+     * Checks whether a cookie exists.
+     */
+    hasCookie(name: string): boolean;
     /**
      * Validates the request payload against a validation schema.
      *

package/dist/http/request.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Request = void 0;
 const validators_1 = require("../validators");
+const cookies_1 = require("../sessions/cookies");
 /**
  * Represents an incoming client request within the framework.
  *
@@ -87,6 +88,24 @@ class Request {
     setSession(session) {
         this._session = session;
     }
+    /**
+     * Returns all request cookies as a key-value object.
+     */
+    get cookies() {
+        return (0, cookies_1.parseCookies)(this._headers?.cookie);
+    }
+    /**
+     * Returns a cookie value by name.
+     */
+    getCookie(name) {
+        return this.cookies[name];
+    }
+    /**
+     * Checks whether a cookie exists.
+     */
+    hasCookie(name) {
+        return name in this.cookies;
+    }
     /**
      * Validates the request payload against a validation schema.
      *

package/dist/http/response.d.ts

@@ -1,4 +1,5 @@
 import type { Headers } from "../types";
+import { type CookieOptions } from "../sessions/cookies";
 /**
  * Represents an outgoing response sent to the client.
  *
@@ -35,6 +36,14 @@ export declare class Response {
     private merge;
     setHeader(header: string, value: string): this;
     removeHeader(header: string): void;
+    /**
+     * Sets a cookie in the `Set-Cookie` response header.
+     */
+    setCookie(name: string, value: string, options?: CookieOptions): this;
+    /**
+     * Clears a cookie by setting an empty value and immediate expiration.
+     */
+    removeCookie(name: string, options?: CookieOptions): this;
     /**
      * Semantic shortcut to define the `Content-Type` header.
      *

package/dist/http/response.js

@@ -6,6 +6,7 @@ const invalidHttpStatusException_1 = require("../exceptions/invalidHttpStatusExc
 const fileDownload_1 = require("../static/fileDownload");
 const engineTemplate_1 = require("../views/engineTemplate");
 const container_1 = require("../container/container");
+const cookies_1 = require("../sessions/cookies");
 /**
  * Represents an outgoing response sent to the client.
  *
@@ -62,6 +63,32 @@ class Response {
     removeHeader(header) {
         delete this._headers[header];
     }
+    /**
+     * Sets a cookie in the `Set-Cookie` response header.
+     */
+    setCookie(name, value, options = {}) {
+        const cookie = (0, cookies_1.serializeCookie)(name, value, options);
+        const current = this._headers["Set-Cookie"];
+        if (!current) {
+            this._headers["Set-Cookie"] = cookie;
+            return this;
+        }
+        if (Array.isArray(current)) {
+            this._headers["Set-Cookie"] = [...current, cookie];
+            return this;
+        }
+        this._headers["Set-Cookie"] = [current, cookie];
+        return this;
+    }
+    /**
+     * Clears a cookie by setting an empty value and immediate expiration.
+     */
+    removeCookie(name, options = {}) {
+        return this.setCookie(name, "", {
+            ...options,
+            maxAge: 0,
+        });
+    }
     /**
      * Semantic shortcut to define the `Content-Type` header.
      *

package/dist/middlewares/cors.d.ts

@@ -1,22 +1,5 @@
 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.
  *
@@ -33,7 +16,7 @@ interface CorsOptions {
      *
      * Affects: `Access-Control-Allow-Origin`.
      */
-    origin?: CorsOrigin;
+    origin?: string | string[] | ((origin: string | undefined) => string);
     /**
      * HTTP methods allowed for cross-origin requests.
      *

package/dist/middlewares/session.d.ts

@@ -1,26 +1,48 @@
-import { type SessionStorage, type CookieOptions } from "../sessions";
+import { type SessionStorage } from "../sessions";
+import { type CookieOptions } from "../sessions/cookies";
 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.
+ * Options inspired by express-session and adapted to Skyguard.
+ */
+export interface SessionOptions {
+    /**
+     * Name of the cookie that carries the session id.
+     * @default "connect.sid"
+     */
+    name?: string;
+    /**
+     * Enables issuing a fresh session cookie on every response.
+     * @default false
+     */
+    rolling?: boolean;
+    /**
+     * Save a cookie even if the session was never initialized with data.
+     * @default false
+     */
+    saveUninitialized?: boolean;
+    /**
+     * Session cookie attributes.
+     */
+    cookie?: CookieOptions;
+}
+/**
+ * Session lifecycle middleware.
+ *
+ * API inspired by `express-session`, adapted to the Skyguard architecture.
  *
- * @param StorageClass - `SessionStorage` implementation
- * @param options - Session cookie configuration
- * @returns Session middleware
+ * Cookie emission rules:
+ * - A cookie is set when a session id exists AND at least one of the following is true:
+ *   - `rolling` is enabled (refresh cookie every request),
+ *   - `saveUninitialized` is enabled (always create/set cookie when no prior session),
+ *   - the session was created during this request.
  *
- * @example
- * app.middlewares([
- *   sessionMiddleware(MemorySessionStorage, {
- *     cookieName: "sid",
- *     maxAge: 86400,
- *   }),
- * ]);
+ * @param StorageClass - Session storage constructor used per request.
+ * @param options - Raw session middleware options.
+ * @returns A Skyguard `Middleware` that manages session load/save and cookie IO.
  */
-export declare const sessions: (StorageClass: SessionStorageConstructor, options?: CookieOptions) => Middleware;
+export declare const sessions: (StorageClass: SessionStorageConstructor, options?: SessionOptions) => Middleware;
 export {};

package/dist/middlewares/session.js

@@ -2,85 +2,87 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.sessions = void 0;
 const sessions_1 = require("../sessions");
+const cookies_1 = require("../sessions/cookies");
+const httpExceptions_1 = require("../exceptions/httpExceptions");
 /**
- * Parses the `Cookie` header into a key/value object.
+ * Attempts to load a session from a cookie value into the provided storage.
  *
- * @param cookieHeader - Raw `Cookie` header value
- * @returns Parsed cookies
+ * If `cookieValue` is missing, this is a no-op.
  *
- * @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.
+ * If the storage rejects with `UnauthorizedError` (e.g., invalid or expired session),
+ * the error is swallowed and the request proceeds as unauthenticated/uninitialized.
  *
- * @param sessionId - Session identifier
- * @param config - Fully resolved cookie configuration
- * @returns Value ready to be used in `Set-Cookie`
+ * Any other error type is treated as unexpected and is re-thrown.
  *
- * @example
- * buildSessionCookie("abc123", config);
- * // "session_id=abc123; Max-Age=86400; Path=/; SameSite=Lax; HttpOnly"
+ * @param storage - Session storage instance used to load the session.
+ * @param cookieValue - Session id extracted from the request cookie.
+ * @throws Unknown errors coming from the storage layer (non-UnauthorizedError).
  */
-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("; ");
+async function loadSessionFromCookie(storage, cookieValue) {
+    if (!cookieValue)
+        return;
+    try {
+        await storage.load(cookieValue);
+    }
+    catch (error) {
+        if (error instanceof httpExceptions_1.UnauthorizedError)
+            return;
+        throw error;
+    }
 }
 /**
- * Session lifecycle middleware implementation.
+ * Session lifecycle middleware.
+ *
+ * API inspired by `express-session`, adapted to the Skyguard architecture.
  *
- * @param StorageClass - `SessionStorage` implementation
- * @param options - Session cookie configuration
- * @returns Session middleware
+ * Cookie emission rules:
+ * - A cookie is set when a session id exists AND at least one of the following is true:
+ *   - `rolling` is enabled (refresh cookie every request),
+ *   - `saveUninitialized` is enabled (always create/set cookie when no prior session),
+ *   - the session was created during this request.
  *
- * @example
- * app.middlewares([
- *   sessionMiddleware(MemorySessionStorage, {
- *     cookieName: "sid",
- *     maxAge: 86400,
- *   }),
- * ]);
+ * @param StorageClass - Session storage constructor used per request.
+ * @param options - Raw session middleware options.
+ * @returns A Skyguard `Middleware` that manages session load/save and cookie IO.
  */
 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 ?? "/",
+        name: options.name ?? "connect.sid",
+        rolling: options.rolling ?? false,
+        saveUninitialized: options.saveUninitialized ?? false,
+        cookie: {
+            maxAge: options.cookie?.maxAge ?? 86400,
+            httpOnly: options.cookie?.httpOnly ?? true,
+            secure: options.cookie?.secure ?? false,
+            sameSite: options.cookie?.sameSite ?? "Lax",
+            path: options.cookie?.path ?? "/",
+        },
     };
     return async (request, next) => {
-        const cookies = parseCookies(request.headers.cookie || "");
-        const sessionId = cookies[config.cookieName];
-        const storage = new StorageClass(options.maxAge || timeMaxAge);
-        if (sessionId)
-            await storage.load(sessionId);
+        const cookies = (0, cookies_1.parseCookies)(request.headers.cookie);
+        const sessionIdFromCookie = cookies[config.name];
+        const storage = new StorageClass(config.cookie.maxAge);
+        await loadSessionFromCookie(storage, sessionIdFromCookie);
         const session = new sessions_1.Session(storage);
         request.setSession(session);
+        const sessionIdBefore = storage.id();
+        if (!sessionIdBefore && config.saveUninitialized)
+            await storage.start();
         const response = await next(request);
-        if (storage.id()) {
-            const cookieValue = buildSessionCookie(storage.id(), config);
-            response.setHeader("Set-Cookie", cookieValue);
+        const sessionIdAfter = storage.id();
+        if (sessionIdAfter && config.rolling)
+            await storage.touch();
+        const sessionWasCreated = !sessionIdBefore && Boolean(sessionIdAfter);
+        const shouldSetCookie = Boolean(sessionIdAfter) &&
+            (config.rolling || config.saveUninitialized || sessionWasCreated);
+        if (shouldSetCookie && sessionIdAfter) {
+            response.setHeader("Set-Cookie", (0, cookies_1.serializeCookie)(config.name, sessionIdAfter, {
+                maxAge: config.cookie.maxAge,
+                path: config.cookie.path,
+                httpOnly: config.cookie.httpOnly,
+                secure: config.cookie.secure,
+                sameSite: config.cookie.sameSite,
+            }));
         }
         return response;
     };

package/dist/parsers/jsonParser.js

@@ -2,7 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.JsonParser = void 0;
 const httpExceptions_1 = require("../exceptions/httpExceptions");
-const parserInterface_1 = require("./parserInterface");
 /**
  * JSON content parser.
  *
@@ -10,7 +9,7 @@ const parserInterface_1 = require("./parserInterface");
  */
 class JsonParser {
     canParse(contentType) {
-        return contentType.includes(parserInterface_1.contentTypes["application-json"]);
+        return contentType.includes("application/json");
     }
     parse(body) {
         try {

package/dist/parsers/multipartParser.d.ts

@@ -1,5 +1,5 @@
 import type { ContentParser } from "./contentParser";
-import { type MultipartData } from "./parserInterface";
+import type { MultipartData } from "./parserInterface";
 /**
  * `multipart/form-data` content parser.
  *