skyguard-js 1.0.2 → 1.1.0

package/README.md

@@ -26,6 +26,10 @@ 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)
 
@@ -63,11 +67,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 +103,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 +125,53 @@ app.get("/secure", () => Response.json({ secure: true }), [authMiddleware]);
 
 ---
 
-## Static Files
+## 🌐 CORS Middleware
 
-To serve static files, use the `static` method.
+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 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,6 +192,143 @@ Validation is:
 
 ---
 
+## 🚨 Exceptions & Error Handling
+
+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/exceptions";
+
+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",
+    );
+  }
+});
+```
+
+---
+
+## 🧱 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",
+    });
+
+    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 });
+});
+```
+
+---
+
+## 🛡️ 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";
+
+app.post("/register", async (request: Request) => {
+  const { username, password } = request.data;
+  const hashedPassword = await hash(password);
+
+  // 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 HTML views, use the `render` helper.
@@ -207,17 +364,6 @@ app.get("/home", () => {
 
 ---
 
-## 🧱 Project Status
-
-⚠️ **Early-stage project**
-
-- Not production-ready
-- API may change
-- Features are still evolving
-- Intended primarily for learning and experimentation
-
----
-
 ## 🔮 Roadmap (Tentative)
 
 - Middleware system (✅)
@@ -225,9 +371,12 @@ app.get("/home", () => {
 - 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

@@ -30,6 +30,8 @@ export declare class App {
     view: View;
     /** Static file handler (optional) */
     private staticFileHandler;
+    private logger;
+    private startTime;
     /**
      * Bootstraps and configures the application.
      *

package/dist/app.js

@@ -3,7 +3,7 @@ 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 validationException_1 = require("./exceptions/validationException");
 const views_1 = require("./views");
 const node_path_1 = require("node:path");
 const app_1 = require("./helpers/app");
@@ -39,6 +39,8 @@ class App {
     view;
     /** Static file handler (optional) */
     staticFileHandler = null;
+    logger;
+    startTime;
     /**
      * Bootstraps and configures the application.
      *
@@ -52,6 +54,7 @@ class App {
         const app = (0, app_1.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();
         return app;
     }
     /**
@@ -71,8 +74,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;
@@ -107,8 +110,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();
         });
@@ -175,9 +180,8 @@ class App {
             adapter.sendResponse(http_1.Response.json(error.toJSON()).setStatus(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));
             return;

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 {};

package/dist/crypto/hasher.js

@@ -0,0 +1,220 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyBatch = exports.hashBatch = exports.needsRehash = exports.verify = exports.hash = void 0;
+const node_crypto_1 = require("node:crypto");
+const node_util_1 = require("node:util");
+/**
+ * Derives password keys using Node.js `crypto.scrypt` but exposed as a Promise.
+ *
+ * Why the cast?
+ * `crypto.scrypt` has multiple overloads (with/without `options`). When wrapped with
+ * `util.promisify`, TypeScript often keeps only the 3-argument overload and “forgets”
+ * the one that accepts `options`. We re-type it to preserve the 4-argument signature.
+ *
+ * @param password - Plaintext password (or Buffer) to derive from.
+ * @param salt - Random per-password salt (or Buffer).
+ * @param keylen - Desired derived key length in bytes (e.g., 64).
+ * @param options - Scrypt work-factor parameters (cost, blockSize, parallelization, maxmem).
+ * @returns The derived key as a Buffer.
+ */
+const scryptAsync = (0, node_util_1.promisify)(node_crypto_1.scrypt);
+const KEY_LENGTH = 64;
+// Reasonable defaults (tune cost by measuring ~100–250ms on your server).
+const DEFAULT_PARAMS = {
+    cost: 16384,
+    blockSize: 8,
+    parallelization: 1,
+    maxmem: 64 * 1024 * 1024,
+};
+const isHex = (s) => /^[0-9a-f]+$/i.test(s);
+const isPositiveInt = (n) => Number.isInteger(n) && n > 0;
+/**
+ * Parses a compact scrypt password hash string into its components.
+ *
+ * Expected format:
+ *   `scrypt$<cost>$<blockSize>$<parallelization>$<saltHex>$<hashHex>`
+ *
+ * @param hash - Stored hash string in compact format.
+ * @returns Parsed fields or `null` if the string is invalid.
+ */
+const parseHash = (hash) => {
+    try {
+        const parts = hash.split("$");
+        if (parts.length !== 6)
+            return null;
+        const [algo, costStr, blockSizeStr, parallelStr, saltHex, hashHex] = parts;
+        if (algo !== "scrypt")
+            return null;
+        const cost = Number(costStr);
+        const blockSize = Number(blockSizeStr);
+        const parallelization = Number(parallelStr);
+        if (!isPositiveInt(cost) ||
+            !isPositiveInt(blockSize) ||
+            !isPositiveInt(parallelization))
+            return null;
+        if (!saltHex || !hashHex)
+            return null;
+        if (!isHex(saltHex) || !isHex(hashHex))
+            return null;
+        if (saltHex.length % 2 !== 0 || hashHex.length % 2 !== 0)
+            return null;
+        if (saltHex.length < 32)
+            return null;
+        const hashBuffer = Buffer.from(hashHex, "hex");
+        if (hashBuffer.length === 0)
+            return null;
+        return {
+            cost,
+            blockSize,
+            parallelization,
+            salt: saltHex,
+            hash: hashHex,
+            keyLength: hashBuffer.length,
+        };
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * 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.
+ */
+const hash = async (password, saltLength = 16, params = DEFAULT_PARAMS, pepper) => {
+    const salt = (0, node_crypto_1.randomBytes)(saltLength);
+    const pwd = pepper ? password + pepper : password;
+    const derived = await scryptAsync(pwd, salt, KEY_LENGTH, {
+        cost: params.cost,
+        blockSize: params.blockSize,
+        parallelization: params.parallelization,
+        ...(params.maxmem ? { maxmem: params.maxmem } : {}),
+    });
+    return `scrypt$${params.cost}$${params.blockSize}$${params.parallelization}$${salt.toString("hex")}$${derived.toString("hex")}`;
+};
+exports.hash = hash;
+/**
+ * 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`.
+ */
+const verify = async (password, storedHash, pepper) => {
+    const parsed = parseHash(storedHash);
+    if (!parsed)
+        return false;
+    try {
+        const pwd = pepper ? password + pepper : password;
+        const derived = await scryptAsync(pwd, Buffer.from(parsed.salt, "hex"), parsed.keyLength, {
+            cost: parsed.cost,
+            blockSize: parsed.blockSize,
+            parallelization: parsed.parallelization,
+        });
+        const storedBuffer = Buffer.from(parsed.hash, "hex");
+        if (storedBuffer.length !== derived.length)
+            return false;
+        return (0, node_crypto_1.timingSafeEqual)(derived, storedBuffer);
+    }
+    catch {
+        return false;
+    }
+};
+exports.verify = verify;
+/**
+ * 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.
+ */
+const needsRehash = (storedHash, params = DEFAULT_PARAMS) => {
+    const parsed = parseHash(storedHash);
+    if (!parsed)
+        return true;
+    return (parsed.keyLength !== KEY_LENGTH ||
+        parsed.cost !== params.cost ||
+        parsed.blockSize !== params.blockSize ||
+        parsed.parallelization !== params.parallelization);
+};
+exports.needsRehash = needsRehash;
+/**
+ * Simple concurrency limiter for CPU-heavy hashing/verifying.
+ */
+const mapLimit = async (items, limit, fn) => {
+    const results = new Array(items.length);
+    let idx = 0;
+    const workers = Array.from({ length: Math.max(1, limit) }, async () => {
+        while (true) {
+            const i = idx++;
+            if (i >= items.length)
+                break;
+            results[i] = await fn(items[i], i);
+        }
+    });
+    await Promise.all(workers);
+    return results;
+};
+/**
+ * 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.
+ */
+const hashBatch = async (passwords, options) => {
+    const saltLength = options?.saltLength ?? 16;
+    const params = options?.params ?? DEFAULT_PARAMS;
+    const pepper = options?.pepper;
+    const concurrency = options?.concurrency ?? 4;
+    return mapLimit(passwords, concurrency, p => (0, exports.hash)(p, saltLength, params, pepper));
+};
+exports.hashBatch = hashBatch;
+/**
+ * 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.
+ */
+const verifyBatch = async (credentials, options) => {
+    const pepper = options?.pepper;
+    const concurrency = options?.concurrency ?? 8;
+    return mapLimit(credentials, concurrency, c => (0, exports.verify)(c.password, c.hash, pepper));
+};
+exports.verifyBatch = verifyBatch;

package/dist/crypto/index.d.ts

@@ -0,0 +1,2 @@
+export { hash, verify, hashBatch, verifyBatch } from "./hasher";
+export { createJWT, verifyJWT, decodeJWT } from "./jwt";

package/dist/crypto/index.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decodeJWT = exports.verifyJWT = exports.createJWT = exports.verifyBatch = exports.hashBatch = exports.verify = exports.hash = void 0;
+var hasher_1 = require("./hasher");
+Object.defineProperty(exports, "hash", { enumerable: true, get: function () { return hasher_1.hash; } });
+Object.defineProperty(exports, "verify", { enumerable: true, get: function () { return hasher_1.verify; } });
+Object.defineProperty(exports, "hashBatch", { enumerable: true, get: function () { return hasher_1.hashBatch; } });
+Object.defineProperty(exports, "verifyBatch", { enumerable: true, get: function () { return hasher_1.verifyBatch; } });
+var jwt_1 = require("./jwt");
+Object.defineProperty(exports, "createJWT", { enumerable: true, get: function () { return jwt_1.createJWT; } });
+Object.defineProperty(exports, "verifyJWT", { enumerable: true, get: function () { return jwt_1.verifyJWT; } });
+Object.defineProperty(exports, "decodeJWT", { enumerable: true, get: function () { return jwt_1.decodeJWT; } });