skyguard-js 1.0.2 → 1.1.1

package/README.md

@@ -26,11 +26,20 @@ At its current stage, the framework focuses on **routing**, **internal architect
 - Request / Response abstractions
 - Declarative data validation
 - Simple template engine with layouts and helpers
+- Built-in HTTP exceptions
+- Password hashing and JWT token generation
+- CORS middleware
+- File uploads (via middleware)
 - Static file serving
 - Session handling (via middleware)
 
 ---
 
+> [!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.
+
+---
+
 ## 📦 Installation
 
 ```bash
@@ -63,11 +72,11 @@ Routes are registered using HTTP methods on the `app` instance.
 
 ```ts
 app.get("/posts/{id}", (request: Request) => {
-  return Response.json(request.getParams());
+  return Response.json(request.params);
 });
 
 app.post("/posts", (request: Request) => {
-  return Response.json(request.getData());
+  return Response.json(request.data);
 });
 ```
 
@@ -99,7 +108,7 @@ const authMiddleware = async (
   request: Request,
   next: RouteHandler,
 ): Promise<Response> => {
-  if (request.getHeaders["authorization"] !== "secret") {
+  if (request.headers["authorization"] !== "secret") {
     return Response.json({ message: "Unauthorized" }).setStatus(401);
   }
 
@@ -121,37 +130,53 @@ app.get("/secure", () => Response.json({ secure: true }), [authMiddleware]);
 
 ---
 
-## Static Files
+## 🌐 CORS Middleware
+
+To enable CORS, use the built-in `cors` middleware.
+
+```ts
+import { cors } from "skyguard-js/middlewares";
+
+app.middlewares([
+  cors({
+    origin: ["http://localhost:3000", "https://myapp.com"],
+    methods: ["GET", "POST"],
+    allowedHeaders: ["Content-Type", "Authorization"],
+    credentials: true,
+  }),
+]);
+```
+
+---
+
+## 📌 Static Files
 
-To serve static files, use the `static` method.
+To serve static files, use the application's `staticFiles` method with the directory path. The name of the folder will determine the initial route prefix.
 
 ```ts
 import { join } from "node:path";
 
-app.static(join(__dirname, "..", "static"));
+app.staticFiles(join(__dirname, "..", "static"));
+
+// Route http://localhost:3000/static/style.css will serve the file located at ./static/style.css
 ```
 
 ---
 
-## 📦 Data Validation
+## ⛔ Data Validation
 
 Skyguard.js provides a **declarative validation system** using schemas.
 
 ```ts
-import { ValidationSchema } from "skyguard-js/validation";
-
-export const userSchema = ValidationSchema.create()
-  .field("name")
-  .required("Name is required")
-  .string({ maxLength: 60 })
-  .field("email")
-  .required()
-  .email()
-  .field("age")
-  .number({ min: 18, max: 99 })
-  .field("active")
-  .boolean()
-  .build();
+import { validator } from "skyguard-js/validation";
+
+const userSchema = validator.schema({
+  name: validator.string({ maxLength: 60 }),
+  email: validator.email().required(),
+  age: validator.number({ min: 18 }),
+  active: validator.boolean().required(),
+  birthdate: validator.date({ max: new Date() }),
+});
 
 app.post("/users", (request: Request) => {
   const validatedData = request.validateData(userSchema);
@@ -172,62 +197,194 @@ Validation is:
 
 ---
 
-## 📄 Views & Template Engine
+## 🚨 Exceptions & Error Handling
 
-To render HTML views, use the `render` helper.
+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 { render } from "skyguard-js/helpers";
+import { NotFoundError, InternalServerError } from "skyguard-js/exceptions";
 
-app.get("/home", () => {
-  return render(
-    "home",
-    {
-      title: "Products",
-      products: [
-        { name: "Laptop", price: 999.99 },
-        { name: "Mouse", price: 29.99 },
-      ],
-      user: { name: "John", role: "admin" },
-    },
-    "main",
-  );
+const listResources = ["1", "2", "3"];
+
+app.get("/resource/{id}", (request: Request) => {
+  const resource = request.params["id"];
+
+  if (!listResources.includes(resource)) {
+    throw new NotFoundError("Resource not found");
+  }
+
+  return Response.json(resource);
+});
+
+app.get("/divide", (request: Request) => {
+  try {
+    const { a, b } = request.query;
+    const result = Number(a) / Number(b);
+
+    return Response.json({ result });
+  } catch (error) {
+    throw new InternalServerError(
+      "An error occurred while processing your request",
+    );
+  }
 });
 ```
 
-### Supported features
+---
+
+## 🧱 Sessions
+
+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 } from "skyguard-js/middlewares";
+import { FileSessionStorage } from "skyguard-js";
+
+app.middlewares([sessions(FileSessionStorage)]);
+
+app.post("/login", (request: Request) => {
+  const { username, password } = request.data;
+
+  if (username === "admin" && password === "secret") {
+    request.session.set("user", {
+      id: 1,
+      username: "admin",
+      role: "admin",
+    });
 
-- Variable interpolation (`{{ variable }}`)
-- Conditionals (`{{#if}}`)
-- Loops (`{{#each}}`)
-- Layouts
-- Partials
-- Built-in helpers (`upper`, `lower`, `date`)
-- Custom helpers
+    return json({ message: "Logged in" });
+  }
+
+  throw new UnauthorizedError("Invalid credentials");
+});
+
+app.get("/me", (request: Request) => {
+  const user = request.session.get("user");
+
+  if (!user) throw new UnauthorizedError("Not authenticated");
+  return json({ user });
+});
+```
 
 ---
 
-## 🧱 Project Status
+## 🛡️ Security
+
+The framework includes some password hashing and JWT token generation functions, and also includes JWT authentication middleware.
+
+```ts
+import { hash, verify, createJWT } from "skyguard-js/security";
+import { authJWT } from "skyguard-js/middlewares";
 
-⚠️ **Early-stage project**
+app.post("/register", async (request: Request) => {
+  const { username, password } = request.data;
+  const hashedPassword = await hash(password);
 
-- Not production-ready
-- API may change
-- Features are still evolving
-- Intended primarily for learning and experimentation
+  // Save username and hashedPassword to database
+  // ...
+
+  return Response.json({ message: "User registered" });
+});
+
+app.post("/login", async (request: Request) => {
+  const { username, password } = request.data;
+
+  // Retrieve user from database by username
+  // ...
+
+  const isValid = await verify(password, user.hashedPassword);
+
+  if (!isValid) {
+    throw new UnauthorizedError("Invalid credentials");
+  }
+
+  const token = createJWT({ sub: user.id, role: user.role }, "1h");
+
+  return Response.json({ token });
+});
+```
+
+---
+
+## 📂 File Uploads
+
+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";
+
+const uploader = createUploader({
+  storageType: StorageType.DISK,
+  storageOptions: {
+    destination: "./uploads",
+  },
+});
+
+app.post(
+  "/upload",
+  (request: Request) => {
+    return Response.json({
+      message: "File uploaded successfully",
+      file: request.file,
+    });
+  },
+  [uploader.single("file")],
+);
+```
+
+---
+
+## 📄 Views & Template Engine
+
+To render views, you must first set up the template engine using the `engineTemplates` method of the `app`, set the view path with the `views` method of the `app`, and then you can use the `render` method within your handlers to render the views with the data you want to pass.
+
+```ts
+import { engine } from "express-handlebars";
+import ejs from "ejs";
+import { join } from "node:path";
+
+app.views(__dirname, "views");
+
+// Config for Express Handlebars
+app.engineTemplates(
+  "hbs",
+  engine({
+    extname: "hbs",
+    layoutsDir: join(__dirname, "views"),
+    defaultLayout: "main",
+  }),
+);
+
+// Config for EJS
+app.engineTemplates("ejs", (templatePath, data) => {
+  return ejs.renderFile(templatePath, data);
+});
+
+app.get("/home", () => {
+  return render("index", {
+    title: "Home Page",
+    message: "Welcome to the home page!",
+  });
+});
+```
+
+Currently, it works with third-party template engines such as **Express Handlebars**, **Pug**, and **EJS**, but the idea is to implement its own template engine in the future.
 
 ---
 
 ## 🔮 Roadmap (Tentative)
 
 - Middleware system (✅)
-- Template engine (✅)
+- Template engines supported (✅)
 - Request / Response abstraction (✅)
 - Data validation (✅)
 - Error handling improvements (✅)
-- Sessions & cookies (in progress)
-- Authentication & authorization
+- Sessions & cookies (✅)
+- Passoword hashing & JWT tokens (✅)
+- File uploads (✅)
 - Database & ORM integration
+- Authentication & authorization
+- WebSockets
 
 ---
 

package/dist/app.d.ts

@@ -1,6 +1,6 @@
 import { RouterGroup } from "./routing";
-import { type View } from "./views";
 import type { Middleware, RouteHandler } from "./types";
+import { type TemplateEngineFunction } from "./views/engineTemplate";
 /**
  * The `App` class acts as the **execution kernel** and **lifecycle orchestrator**
  * of the framework.
@@ -22,14 +22,14 @@ import type { Middleware, RouteHandler } from "./types";
 export declare class App {
     /** Main routing system */
     private router;
-    /**
-     * View engine used to render templates.
-     *
-     * Typically consumed inside controllers to generate HTML responses.
-     */
-    view: View;
     /** Static file handler (optional) */
     private staticFileHandler;
+    /** Logger instance for request logging */
+    private logger;
+    /** Timestamp marking the start of request processing (for logging) */
+    private startTime;
+    /** View engine for rendering templates (optional) */
+    private viewEngine;
     /**
      * Bootstraps and configures the application.
      *
@@ -65,6 +65,42 @@ export declare class App {
      * // /public/css/style.css → /css/style.css
      */
     staticFiles(publicPath: string): void;
+    /**
+     * Configures the views directory for template rendering.
+     *
+     * @param pathSegments Path segments leading to the views directory
+     * @example
+     * app.views(__dirname, "views");
+     */
+    views(...pathSegments: string[]): void;
+    /**
+     * Configures the template engine for rendering views.
+     *
+     * @param extension - File extension associated with the template engine (e.g. "hbs", "ejs")
+     * @param engine - Function that renders a template given its path and data
+     *
+     * @example
+     * app.engineTemplates("hbs", (templatePath, data) => {
+     *   const content = fs.readFileSync(templatePath, "utf-8");
+     *   return content.replace(/{{\s*(\w+)\s*}}/g, (_, key) => {
+     *     return data[key] ?? "";
+     *   });
+     * });
+     *
+     * // With express-handlebars
+     * app.engineTemplates(
+     *   "hbs",
+     *   engine({
+     *     extname: "hbs",
+     *     layoutsDir: join(__dirname, "views"),
+     *     defaultLayout: "main",
+     *   }),
+     * );
+     *
+     * The `extension` parameter allows the framework to automatically select the correct
+     * template engine based on the file extension of the view being rendered.
+     */
+    engineTemplates(extension: string, engine: TemplateEngineFunction): void;
     /**
      * Starts the HTTP server on the given port.
      *

package/dist/app.js

@@ -3,13 +3,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createApp = exports.App = void 0;
 const routing_1 = require("./routing");
 const http_1 = require("./http");
-const exceptions_1 = require("./exceptions");
-const views_1 = require("./views");
+const validationException_1 = require("./exceptions/validationException");
 const node_path_1 = require("node:path");
-const app_1 = require("./helpers/app");
 const fileStaticHandler_1 = require("./static/fileStaticHandler");
 const node_http_1 = require("node:http");
 const httpExceptions_1 = require("./exceptions/httpExceptions");
+const engineTemplate_1 = require("./views/engineTemplate");
+const container_1 = require("./container/container");
 /**
  * The `App` class acts as the **execution kernel** and **lifecycle orchestrator**
  * of the framework.
@@ -31,14 +31,14 @@ const httpExceptions_1 = require("./exceptions/httpExceptions");
 class App {
     /** Main routing system */
     router;
-    /**
-     * View engine used to render templates.
-     *
-     * Typically consumed inside controllers to generate HTML responses.
-     */
-    view;
     /** Static file handler (optional) */
     staticFileHandler = null;
+    /** Logger instance for request logging */
+    logger;
+    /** Timestamp marking the start of request processing (for logging) */
+    startTime;
+    /** View engine for rendering templates (optional) */
+    viewEngine;
     /**
      * Bootstraps and configures the application.
      *
@@ -49,9 +49,10 @@ class App {
      * @returns The singleton `App` instance
      */
     static bootstrap() {
-        const app = (0, app_1.singleton)(App);
+        const app = container_1.Container.singleton(App);
         app.router = new routing_1.Router();
-        app.view = new views_1.RaptorEngine((0, node_path_1.join)(__dirname, "..", "views"));
+        app.logger = new http_1.Logger();
+        app.viewEngine = container_1.Container.singleton(engineTemplate_1.ViewEngine);
         return app;
     }
     /**
@@ -71,8 +72,8 @@ class App {
     async handle(adapter) {
         try {
             const request = await adapter.getRequest();
-            if (this.staticFileHandler && request.getMethod === http_1.HttpMethods.get) {
-                const staticResponse = await this.staticFileHandler.tryServeFile(request.getUrl);
+            if (this.staticFileHandler && request.method === http_1.HttpMethods.get) {
+                const staticResponse = await this.staticFileHandler.tryServeFile(request.url);
                 if (staticResponse) {
                     adapter.sendResponse(staticResponse);
                     return;
@@ -97,6 +98,46 @@ class App {
     staticFiles(publicPath) {
         this.staticFileHandler = new fileStaticHandler_1.StaticFileHandler(publicPath);
     }
+    /**
+     * Configures the views directory for template rendering.
+     *
+     * @param pathSegments Path segments leading to the views directory
+     * @example
+     * app.views(__dirname, "views");
+     */
+    views(...pathSegments) {
+        this.viewEngine.setViewsPath((0, node_path_1.join)(...pathSegments));
+    }
+    /**
+     * Configures the template engine for rendering views.
+     *
+     * @param extension - File extension associated with the template engine (e.g. "hbs", "ejs")
+     * @param engine - Function that renders a template given its path and data
+     *
+     * @example
+     * app.engineTemplates("hbs", (templatePath, data) => {
+     *   const content = fs.readFileSync(templatePath, "utf-8");
+     *   return content.replace(/{{\s*(\w+)\s*}}/g, (_, key) => {
+     *     return data[key] ?? "";
+     *   });
+     * });
+     *
+     * // With express-handlebars
+     * app.engineTemplates(
+     *   "hbs",
+     *   engine({
+     *     extname: "hbs",
+     *     layoutsDir: join(__dirname, "views"),
+     *     defaultLayout: "main",
+     *   }),
+     * );
+     *
+     * The `extension` parameter allows the framework to automatically select the correct
+     * template engine based on the file extension of the view being rendered.
+     */
+    engineTemplates(extension, engine) {
+        this.viewEngine.setEngine(extension, engine);
+    }
     /**
      * Starts the HTTP server on the given port.
      *
@@ -107,8 +148,10 @@ class App {
      */
     run(port, callback, hostname = "127.0.0.1") {
         (0, node_http_1.createServer)((req, res) => {
+            this.startTime = process.hrtime.bigint();
             const adapter = new http_1.NodeHttpAdapter(req, res);
             void this.handle(adapter);
+            this.logger.log(req, res, this.startTime);
         }).listen(port, hostname, () => {
             callback();
         });
@@ -172,20 +215,19 @@ class App {
      */
     handleError(error, adapter) {
         if (error instanceof httpExceptions_1.HttpException) {
-            adapter.sendResponse(http_1.Response.json(error.toJSON()).setStatus(error.statusCode));
+            adapter.sendResponse(http_1.Response.json(error.toJSON()).setStatusCode(error.statusCode));
             return;
         }
-        if (error instanceof exceptions_1.ValidationException) {
+        if (error instanceof validationException_1.ValidationException) {
             adapter.sendResponse(http_1.Response.json({
-                success: false,
                 errors: error.getErrorsByField(),
-            }).setStatus(400));
+            }).setStatusCode(400));
             return;
         }
         adapter.sendResponse(http_1.Response.json({
             statusCode: 500,
             message: "Internal Server Error",
-        }).setStatus(500));
+        }).setStatusCode(500));
         console.error(error);
     }
 }

package/dist/crypto/hasher.d.ts

@@ -0,0 +1,91 @@
+type ScryptOptions = {
+    cost: number;
+    blockSize: number;
+    parallelization: number;
+    maxmem?: number;
+};
+/**
+ * Hashes a plaintext password using scrypt with an unique random salt.
+ *
+ * Output format:
+ *   `scrypt$<cost>$<blockSize>$<parallelization>$<saltHex>$<hashHex>`
+ *
+ * @param password - Plaintext password.
+ * @param saltLength - Salt length in bytes. Default `16` (recommended minimum).
+ * @param params - Scrypt work-factor params. Defaults to `DEFAULT_PARAMS`.
+ * @param pepper - Optional server secret mixed into the password (e.g., from env var).
+ * @returns A compact encoded hash string containing algorithm parameters + salt + derived key.
+ */
+export declare const hash: (password: string, saltLength?: number, params?: ScryptOptions, pepper?: string) => Promise<string>;
+/**
+ * Verifies a plaintext password against a stored scrypt hash string.
+ *
+ * Safe failure behavior:
+ * - Returns `false` for any parsing error, invalid encoding, mismatched lengths,
+ *   or scrypt errors. This avoids leaking details about why verification failed.
+ *
+ * @param password - Plaintext password to verify.
+ * @param storedHash - Stored hash string in the compact format.
+ * @param pepper - Optional server secret; must match the one used when hashing.
+ * @returns `true` if the password matches, otherwise `false`.
+ */
+export declare const verify: (password: string, storedHash: string, pepper?: string) => Promise<boolean>;
+/**
+ * Indicates whether a stored hash should be regenerated using the current parameters.
+ *
+ * Use this after successful login:
+ * - If `needsRehash(...) === true`, compute a new hash using `hash(...)` with
+ *   the latest parameters and store it back to the DB.
+ *
+ * This enables gradual upgrades of the work factor without forcing password resets.
+ *
+ * @param storedHash - Stored hash string in compact format.
+ * @param params - Desired/current scrypt params. Defaults to `DEFAULT_PARAMS`.
+ * @returns `true` if the hash is missing/invalid or was produced with different parameters.
+ */
+export declare const needsRehash: (storedHash: string, params?: ScryptOptions) => boolean;
+/**
+ * Hashes multiple passwords using controlled concurrency.
+ *
+ * Why limit concurrency?
+ * scrypt is intentionally CPU + memory intensive. Running too many in parallel can:
+ * - saturate the libuv threadpool,
+ * - exceed memory limits (especially in containers),
+ * - increase latency for the rest of the application.
+ *
+ * The `concurrency` option caps the number of simultaneous scrypt operations.
+ *
+ * @param passwords - List of plaintext passwords.
+ * @param options - Optional hashing controls:
+ *   - saltLength: salt bytes (default 16)
+ *   - params: scrypt params (default DEFAULT_PARAMS)
+ *   - pepper: optional server secret
+ *   - concurrency: max simultaneous operations (default 4)
+ * @returns Array of compact hash strings in the same order as input.
+ */
+export declare const hashBatch: (passwords: string[], options?: {
+    saltLength?: number;
+    params?: ScryptOptions;
+    pepper?: string;
+    concurrency?: number;
+}) => Promise<string[]>;
+/**
+ * Verifies multiple password/hash pairs using controlled concurrency.
+ *
+ * This is useful for bulk checks or migrations. Concurrency is typically higher
+ * than hashing, but still should be bounded to avoid saturating the threadpool.
+ *
+ * @param credentials - Array of `{ password, hash }` pairs.
+ * @param options - Optional verification controls:
+ *   - pepper: optional server secret
+ *   - concurrency: max simultaneous operations (default 8)
+ * @returns Array of booleans in the same order as input.
+ */
+export declare const verifyBatch: (credentials: Array<{
+    password: string;
+    hash: string;
+}>, options?: {
+    pepper?: string;
+    concurrency?: number;
+}) => Promise<boolean[]>;
+export {};