skyguard-js 1.1.2 → 1.1.4

package/README.md

@@ -55,12 +55,14 @@ import { createApp, Response } from "skyguard-js";
 
 const app = createApp();
 
+const PORT = 3000;
+
 app.get("/health", () => {
   return Response.json({ status: "ok" });
 });
 
-app.run(3000, () => {
-  console.log(`Server running in port: http://localhost:${3000}`);
+app.run(PORT, () => {
+  console.log(`Server running in port: http://localhost:${PORT}`);
 });
 ```
 
@@ -136,11 +138,12 @@ To enable CORS, use the built-in `cors` middleware.
 
 ```ts
 import { cors } from "skyguard-js/middlewares";
+import { HttpMethods } from "skyguard-js";
 
 app.middlewares([
   cors({
     origin: ["http://localhost:3000", "https://myapp.com"],
-    methods: ["GET", "POST"],
+    methods: [HttpMethods.get, HttpMethods.post],
     allowedHeaders: ["Content-Type", "Authorization"],
     credentials: true,
   }),
@@ -242,7 +245,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;
@@ -276,7 +292,6 @@ The framework includes some password hashing and JWT token generation functions,
 
 ```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;
@@ -300,7 +315,10 @@ 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: "123" }, "secret-key", {
+    algorithm: "HS256",
+    expiresIn: "1h",
+  });
 
   return Response.json({ token });
 });
@@ -318,7 +336,9 @@ import { createUploader, StorageType } from "skyguard-js";
 const uploader = createUploader({
   storageType: StorageType.DISK,
   storageOptions: {
-    destination: "./uploads",
+    disk: {
+      destination: "./uploads",
+    },
   },
 });
 
@@ -334,6 +354,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.d.ts

@@ -62,6 +62,7 @@ export declare class App {
      *
      * @example
      * app.staticFiles("public");
+     * app.staticFiles(join(__dirname, "..", "public"));
      * // /public/css/style.css → /css/style.css
      */
     staticFiles(publicPath: string): void;
@@ -134,6 +135,14 @@ export declare class App {
      * Registers global middlewares.
      *
      * These are executed for every route.
+     *
+     * @example
+     * const auth = async (request, next) => {
+     *    console.log(request.header);
+     *    return await next(request);
+     * }
+     *
+     * app.middlewares(auth);
      */
     middlewares(middlewares: Middleware[]): void;
     /**

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;
     }
@@ -93,6 +93,7 @@ class App {
      *
      * @example
      * app.staticFiles("public");
+     * app.staticFiles(join(__dirname, "..", "public"));
      * // /public/css/style.css → /css/style.css
      */
     staticFiles(publicPath) {
@@ -192,6 +193,14 @@ class App {
      * Registers global middlewares.
      *
      * These are executed for every route.
+     *
+     * @example
+     * const auth = async (request, next) => {
+     *    console.log(request.header);
+     *    return await next(request);
+     * }
+     *
+     * app.middlewares(auth);
      */
     middlewares(middlewares) {
         this.router.middlewares(middlewares);
@@ -228,6 +237,7 @@ class App {
             statusCode: 500,
             message: "Internal Server Error",
         }).setStatusCode(500));
+        // eslint-disable-next-line no-console
         console.error(error);
     }
 }

package/dist/crypto/hasher.d.ts

@@ -15,6 +15,9 @@ type ScryptOptions = {
  * @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.
+ *
+ * @example
+ * const passwordHash = await hash("password", 16);
  */
 export declare const hash: (password: string, saltLength?: number, params?: ScryptOptions, pepper?: string) => Promise<string>;
 /**
@@ -28,6 +31,9 @@ export declare const hash: (password: string, saltLength?: number, params?: Scry
  * @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`.
+ *
+ * @example
+ * const validPassword = await verify("password", "passwordHashed");
  */
 export declare const verify: (password: string, storedHash: string, pepper?: string) => Promise<boolean>;
 /**
@@ -42,6 +48,9 @@ export declare const verify: (password: string, storedHash: string, pepper?: str
  * @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.
+ *
+ * @example
+ * const passwordRehash = needsRehash("passwordHashed");
  */
 export declare const needsRehash: (storedHash: string, params?: ScryptOptions) => boolean;
 /**
@@ -62,13 +71,13 @@ export declare const needsRehash: (storedHash: string, params?: ScryptOptions) =
  *   - pepper: optional server secret
  *   - concurrency: max simultaneous operations (default 4)
  * @returns Array of compact hash strings in the same order as input.
+ *
+ * @example
+ *
+ * const listPasswords = ["password1", "password2", "password3"];
+ * const passwordsHasherList = await hashBatch(listPasswords, 16);
  */
-export declare const hashBatch: (passwords: string[], options?: {
-    saltLength?: number;
-    params?: ScryptOptions;
-    pepper?: string;
-    concurrency?: number;
-}) => Promise<string[]>;
+export declare const hashBatch: (passwords: string[], saltLength?: number, concurrency?: number, params?: ScryptOptions, pepper?: string) => Promise<string[]>;
 /**
  * Verifies multiple password/hash pairs using controlled concurrency.
  *
@@ -80,12 +89,12 @@ export declare const hashBatch: (passwords: string[], options?: {
  *   - pepper: optional server secret
  *   - concurrency: max simultaneous operations (default 8)
  * @returns Array of booleans in the same order as input.
+ *
+ * @example
+ * const verifyPasswords = await verifyBatch([{ password: "test", hash: "testHash" }, { password: "test2", hash: "testHash2" }]);
  */
 export declare const verifyBatch: (credentials: Array<{
     password: string;
     hash: string;
-}>, options?: {
-    pepper?: string;
-    concurrency?: number;
-}) => Promise<boolean[]>;
+}>, concurrency?: number, pepper?: string) => Promise<boolean[]>;
 export {};

package/dist/crypto/hasher.js

@@ -87,6 +87,9 @@ const parseHash = (hash) => {
  * @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.
+ *
+ * @example
+ * const passwordHash = await hash("password", 16);
  */
 const hash = async (password, saltLength = 16, params = DEFAULT_PARAMS, pepper) => {
     const salt = (0, node_crypto_1.randomBytes)(saltLength);
@@ -111,6 +114,9 @@ exports.hash = hash;
  * @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`.
+ *
+ * @example
+ * const validPassword = await verify("password", "passwordHashed");
  */
 const verify = async (password, storedHash, pepper) => {
     const parsed = parseHash(storedHash);
@@ -145,6 +151,9 @@ exports.verify = verify;
  * @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.
+ *
+ * @example
+ * const passwordRehash = needsRehash("passwordHashed");
  */
 const needsRehash = (storedHash, params = DEFAULT_PARAMS) => {
     const parsed = parseHash(storedHash);
@@ -191,13 +200,14 @@ const mapLimit = async (items, limit, fn) => {
  *   - pepper: optional server secret
  *   - concurrency: max simultaneous operations (default 4)
  * @returns Array of compact hash strings in the same order as input.
+ *
+ * @example
+ *
+ * const listPasswords = ["password1", "password2", "password3"];
+ * const passwordsHasherList = await hashBatch(listPasswords, 16);
  */
-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));
+const hashBatch = async (passwords, saltLength = 16, concurrency = 4, params = DEFAULT_PARAMS, pepper) => {
+    return mapLimit(passwords, concurrency, password => (0, exports.hash)(password, saltLength, params, pepper));
 };
 exports.hashBatch = hashBatch;
 /**
@@ -211,10 +221,11 @@ exports.hashBatch = hashBatch;
  *   - pepper: optional server secret
  *   - concurrency: max simultaneous operations (default 8)
  * @returns Array of booleans in the same order as input.
+ *
+ * @example
+ * const verifyPasswords = await verifyBatch([{ password: "test", hash: "testHash" }, { password: "test2", hash: "testHash2" }]);
  */
-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));
+const verifyBatch = async (credentials, concurrency = 8, pepper) => {
+    return mapLimit(credentials, concurrency, credential => (0, exports.verify)(credential.password, credential.hash, pepper));
 };
 exports.verifyBatch = verifyBatch;

package/dist/crypto/jwt.d.ts

@@ -1,31 +1,93 @@
+/**
+ * Represents the payload (claims set) of a JSON Web Token.
+ *
+ * A JWT payload may contain arbitrary custom claims.
+ * Common registered claims:
+ * - `exp` (Expiration Time) – Unix timestamp (seconds)
+ * - `iat` (Issued At) – Unix timestamp (seconds)
+ *
+ * Additional claims may be added depending on the application.
+ */
 interface JWTPayload {
     [key: string]: any;
     exp?: number;
     iat?: number;
 }
+/**
+ * Represents the header section of a JWT.
+ *
+ * - `alg` – Signing algorithm used
+ * - `typ` – Token type (typically `"JWT"`)
+ */
 interface JWTHeader {
     alg: string;
     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
+ * Supported JWT signing algorithms.
+ *
+ * - HS* → HMAC (symmetric secret)
+ * - RS* → RSA (asymmetric public/private key)
+ */
+type Algorithm = "HS256" | "HS384" | "HS512" | "RS256" | "RS384" | "RS512";
+/**
+ * Options used when creating a JWT.
+ */
+interface CreateJWTOptions {
+    /**
+     * Signing algorithm.
+     * Defaults to `"HS256"` if not provided.
+     */
+    algorithm?: Algorithm;
+    /**
+     * Token expiration:
+     * - Number → seconds
+     * - String → time expression (e.g. `"1h"`, `"30m"`, `"2d"`)
+     */
+    expiresIn?: number | 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.
+ *
+ * @example
+ * const jwt = createJWT({ sub: "123" }, "secret", { algorithm: "HS512", expiresIn: "1h" });
  */
-export declare const createJWT: (payload: JWTPayload, secret: string, expiresIn?: number) => string;
+export declare const createJWT: (payload: JWTPayload, secret: string | Buffer, opts?: number | string | CreateJWTOptions) => 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 signature and validity of a JWT.
+ *
+ * Returns `null` if validation fails at any step.
+ *
+ * @param token - JWT string.
+ * @param secret - Secret (HMAC) or public key (RSA).
+ * @returns Decoded payload if valid, otherwise `null`.
+ *
+ * @example
+ * const verifyToken = verifyJWT("token", "secret-key");
  */
-export declare const verifyJWT: (token: string, secret: string) => JWTPayload | null;
+export declare const verifyJWT: (token: string, secret: string | Buffer) => 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.
+ *
+ * @example
+ * conste decodeToken = decodeJWT("token");
  */
 export declare const decodeJWT: (token: string) => {
     header: JWTHeader;