skyguard-js 1.1.7 → 1.2.0

package/README.md

@@ -6,6 +6,7 @@
 
 [![NPM Version](https://img.shields.io/npm/v/skyguard-js)](https://www.npmjs.com/package/skyguard-js)
 [![Deployment Pipeline](https://github.com/Pipe930/Skyguard-js/actions/workflows/pipeline.yml/badge.svg)](https://github.com/Pipe930/Skyguard-js/actions/workflows/pipeline.yml)
+[![Socket Badge](https://badge.socket.dev/npm/package/skyguard-js/1.1.8)](https://badge.socket.dev/npm/package/skyguard-js/1.1.8)
 
 **Skyguard.js** is a **lightweight, dependency-free web framework** built entirely with **TypeScript**.
 
@@ -32,10 +33,11 @@ Skyguard.js currently delivers a solid core that includes **routing**, **type-sa
 - Global, group, and route-level middlewares
 - Request / Response abstractions
 - Declarative data validation
-- Simple template engine with layouts and helpers
+- Support for template motors (handlebars, pugs, ejs, etc.)
 - Built-in HTTP exceptions
 - Password hashing and JWT token generation
 - CORS middleware
+- CSRF middleware protection
 - File uploads (via middleware)
 - Static file serving
 - Session handling (via middleware)
@@ -44,6 +46,24 @@ Skyguard.js currently delivers a solid core that includes **routing**, **type-sa
 
 ## 📦 Installation
 
+You need to have [NodeJS](https://nodejs.org/) version 22 or later installed.
+
+Create the `package.json` file to start a new [NodeJS](https://nodejs.org/) project using the `npm init` command.
+
+After configuring the package.json, install [Typescript](https://www.typescriptlang.org/).
+
+```bash
+npm install typescript -D
+```
+
+After installing [Typescript](https://www.typescriptlang.org/) in your project, you need to create the [Typescript](https://www.typescriptlang.org/) configuration file `tsconfig.json`.
+
+```bash
+npx tsc --init
+```
+
+Now that [Typescript](https://www.typescriptlang.org/) is configured, we can install the library. Since it's a module that's in the [NPM Registry](https://www.npmjs.com/), we use the npm package manager.
+
 ```bash
 npm install skyguard-js
 ```
@@ -68,9 +88,6 @@ app.run(PORT, () => {
 });
 ```
 
-> [!NOTE]
-> It is recommended to develop with `TypeScript` for a more secure and efficient development process; the framework already has native support for `TypeScript` and includes the necessary types.
-
 ---
 
 ## 🛣️ Routing
@@ -97,8 +114,8 @@ Route groups allow you to organize endpoints under a shared prefix.
 
 ```ts
 app.group("/api", api => {
-  api.get("/users", () => Response.json({ message: "Users" }));
-  api.get("/products", () => Response.json({ message: "Products" }));
+  api.get("/users", () => res.json({ message: "Users" }));
+  api.get("/products", () => res.json({ message: "Products" }));
 });
 ```
 
@@ -109,30 +126,30 @@ app.group("/api", api => {
 Middlewares can be registered **globally**, **per group**, or **per route**.
 
 ```ts
-import { Request, Response, RouteHandler } from "skyguard-js";
+import { Request, Response, json, RouteHandler } from "skyguard-js";
 
 const authMiddleware = async (
   request: Request,
   next: RouteHandler,
 ): Promise<Response> => {
   if (request.headers["authorization"] !== "secret") {
-    return Response.json({ message: "Unauthorized" }).setStatus(401);
+    return json({ message: "Unauthorized" }).setStatus(401);
   }
 
   return next(request);
 };
 
 // Global middleware
-app.middlewares([authMiddleware]);
+app.middlewares(authMiddleware);
 
 // Group middleware
 app.group("/admin", admin => {
-  admin.middlewares([authMiddleware]);
-  admin.get("/dashboard", () => Response.json({ ok: true }));
+  admin.middlewares(authMiddleware);
+  admin.get("/dashboard", () => json({ ok: true }));
 });
 
 // Route-level middleware
-app.get("/secure", () => Response.json({ secure: true }), [authMiddleware]);
+app.get("/secure", () => json({ secure: true }), [authMiddleware]);
 ```
 
 ---
@@ -144,14 +161,135 @@ To enable CORS, use the built-in `cors` middleware.
 ```ts
 import { cors, HttpMethods } from "skyguard-js";
 
-app.middlewares([
+app.middlewares(
   cors({
     origin: ["http://localhost:3000", "https://myapp.com"],
     methods: [HttpMethods.get, HttpMethods.post],
     allowedHeaders: ["Content-Type", "Authorization"],
     credentials: true,
   }),
-]);
+);
+```
+
+---
+
+## 🛡️ CSRF Middleware
+
+Use the built-in `csrf` middleware to protect endpoints against CSRF attacks.
+
+```ts
+import { csrf, json } from "skyguard-js";
+
+app.middlewares(
+  csrf({
+    cookieName: "XSRF-TOKEN",
+    headerNames: ["x-csrf-token"],
+  }),
+);
+
+app.post("/transfer", () => {
+  return json({ ok: true });
+});
+```
+
+The middleware follows a hardened **double-submit cookie** strategy:
+
+- It issues a CSRF cookie when missing (including first GET/HEAD/OPTIONS and failed protected requests).
+- For state-changing requests (POST/PUT/PATCH/DELETE), it validates the token from header/body against the cookie value.
+- It validates `Origin`/`Referer` for protected requests (and requires `Referer` on HTTPS when `Origin` is missing).
+- It rejects duplicated CSRF header values to avoid ambiguous token parsing.
+
+### Example: CSRF token in HTML templates (Express Handlebars)
+
+When you render server-side HTML, you can pass the CSRF token to your template and include it as a hidden field in forms.
+
+```ts
+import { createApp, csrf, render, json } from "skyguard-js";
+import { engine } from "express-handlebars";
+import { join } from "node:path";
+
+const app = createApp();
+
+app.views(__dirname, "views");
+app.engineTemplates(
+  "hbs",
+  engine({
+    extname: "hbs",
+    layoutsDir: join(__dirname, "views"),
+    defaultLayout: "main",
+  }),
+);
+
+app.middlewares(
+  csrf({
+    cookieName: "XSRF-TOKEN",
+    headerNames: ["x-csrf-token"],
+  }),
+);
+
+app.get("/transfer", request => {
+  return render("transfer", {
+    csrfToken: request.cookies["XSRF-TOKEN"],
+  });
+});
+
+app.post("/transfer", request => {
+  // If middleware passes, token is valid
+  return json({ ok: true, amount: request.body.amount });
+});
+```
+
+`views/transfer.hbs`:
+
+```hbs
+<form action="/transfer" method="POST">
+  <input type="hidden" name="csrf" value="{{csrfToken}}" />
+  <input type="number" name="amount" />
+  <button type="submit">Send</button>
+</form>
+```
+
+For `fetch`/AJAX requests, send the same token in headers:
+
+```html
+<script>
+  const csrfToken = "{{csrfToken}}";
+
+  async function sendTransfer() {
+    await fetch("/transfer", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-csrf-token": csrfToken,
+      },
+      body: JSON.stringify({ amount: 150 }),
+    });
+  }
+</script>
+```
+
+---
+
+## 🚦 Rate Limit Middleware
+
+You can limit requests with the built-in `rateLimit` middleware.
+
+```ts
+import { rateLimit, Response } from "skyguard-js";
+
+const apiRateLimit = rateLimit({
+  windowMs: 60_000, // 1 minute
+  max: 100,
+  message: "Too many requests from this IP",
+});
+
+app.get(
+  "/api/users",
+  () => {
+    return Response.json([{ id: 1 }]);
+  },
+  [apiRateLimit],
+);
 ```
 
 ---
@@ -175,33 +313,26 @@ app.staticFiles(join(__dirname, "..", "static"));
 To validate the data in the body of client requests, the framework provides the creation of validation schemes and a middleware function to validate the body of HTTP requests, used as follows:
 
 ```ts
-import { v, schema, validateData } from "skyguard-js";
+import { v, schema, validateRequest, json } from "skyguard-js";
 
 // Created Schema
 const userSchema = schema({
-  name: v.string({ maxLength: 60 }),
-  email: v.email(),
-  age: v.number({ min: 18 }),
-  active: v.boolean().default(false),
-  birthdate: v.date({ max: new Date() }),
+  body: {
+    name: v.string({ maxLength: 60 }),
+    email: v.email(),
+    age: v.number({ min: 18 }),
+    active: v.boolean().default(false),
+    birthdate: v.date({ max: new Date() }),
+  },
 });
 
-// Typing Interface
-interface User {
-  name: string;
-  email: string;
-  age: number;
-  active: boolean;
-  birthdate: Date;
-}
-
 app.post(
   "/test",
   (request: Request) => {
-    const data = request.getData<User>(); // The .getData() method returns the typed data with the interface you created
+    const data = request.body;
     return json(data).setStatusCode(201);
   },
-  [validateData(userSchema)],
+  [validateRequest(userSchema)],
 );
 ```
 
@@ -221,7 +352,7 @@ Validation is:
 The framework provides a set of built-in HTTP exceptions that can be thrown from route handlers or middleware. When an exception is thrown, the framework detects it and sends an appropriate HTTP response with the status code and message you specified in the class.
 
 ```ts
-import { NotFoundError, InternalServerError } from "skyguard-js";
+import { NotFoundError, InternalServerError, json } from "skyguard-js";
 
 const listResources = ["1", "2", "3"];
 
@@ -232,7 +363,7 @@ app.get("/resource/{id}", (request: Request) => {
     throw new NotFoundError("Resource not found");
   }
 
-  return Response.json(resource);
+  return json(resource);
 });
 
 app.get("/divide", (request: Request) => {
@@ -240,7 +371,7 @@ app.get("/divide", (request: Request) => {
     const { a, b } = request.query;
     const result = Number(a) / Number(b);
 
-    return Response.json({ result });
+    return json({ result });
   } catch (error) {
     throw new InternalServerError(
       "An error occurred while processing your request",
@@ -256,9 +387,9 @@ app.get("/divide", (request: Request) => {
 To handle sessions, you must use the framework’s built-in middleware. Depending on where you want to store them (in memory, in files, or in a database), you need to use the corresponding storage class.
 
 ```ts
-import { sessions, FileSessionStorage } from "skyguard-js";
+import { sessions, FileSessionStorage, json } from "skyguard-js";
 
-app.middlewares([
+app.middlewares(
   sessions(FileSessionStorage, {
     name: "connect.sid",
     rolling: true,
@@ -271,7 +402,7 @@ app.middlewares([
       path: "/",
     },
   }),
-]);
+);
 
 app.post("/login", (request: Request) => {
   const { username, password } = request.data;
@@ -304,7 +435,7 @@ app.get("/me", (request: Request) => {
 The framework includes some password hashing and JWT token generation functions, and also includes JWT authentication middleware.
 
 ```ts
-import { Hasher, JWT } from "skyguard-js";
+import { Hasher, JWT, json } from "skyguard-js";
 
 app.post("/register", async (request: Request) => {
   const { username, password } = request.data;
@@ -313,7 +444,7 @@ app.post("/register", async (request: Request) => {
   // Save username and hashedPassword to database
   // ...
 
-  return Response.json({ message: "User registered" });
+  return json({ message: "User registered" });
 });
 
 app.post("/login", async (request: Request) => {
@@ -333,7 +464,7 @@ app.post("/login", async (request: Request) => {
     expiresIn: "1h",
   });
 
-  return Response.json({ token });
+  return json({ token });
 });
 ```
 
@@ -344,7 +475,7 @@ app.post("/login", async (request: Request) => {
 To handle file uploads, use the built-in `createUploader` function to create an uploader middleware with the desired storage configuration.
 
 ```ts
-import { createUploader, StorageType } from "skyguard-js";
+import { createUploader, StorageType, json } from "skyguard-js";
 
 const uploader = createUploader({
   storageType: StorageType.DISK,
@@ -358,7 +489,7 @@ const uploader = createUploader({
 app.post(
   "/upload",
   (request: Request) => {
-    return Response.json({
+    return json({
       message: "File uploaded successfully",
       file: request.file,
     });
@@ -379,6 +510,7 @@ To render views, you must first set up the template engine using the `engineTemp
 import { engine } from "express-handlebars";
 import ejs from "ejs";
 import { join } from "node:path";
+import { render } from "skyguard-js";
 
 app.views(__dirname, "views");
 

package/dist/app.d.ts

@@ -140,7 +140,7 @@ export declare class App {
      *
      * app.middlewares(auth);
      */
-    middlewares(middlewares: Middleware[]): void;
+    middlewares(...middlewares: Middleware[]): void;
     /**
      * Creates a route group with a shared prefix.
      *

package/dist/app.js

@@ -195,7 +195,7 @@ class App {
      *
      * app.middlewares(auth);
      */
-    middlewares(middlewares) {
+    middlewares(...middlewares) {
         this.router.middlewares(middlewares);
     }
     /**

package/dist/helpers/http.d.ts

@@ -56,3 +56,40 @@ export declare function download(path: string, filename?: string, headers?: Reco
  * return await render("users/profile", { user }, "main");
  */
 export declare function render(data: string, params?: Record<string, unknown>): Promise<Response>;
+/**
+ * Sends a file as an HTTP response.
+ *
+ * This helper is a thin wrapper around `Response.sendFile`, allowing a file
+ * to be streamed to the client while optionally applying custom headers
+ * and resolving the file path relative to a root directory.
+ *
+ * @param filePath - Path to the file to send.
+ * @param options - Optional configuration for the file response.
+ * @param options.headers - Additional HTTP headers to include in the response
+ * (e.g. `Content-Type`, `Cache-Control`, `Content-Disposition`).
+ * @param options.root - Base directory used to resolve `filePath`.
+ * @returns A `Response` object that streams the requested file to the client.
+ *
+ * @example
+ * // Send a file using an absolute path
+ * const response = await sendFile("/var/www/files/report.pdf", {});
+ *
+ * @example
+ * // Send a file relative to a root directory
+ * const response = await sendFile("report.pdf", {
+ *   root: "/var/www/files",
+ * });
+ *
+ * @example
+ * // Send a downloadable file
+ * const response = await sendFile("report.pdf", {
+ *   root: "/var/www/files",
+ *   headers: {
+ *     "Content-Disposition": "attachment; filename=\"report.pdf\"",
+ *   },
+ * });
+ */
+export declare function sendFile(filePath: string, options: {
+    headers?: Record<string, string>;
+    root?: string;
+}): Promise<Response>;

package/dist/helpers/http.js

@@ -5,6 +5,7 @@ exports.text = text;
 exports.redirect = redirect;
 exports.download = download;
 exports.render = render;
+exports.sendFile = sendFile;
 const response_1 = require("../http/response");
 /**
  * Creates an HTTP response with a JSON body.
@@ -73,3 +74,39 @@ async function download(path, filename, headers) {
 async function render(data, params) {
     return await response_1.Response.render(data, params);
 }
+/**
+ * Sends a file as an HTTP response.
+ *
+ * This helper is a thin wrapper around `Response.sendFile`, allowing a file
+ * to be streamed to the client while optionally applying custom headers
+ * and resolving the file path relative to a root directory.
+ *
+ * @param filePath - Path to the file to send.
+ * @param options - Optional configuration for the file response.
+ * @param options.headers - Additional HTTP headers to include in the response
+ * (e.g. `Content-Type`, `Cache-Control`, `Content-Disposition`).
+ * @param options.root - Base directory used to resolve `filePath`.
+ * @returns A `Response` object that streams the requested file to the client.
+ *
+ * @example
+ * // Send a file using an absolute path
+ * const response = await sendFile("/var/www/files/report.pdf", {});
+ *
+ * @example
+ * // Send a file relative to a root directory
+ * const response = await sendFile("report.pdf", {
+ *   root: "/var/www/files",
+ * });
+ *
+ * @example
+ * // Send a downloadable file
+ * const response = await sendFile("report.pdf", {
+ *   root: "/var/www/files",
+ *   headers: {
+ *     "Content-Disposition": "attachment; filename=\"report.pdf\"",
+ *   },
+ * });
+ */
+async function sendFile(filePath, options) {
+    return await response_1.Response.sendFile(filePath, options);
+}

package/dist/http/nodeNativeHttp.d.ts

@@ -13,6 +13,7 @@ import { Request } from "./request";
 export declare class NodeHttpAdapter implements HttpAdapter {
     private readonly req;
     private readonly res;
+    /** Content Parser instance for parsing body requests */
     private contentParser;
     /** Logger instance for request logging */
     private logger;

package/dist/http/nodeNativeHttp.js

@@ -16,6 +16,7 @@ const logger_1 = require("./logger");
 class NodeHttpAdapter {
     req;
     res;
+    /** Content Parser instance for parsing body requests */
     contentParser;
     /** Logger instance for request logging */
     logger;
@@ -48,7 +49,7 @@ class NodeHttpAdapter {
             request.method === httpMethods_1.HttpMethods.put ||
             request.method === httpMethods_1.HttpMethods.patch) {
             const parsedData = await this.contentParser.parse(this.req);
-            request.setData(parsedData);
+            request.setBody(parsedData);
         }
         return request;
     }

package/dist/http/request.d.ts

@@ -1,7 +1,7 @@
 import { HttpMethods } from "./httpMethods";
-import type { Headers } from "../types";
 import { Session } from "../sessions";
 import type { UploadedFile } from "../parsers/parserInterface";
+import { IncomingHttpHeaders } from "node:http";
 /**
  * Represents an incoming client request within the framework.
  *
@@ -22,7 +22,7 @@ export declare class Request {
     /** Normalized HTTP method */
     private _method;
     /** Parsed request body payload */
-    private _data;
+    private _body;
     /** Query string parameters */
     private _query;
     /** Dynamic route parameters (path params) */
@@ -42,15 +42,14 @@ export declare class Request {
     get url(): string;
     get method(): HttpMethods;
     setMethod(method: HttpMethods): void;
-    get headers(): Headers;
-    setHeaders(headers: Headers): void;
-    get query(): Record<string, string>;
-    setQuery(query: Record<string, string>): void;
-    get params(): Record<string, string>;
-    setParams(params: Record<string, string>): void;
-    get data(): Record<string, any>;
-    setData(data: Record<string, any>): void;
-    getData<T>(): Partial<T>;
+    get headers(): IncomingHttpHeaders;
+    setHeaders(headers: IncomingHttpHeaders): void;
+    get query(): Record<string, unknown>;
+    setQuery(query: Record<string, unknown>): void;
+    get params(): Record<string, unknown>;
+    setParams(params: Record<string, unknown>): void;
+    get body(): Record<string, any>;
+    setBody(body: Record<string, any>): void;
     get session(): Session;
     setSession(session: Session): void;
     /**

package/dist/http/request.js

@@ -22,7 +22,7 @@ class Request {
     /** Normalized HTTP method */
     _method;
     /** Parsed request body payload */
-    _data = {};
+    _body = {};
     /** Query string parameters */
     _query = {};
     /** Dynamic route parameters (path params) */
@@ -68,14 +68,11 @@ class Request {
     setParams(params) {
         this._params = params;
     }
-    get data() {
-        return this._data;
+    get body() {
+        return this._body;
     }
-    setData(data) {
-        this._data = data;
-    }
-    getData() {
-        return this._data;
+    setBody(body) {
+        this._body = body;
     }
     get session() {
         return this._session;

package/dist/http/response.d.ts

@@ -1,5 +1,5 @@
-import type { Headers } from "../types";
 import { type CookieOptions } from "../sessions/cookies";
+import { IncomingHttpHeaders } from "node:http";
 /**
  * Represents an outgoing response sent to the client.
  *
@@ -31,8 +31,8 @@ export declare class Response {
     private _content;
     get statusCode(): number;
     setStatusCode(newStatus: number): this;
-    get headers(): Headers;
-    setHeaders(headers: Headers): this;
+    get headers(): IncomingHttpHeaders;
+    setHeaders(headers: IncomingHttpHeaders): this;
     private merge;
     setHeader(header: string, value: string): this;
     removeHeader(header: string): void;
@@ -109,7 +109,51 @@ export declare class Response {
      * });
      */
     static redirect(url: string): Response;
+    /**
+     * Prepare a response that forces a file download.
+     *
+     * Uses `FileDownloadHelper` to obtain the file content and the headers
+     * required to trigger a download (for example, `content-disposition`).
+     * Returns a `Response` instance containing the file content (typically a
+     * `Buffer`) and the download headers.
+     *
+     * @param path - Path to the file on disk or a location understood by the helper
+     * @param filename - Suggested filename for the downloaded file (optional)
+     * @param headers - Additional headers to merge into the response (optional)
+     * @returns Promise that resolves to a `Response` ready to be sent to the client
+     * @throws Propagates any exceptions thrown by `FileDownloadHelper.download`
+     * @example
+     * return await Response.download("./uploads/report.pdf", "report.pdf");
+     */
     static download(path: string, filename?: string, headers?: Record<string, string>): Promise<Response>;
+    /**
+     * Sends a file to the client for display (inline).
+     *
+     * Unlike {@link download}, this method does not force the browser to download
+     * the file. Instead, it attempts to display the file in the browser (e.g.,
+     * images, PDFs, HTML files). Sets appropriate `Content-Type` and
+     * `Content-Length` headers based on the file.
+     *
+     * @param filePath - Path to the file on disk
+     * @param options - Optional configuration for sending the file
+     * @returns A {@link Response} configured for inline file display
+     *
+     * @example
+     * app.get("/preview", async () => {
+     *   return Response.sendFile("./uploads/document.pdf");
+     * });
+     *
+     * @example
+     * app.get("/image", async () => {
+     *   return Response.sendFile("./assets/photo.jpg", {
+     *     headers: { "Cache-Control": "max-age=3600" }
+     *   });
+     * });
+     */
+    static sendFile(filePath: string, options?: {
+        headers?: Record<string, string>;
+        root?: string;
+    }): Promise<Response>;
     /**
      * Renders an HTML view and returns it as an HTTP response.
      *