@seip/blue-bird 1.0.2 → 1.1.1

package/core/hash.js

@@ -0,0 +1,201 @@
+import crypto from "node:crypto";
+
+let bcryptModule = null;
+try {
+  bcryptModule = (await import("bcrypt")).default || (await import("bcrypt"));
+} catch {
+  // bcrypt not installed, scrypt native is used
+}
+
+/**
+ * High-performance Password Hashing class.
+ * Uses native node:crypto scrypt by default (zero npm dependencies, NIST recommended),
+ * with seamless support for bcrypt when installed or verifying bcrypt hashes.
+ */
+class Hash {
+  /**
+   * Hashes a plain text password using scrypt (default) or bcrypt.
+   * @param {string} password - The plain text password.
+   * @param {Object} [options={}] - Hashing options.
+   * @param {string} [options.driver="scrypt"] - Hashing driver ('scrypt' or 'bcrypt').
+   * @param {number} [options.rounds=10] - Salt rounds for bcrypt (if driver is 'bcrypt').
+   * @param {number} [options.N=16384] - CPU/memory cost parameter for scrypt.
+   * @param {number} [options.r=8] - Block size for scrypt.
+   * @param {number} [options.p=1] - Parallelization parameter for scrypt.
+   * @returns {Promise<string>} Formatted password hash string.
+   * @example
+   * const hash = await Hash.make("mySecretPassword");
+   * // Using bcrypt:
+   * const bcryptHash = await Hash.make("mySecretPassword", { driver: "bcrypt" });
+   */
+  static async make(password, options = {}) {
+    if (typeof password !== "string" || !password) {
+      throw new Error("[HASH ERROR] Password must be a non-empty string.");
+    }
+
+    const driver = (options.driver || "scrypt").toLowerCase();
+
+    if (driver === "bcrypt") {
+      if (!bcryptModule) {
+        throw new Error(
+          "[HASH ERROR] 'bcrypt' package is not installed. Run 'npm install bcrypt' or 'npx blue-bird add bcrypt', or use the default scrypt driver.",
+        );
+      }
+      const rounds = options.rounds || 10;
+      return bcryptModule.hash(password, rounds);
+    }
+
+    // Default: native scrypt with random salt
+    const N = options.N || 16384;
+    const r = options.r || 8;
+    const p = options.p || 1;
+    const keylen = 64;
+    const salt = crypto.randomBytes(16);
+
+    return new Promise((resolve, reject) => {
+      crypto.scrypt(
+        password,
+        salt,
+        keylen,
+        { N, r, p, maxmem: 32 * 1024 * 1024 },
+        (err, derivedKey) => {
+          if (err) return reject(err);
+          const hashString = `$scrypt$N=${N},r=${r},p=${p}$${salt.toString("hex")}$${derivedKey.toString("hex")}`;
+          resolve(hashString);
+        },
+      );
+    });
+  }
+
+  /**
+   * Alias for make().
+   * @param {string} password - The plain text password.
+   * @param {Object} [options={}] - Options.
+   * @returns {Promise<string>}
+   */
+  static async hash(password, options = {}) {
+    return this.make(password, options);
+  }
+
+  /**
+   * Verifies a plain text password against a hash string.
+   * Automatically detects scrypt or bcrypt hash formats.
+   * Uses timing-safe comparison to protect against side-channel attacks.
+   *
+   * @param {string} password - The plain text password to check.
+   * @param {string} hash - The stored hash string.
+   * @returns {Promise<boolean>} True if password matches, false otherwise.
+   * @example
+   * const isValid = await Hash.verify("mySecretPassword", storedHash);
+   */
+  static async verify(password, hash) {
+    if (
+      typeof password !== "string" ||
+      !password ||
+      typeof hash !== "string" ||
+      !hash
+    ) {
+      return false;
+    }
+
+    // 1. Detect bcrypt hash format ($2a$, $2b$, $2y$)
+    if (/^\$2[aby]\$\d{2}\$/.test(hash)) {
+      if (!bcryptModule) {
+        console.error(
+          "[HASH ERROR] A bcrypt hash was detected, but the 'bcrypt' package is not installed. Run 'npm install bcrypt' or 'npx blue-bird add bcrypt'.",
+        );
+        return false;
+      }
+      try {
+        return await bcryptModule.compare(password, hash);
+      } catch {
+        return false;
+      }
+    }
+
+    // 2. Detect native scrypt format ($scrypt$N=...,r=...,p=...$salt$hash)
+    if (hash.startsWith("$scrypt$")) {
+      const parts = hash.split("$");
+      // Format: ["", "scrypt", "N=16384,r=8,p=1", "saltHex", "hashHex"]
+      if (parts.length !== 5) return false;
+
+      const paramsStr = parts[2];
+      const saltHex = parts[3];
+      const originalHashHex = parts[4];
+
+      if (!paramsStr || !saltHex || !originalHashHex) return false;
+
+      let N = 16384,
+        r = 8,
+        p = 1;
+      paramsStr.split(",").forEach((param) => {
+        const [k, v] = param.split("=");
+        if (k === "N") N = parseInt(v, 10) || N;
+        if (k === "r") r = parseInt(v, 10) || r;
+        if (k === "p") p = parseInt(v, 10) || p;
+      });
+
+      const salt = Buffer.from(saltHex, "hex");
+      const originalHash = Buffer.from(originalHashHex, "hex");
+
+      return new Promise((resolve) => {
+        crypto.scrypt(
+          password,
+          salt,
+          originalHash.length,
+          { N, r, p, maxmem: 32 * 1024 * 1024 },
+          (err, derivedKey) => {
+            if (err) return resolve(false);
+            try {
+              const matches = crypto.timingSafeEqual(originalHash, derivedKey);
+              resolve(matches);
+            } catch {
+              resolve(false);
+            }
+          },
+        );
+      });
+    }
+
+    return false;
+  }
+
+  /**
+   * Alias for verify().
+   * @param {string} password - The plain text password.
+   * @param {string} hash - The stored hash string.
+   * @returns {Promise<boolean>}
+   */
+  static async check(password, hash) {
+    return this.verify(password, hash);
+  }
+
+  /**
+   * Checks if a given hash needs to be rehashed to match updated security parameters.
+   * @param {string} hash - The stored hash string.
+   * @param {Object} [options={}] - Target options.
+   * @returns {boolean} True if the hash should be regenerated.
+   */
+  static needsRehash(hash, options = {}) {
+    if (!hash || typeof hash !== "string") return true;
+    const targetDriver = (options.driver || "scrypt").toLowerCase();
+
+    if (targetDriver === "bcrypt") {
+      return !/^\$2[aby]\$\d{2}\$/.test(hash);
+    }
+
+    if (!hash.startsWith("$scrypt$")) return true;
+
+    const parts = hash.split("$");
+    if (parts.length !== 5) return true;
+
+    const paramsStr = parts[2];
+    const targetN = options.N || 16384;
+    const targetR = options.r || 8;
+    const targetP = options.p || 1;
+
+    return !paramsStr.includes(`N=${targetN},r=${targetR},p=${targetP}`);
+  }
+}
+
+export default Hash;

package/core/index.d.ts

@@ -1,137 +1,194 @@
-import { Router as ExpressRouter, Request, Response, NextFunction } from "express";
-
-declare global {
-  namespace Express {
-    interface Response {
-      /**
-       * Sends a standardized JSON success response.
-       * @param data Data payload to return.
-       * @param message Success message.
-       * @param statusCode HTTP status code (default: 200).
-       */
-      success(data?: any, message?: string, statusCode?: number): Response;
-
-      /**
-       * Sends a standardized JSON error response.
-       * @param message Error message.
-       * @param statusCode HTTP status code (default: 400).
-       * @param errors Array or object of detailed errors.
-       */
-      error(message?: string, statusCode?: number, errors?: any): Response;
-
-      /**
-       * Sends a standardized paginated JSON response.
-       * @param data Array of records for current page.
-       * @param pagination Object containing page, limit, and total count.
-       * @param message Success message.
-       */
-      paginate(
-        data?: any[],
-        pagination?: { page?: number; limit?: number; total?: number },
-        message?: string
-      ): Response;
-    }
-  }
-}
-
-export class AppError extends Error {
-  statusCode: number;
-  errors: any;
-  isOperational: boolean;
-
-  constructor(message: string, statusCode?: number, errors?: any);
-}
-
-export class App {
-  constructor(options?: {
-    routes?: any[];
-    cors?: any;
-    middlewares?: any[];
-    port?: number | string;
-    host?: string;
-    logger?: boolean;
-    notFound?: boolean;
-    json?: boolean;
-    urlencoded?: boolean;
-    static?: { path: string; options?: any };
-    cookieParser?: boolean;
-    rateLimit?: boolean | any;
-    swagger?: boolean | any;
-    compression?: boolean;
-  });
-
-  use(record: any): void;
-  set(key: string, value: any): void;
-  websocket(
-    options?:
-      | ((ws: any, req: any) => void)
-      | { path?: string; auth?: boolean }
-  ): WebSocketManager;
-  run(): void;
-
-  static helmet(options?: any): any;
-}
-
-export class WebSocketManager {
-  constructor(server: any, options?: { path?: string; auth?: boolean });
-  onConnection(handler: (ws: any, req: any) => void): void;
-  join(room: string, ws: any): void;
-  leave(room: string, ws: any): void;
-  broadcast(data: any, room?: string | null): void;
-}
-
-export class Router {
-  constructor(path?: string, options?: { seo?: boolean; languages?: string[] });
-
-  use(...middleware: any[]): void;
-  get(path: string | RegExp, ...callback: any[]): void;
-  post(path: string | RegExp, ...callback: any[]): void;
-  put(path: string | RegExp, ...callback: any[]): void;
-  delete(path: string | RegExp, ...callback: any[]): void;
-  patch(path: string | RegExp, ...callback: any[]): void;
-  options(path: string | RegExp, ...callback: any[]): void;
-  getRouter(): ExpressRouter;
-  getPath(): string;
-}
-
-export class Validator {
-  constructor(schema: Record<string, any>, lang?: string);
-  middleware(): (req: Request, res: Response, next: NextFunction) => void;
-  validate(data: Record<string, any>): { valid: boolean; errors: any[] };
-}
-
-export class Auth {
-  static encrypt(payload: any, secret: string): string;
-  static decrypt(data: string, secret: string): any;
-  static generateToken(payload: any, secret?: string, expiresIn?: string | number): string;
-  static verifyToken(token: string, secret?: string): any;
-  static protect(options?: { redirect?: string | null; key?: string; cookieKey?: string }): (req: Request, res: Response, next: NextFunction) => Promise<any>;
-  static login(res: Response, data: any, key?: string, options?: { expiresIn?: string | number; cookie?: any }): Promise<string>;
-  static logout(res: Response, key?: string, options?: any, req?: Request): Promise<boolean>;
-}
-
-export class Cache {
-  static middleware(seconds?: number): (req: Request, res: Response, next: NextFunction) => Promise<any>;
-  static get(key: string): Promise<any | null>;
-  static set(key: string, value: any, seconds?: number): Promise<boolean>;
-  static delete(keys: string | string[]): Promise<boolean>;
-  static del(keys: string | string[]): Promise<boolean>;
-  static clear(): Promise<boolean>;
-}
-
-export function getRedisClient(): any;
-
-export class Database {
-  constructor(connectionLimit?: number, queueLimit?: number, config?: any);
-  init(retries?: number): Promise<boolean>;
-  query(sql: string, params?: any[], options?: any): Promise<any>;
-  paginate(
-    sql: string,
-    params?: any[],
-    options?: { page?: number; limit?: number; cache?: number }
-  ): Promise<{ data: any[]; total: number; page: number; limit: number; totalPages: number }>;
-  transaction<T = any>(callback: (tx: { query: (sql: string, params?: any[], options?: any) => Promise<any> }) => Promise<T>): Promise<T>;
-  executeTransaction<T = any>(callback: (tx: { query: (sql: string, params?: any[], options?: any) => Promise<any> }) => Promise<T>): Promise<T>;
-}
-
-export default App;
+import { Router as ExpressRouter, Request, Response, NextFunction } from "express";
+
+declare global {
+  namespace Express {
+    interface Response {
+      /**
+       * Sends a standardized JSON success response.
+       * @param data Data payload to return.
+       * @param message Success message.
+       * @param statusCode HTTP status code (default: 200).
+       */
+      success(data?: any, message?: string, statusCode?: number): Response;
+
+      /**
+       * Sends a standardized HTTP 200 OK success response.
+       * @param data Data payload.
+       * @param message Success message.
+       */
+      ok(data?: any, message?: string): Response;
+
+      /**
+       * Sends a standardized HTTP 201 Created success response.
+       * @param data Data payload.
+       * @param message Success message.
+       */
+      created(data?: any, message?: string): Response;
+
+      /**
+       * Sends a standardized HTTP 400 Bad Request error response.
+       * @param message Error message.
+       * @param errors Detailed errors array or object.
+       */
+      badRequest(message?: string, errors?: any): Response;
+
+      /**
+       * Sends a standardized HTTP 401 Unauthorized error response.
+       * @param message Error message.
+       */
+      unauthorized(message?: string): Response;
+
+      /**
+       * Sends a standardized HTTP 403 Forbidden error response.
+       * @param message Error message.
+       */
+      forbidden(message?: string): Response;
+
+      /**
+       * Sends a standardized HTTP 404 Not Found error response.
+       * @param message Error message.
+       */
+      notFound(message?: string): Response;
+
+      /**
+       * Sends a standardized HTTP 500 Internal Server Error response.
+       * @param message Error message.
+       * @param errors Error details.
+       */
+      serverError(message?: string, errors?: any): Response;
+
+      /**
+       * Sends a standardized JSON error response.
+       * @param message Error message.
+       * @param statusCode HTTP status code (default: 400).
+       * @param errors Array or object of detailed errors.
+       */
+      error(message?: string, statusCode?: number, errors?: any): Response;
+
+      /**
+       * Sends a standardized paginated JSON response.
+       * @param data Array of records for current page.
+       * @param pagination Object containing page, limit, and total count.
+       * @param message Success message.
+       */
+      paginate(
+        data?: any[],
+        pagination?: { page?: number; limit?: number; total?: number },
+        message?: string
+      ): Response;
+    }
+  }
+}
+
+export class AppError extends Error {
+  statusCode: number;
+  errors: any;
+  isOperational: boolean;
+
+  constructor(message: string, statusCode?: number, errors?: any);
+}
+
+export class App {
+  constructor(options?: {
+    routes?: any[];
+    cors?: any;
+    middlewares?: any[];
+    port?: number | string;
+    host?: string;
+    logger?: boolean;
+    notFound?: boolean;
+    json?: boolean;
+    urlencoded?: boolean;
+    static?: { path: string; options?: any };
+    cookieParser?: boolean;
+    rateLimit?: boolean | any;
+    swagger?: boolean | any;
+    compression?: boolean;
+  });
+
+  use(record: any): void;
+  set(key: string, value: any): void;
+  websocket(
+    options?:
+      | ((ws: any, req: any) => void)
+      | { path?: string; auth?: boolean }
+  ): WebSocketManager;
+  run(): void;
+
+  static helmet(options?: any): any;
+}
+
+export class WebSocketManager {
+  constructor(server: any, options?: { path?: string; auth?: boolean });
+  onConnection(handler: (ws: any, req: any) => void): void;
+  join(room: string, ws: any): void;
+  leave(room: string, ws: any): void;
+  broadcast(data: any, room?: string | null): void;
+}
+
+export class Router {
+  constructor(path?: string, options?: { seo?: boolean; languages?: string[] });
+
+  use(...middleware: any[]): void;
+  get(path: string | RegExp, ...callback: any[]): void;
+  post(path: string | RegExp, ...callback: any[]): void;
+  put(path: string | RegExp, ...callback: any[]): void;
+  delete(path: string | RegExp, ...callback: any[]): void;
+  patch(path: string | RegExp, ...callback: any[]): void;
+  options(path: string | RegExp, ...callback: any[]): void;
+  getRouter(): ExpressRouter;
+  getPath(): string;
+}
+
+export class Validator {
+  constructor(schema: Record<string, any>, lang?: string);
+  middleware(): (req: Request, res: Response, next: NextFunction) => void;
+  validate(data: Record<string, any>): { valid: boolean; errors: any[] };
+}
+
+export class Hash {
+  static make(password: string, options?: { driver?: "scrypt" | "bcrypt"; rounds?: number; N?: number; r?: number; p?: number }): Promise<string>;
+  static hash(password: string, options?: { driver?: "scrypt" | "bcrypt"; rounds?: number; N?: number; r?: number; p?: number }): Promise<string>;
+  static verify(password: string, hash: string): Promise<boolean>;
+  static check(password: string, hash: string): Promise<boolean>;
+  static needsRehash(hash: string, options?: { driver?: "scrypt" | "bcrypt"; N?: number; r?: number; p?: number }): boolean;
+}
+
+export class Auth {
+  static encrypt(payload: any, secret: string): string;
+  static decrypt(data: string, secret: string): any;
+  static generateToken(payload: any, secret?: string, expiresIn?: string | number): string;
+  static verifyToken(token: string, secret?: string): any;
+  static protect(options?: { redirect?: string | null; key?: string; cookieKey?: string }): (req: Request, res: Response, next: NextFunction) => Promise<any>;
+  static login(res: Response, data: any, key?: string, options?: { expiresIn?: string | number; cookie?: any }): Promise<string>;
+  static logout(res: Response, key?: string, options?: any, req?: Request): Promise<boolean>;
+}
+
+export class Cache {
+  static middleware(seconds?: number): (req: Request, res: Response, next: NextFunction) => Promise<any>;
+  static get(key: string): Promise<any | null>;
+  static set(key: string, value: any, seconds?: number): Promise<boolean>;
+  static delete(keys: string | string[]): Promise<boolean>;
+  static del(keys: string | string[]): Promise<boolean>;
+  static clear(): Promise<boolean>;
+  static getMode(): string;
+}
+
+export function getRedisClient(): any;
+
+export class Database {
+  constructor(connectionLimit?: number, queueLimit?: number, config?: any);
+  init(retries?: number): Promise<boolean>;
+  query(sql: string, params?: any[], options?: any): Promise<any>;
+  paginate(
+    sql: string,
+    params?: any[],
+    options?: { page?: number; limit?: number; cache?: number }
+  ): Promise<{ data: any[]; total: number; page: number; limit: number; totalPages: number }>;
+  transaction<T = any>(callback: (tx: { query: (sql: string, params?: any[], options?: any) => Promise<any> }) => Promise<T>): Promise<T>;
+  executeTransaction<T = any>(callback: (tx: { query: (sql: string, params?: any[], options?: any) => Promise<any> }) => Promise<T>): Promise<T>;
+  close(): Promise<void>;
+}
+
+export default App;
+