fiberx-backend-toolkit 0.0.50 → 0.0.52

package/dist/config/constants.d.ts

@@ -23,4 +23,8 @@ export declare const REQUEST_RATE_LIMITTER_OPTIONS: {
     max_requests: number;
     message: string;
 };
-export declare const ALPHABET_CORPUS: string[];
+export declare const CHARACTER_CORPUS: string[];
+export declare const ALPHABET_CORPUS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+export declare const DEFAULT_TOTP_STEP = 30;
+export declare const DEFAULT_TOTP_DIGITS = 6;
+export declare const DEFAULT_TOTP_WINDOW = 1;

package/dist/config/constants.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ALPHABET_CORPUS = exports.REQUEST_RATE_LIMITTER_OPTIONS = exports.CORS_MAX_AGE_IN_MICRO_SECONDS = exports.CORS_MAX_AGE_IN_SECONDS = exports.CORS_ALLOWED_HEADERS = exports.CORS_ALLOWED_METHODS = exports.DEVICE_ID_HEADERS_NAME = exports.DEVICE_ID_COOKIE_NAME = exports.DEVICE_ID_COOKIE_MAX_AGE = exports.REQUEST_ID_HEADERS_NAME = exports.REQUEST_ID_COOKIE_NAME = exports.REQUEST_ID_COOKIE_MAX_AGE = exports.SEQUELIZE_SEEDER_META_TABLE_NAME = exports.SEQUELIZE_META_TABLE_NAME = exports.SEEDERS_DIR = exports.MIGRATIONS_DIR = exports.MODELS_DIR = exports.SCHEMA_SNAPSHOTS_DIR = exports.SCHEMAS_DIR = exports.ENV_VAR_DIR = exports.LOG_DIR = exports.BASE_DIR = void 0;
+exports.DEFAULT_TOTP_WINDOW = exports.DEFAULT_TOTP_DIGITS = exports.DEFAULT_TOTP_STEP = exports.ALPHABET_CORPUS = exports.CHARACTER_CORPUS = exports.REQUEST_RATE_LIMITTER_OPTIONS = exports.CORS_MAX_AGE_IN_MICRO_SECONDS = exports.CORS_MAX_AGE_IN_SECONDS = exports.CORS_ALLOWED_HEADERS = exports.CORS_ALLOWED_METHODS = exports.DEVICE_ID_HEADERS_NAME = exports.DEVICE_ID_COOKIE_NAME = exports.DEVICE_ID_COOKIE_MAX_AGE = exports.REQUEST_ID_HEADERS_NAME = exports.REQUEST_ID_COOKIE_NAME = exports.REQUEST_ID_COOKIE_MAX_AGE = exports.SEQUELIZE_SEEDER_META_TABLE_NAME = exports.SEQUELIZE_META_TABLE_NAME = exports.SEEDERS_DIR = exports.MIGRATIONS_DIR = exports.MODELS_DIR = exports.SCHEMA_SNAPSHOTS_DIR = exports.SCHEMAS_DIR = exports.ENV_VAR_DIR = exports.LOG_DIR = exports.BASE_DIR = void 0;
 const path_1 = __importDefault(require("path"));
 // Database constants
 exports.BASE_DIR = process.cwd();
@@ -33,4 +33,8 @@ exports.REQUEST_RATE_LIMITTER_OPTIONS = {
     max_requests: 50,
     message: "⏳ Too many requests from this IP, please try again later"
 };
-exports.ALPHABET_CORPUS = ["6", ";", "s", "[", "w", "*", "n", "K", "h", "U", "#", "P", "T", "&", "M", "2", "}", "x", ")", "{", "|", "i", "%", "m", ":", "E", "q", "?", "0", "@", "1", "v", "A", "W", "<", "y", "Y", "4", "5", ".", "e", "G", ",", "D", "7", "I", "j", ">", "g", "t", "k", "c", "V", "9", "J", "L", "u", "H", "b", "Z", "+", '"', "'", "a", "f"];
+exports.CHARACTER_CORPUS = ["6", ";", "s", "[", "w", "*", "n", "K", "h", "U", "#", "P", "T", "&", "M", "2", "}", "x", ")", "{", "|", "i", "%", "m", ":", "E", "q", "?", "0", "@", "1", "v", "A", "W", "<", "y", "Y", "4", "5", ".", "e", "G", ",", "D", "7", "I", "j", ">", "g", "t", "k", "c", "V", "9", "J", "L", "u", "H", "b", "Z", "+", '"', "'", "a", "f"];
+exports.ALPHABET_CORPUS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+exports.DEFAULT_TOTP_STEP = 30;
+exports.DEFAULT_TOTP_DIGITS = 6;
+exports.DEFAULT_TOTP_WINDOW = 1;

package/dist/types/util_type.d.ts

@@ -45,3 +45,26 @@ export declare enum ErrorHandlingStrategyEnum {
     THROW_ERROR = 2,
     CONTROLLER_ERROR = 3
 }
+export type GenerateSecretOptionsType = {
+    name: string;
+    issuer: string;
+    length?: number;
+};
+export type VerifyResultType = {
+    valid: boolean;
+    counter?: number;
+};
+export type VerifyOptionsType = {
+    secret: string;
+    token: string;
+};
+export interface TOTPServiceOptions {
+    STEP?: number;
+    DIGITS?: number;
+    WINDOW?: number;
+    ALGORITHM?: "SHA1" | "SHA256" | "SHA512";
+}
+export interface GenerateSecretResult {
+    secret_key: string;
+    otpauth_url: string;
+}

package/dist/types/util_type.js

@@ -8,3 +8,4 @@ var ErrorHandlingStrategyEnum;
     ErrorHandlingStrategyEnum[ErrorHandlingStrategyEnum["THROW_ERROR"] = 2] = "THROW_ERROR";
     ErrorHandlingStrategyEnum[ErrorHandlingStrategyEnum["CONTROLLER_ERROR"] = 3] = "CONTROLLER_ERROR";
 })(ErrorHandlingStrategyEnum || (exports.ErrorHandlingStrategyEnum = ErrorHandlingStrategyEnum = {}));
+;

package/dist/utils/encryptor_decryptor_util.js

@@ -14,7 +14,7 @@ class EncryptorDecryptorUtil {
     static instance;
     encrypt_secret_key;
     corpus_shift_key;
-    corpus = constants_1.ALPHABET_CORPUS;
+    corpus = constants_1.CHARACTER_CORPUS;
     algorithm = "aes-256-cbc";
     iv_length = 16;
     jwt_secret_key;

package/dist/utils/input_validator_util.js

@@ -9,7 +9,6 @@ const dayjs_1 = __importDefault(require("dayjs"));
 const isSameOrAfter_1 = __importDefault(require("dayjs/plugin/isSameOrAfter"));
 const bcrypt_1 = __importDefault(require("bcrypt"));
 const axios_1 = __importDefault(require("axios"));
-// import speakeasy        from "speakeasy";
 const env_manager_util_1 = __importDefault(require("../utils/env_manager_util"));
 dayjs_1.default.extend(isSameOrAfter_1.default);
 class InputValidatorUtil {

package/dist/utils/totp_service_util.d.ts

@@ -0,0 +1,21 @@
+import { GenerateSecretOptionsType, VerifyResultType, VerifyOptionsType, TOTPServiceOptions, GenerateSecretResult } from "../types/util_type";
+declare class TOTPServiceUtil {
+    readonly name = "totp_service_util";
+    private static instance;
+    private logger;
+    private readonly STEP;
+    private readonly DIGITS;
+    private readonly WINDOW;
+    private readonly ALGORITHM;
+    private readonly SECRET_KEY_REGEX;
+    private constructor();
+    static getInstance(options?: TOTPServiceOptions): TOTPServiceUtil;
+    private base32Decode;
+    private base32Encode;
+    private generateForCounter;
+    generateSecret(options: GenerateSecretOptionsType): GenerateSecretResult;
+    verify(options: VerifyOptionsType & {
+        last_used_counter?: number;
+    }): VerifyResultType;
+}
+export default TOTPServiceUtil;

package/dist/utils/totp_service_util.js

@@ -0,0 +1,158 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const crypto_1 = __importDefault(require("crypto"));
+const constants_1 = require("../config/constants");
+const logger_util_1 = __importDefault(require("./logger_util"));
+const input_validator_util_1 = __importDefault(require("./input_validator_util"));
+class TOTPServiceUtil {
+    name = "totp_service_util";
+    static instance;
+    logger = new logger_util_1.default(this.name);
+    // ===============================
+    // CONFIG
+    // ===============================
+    STEP;
+    DIGITS;
+    WINDOW;
+    ALGORITHM;
+    SECRET_KEY_REGEX = (/^[A-Z2-7]+$/i);
+    constructor(options = {}) {
+        this.STEP = options.STEP ?? constants_1.DEFAULT_TOTP_STEP;
+        this.DIGITS = options.DIGITS ?? constants_1.DEFAULT_TOTP_DIGITS;
+        this.WINDOW = options.WINDOW ?? constants_1.DEFAULT_TOTP_WINDOW;
+        this.ALGORITHM = options.ALGORITHM?.toLowerCase() ?? "sha1";
+    }
+    // ✅ Global access point
+    static getInstance(options = {}) {
+        if (!TOTPServiceUtil.instance) {
+            TOTPServiceUtil.instance = new TOTPServiceUtil(options);
+        }
+        return TOTPServiceUtil.instance;
+    }
+    // ===============================
+    // BASE32 DECODE
+    // ===============================
+    base32Decode(input) {
+        if (!/^[A-Z2-7]+=*$/i.test(input)) {
+            throw new Error("Invalid base32 secret");
+        }
+        const alphabet = constants_1.ALPHABET_CORPUS;
+        const cleaned = input.replace(/=+$/, "").toUpperCase();
+        let bits = 0;
+        let value = 0;
+        const output = [];
+        for (const char of cleaned) {
+            const idx = alphabet.indexOf(char);
+            if (idx === -1) {
+                throw new Error("Invalid base32 character while decoding base 32 for totp service util");
+            }
+            value = (value << 5) | idx;
+            bits += 5;
+            if (bits >= 8) {
+                output.push((value >>> (bits - 8)) & 255);
+                bits -= 8;
+            }
+        }
+        return Buffer.from(output);
+    }
+    // ===============================
+    // BASE32 ENCODE
+    // ===============================
+    base32Encode(buffer) {
+        const alphabet = constants_1.ALPHABET_CORPUS;
+        let bits = 0;
+        let value = 0;
+        let output = "";
+        for (const byte of buffer) {
+            value = (value << 8) | byte;
+            bits += 8;
+            while (bits >= 5) {
+                output += alphabet[(value >>> (bits - 5)) & 31];
+                bits -= 5;
+            }
+        }
+        if (bits > 0) {
+            output += alphabet[(value << (5 - bits)) & 31];
+        }
+        return output;
+    }
+    // ===============================
+    // INTERNAL: GENERATE OTP
+    // ===============================
+    generateForCounter(secret, counter) {
+        const buffer = Buffer.alloc(8);
+        buffer.writeBigUInt64BE(BigInt(counter));
+        const hmac = crypto_1.default
+            .createHmac(this.ALGORITHM, secret)
+            .update(buffer)
+            .digest();
+        const offset = hmac[hmac.length - 1] & 0xf;
+        const code = ((hmac[offset] & 0x7f) << 24) |
+            ((hmac[offset + 1] & 0xff) << 16) |
+            ((hmac[offset + 2] & 0xff) << 8) |
+            (hmac[offset + 3] & 0xff);
+        const otp = code % 10 ** this.DIGITS;
+        return otp.toString().padStart(this.DIGITS, "0");
+    }
+    // ===============================
+    // PUBLIC: GENERATE SECRET
+    // ===============================
+    generateSecret(options) {
+        const { name, issuer, length = 20 } = options;
+        const buffer = crypto_1.default.randomBytes(length);
+        const base32 = this.base32Encode(buffer);
+        const encoder_issuer = encodeURIComponent(issuer);
+        const encoded_name = encodeURIComponent(name);
+        const otpauth_url = `otpauth://totp/${encoder_issuer}:${encoded_name}` +
+            `?secret=${base32}` +
+            `&issuer=${encoder_issuer}` +
+            `&algorithm=${this.ALGORITHM.toUpperCase()}` +
+            `&digits=${this.DIGITS}` +
+            `&period=${this.STEP}`;
+        return {
+            secret_key: base32,
+            otpauth_url,
+        };
+    }
+    // ===============================
+    // PUBLIC: VERIFY TOKEN
+    // ===============================
+    verify(options) {
+        const { secret, token, last_used_counter } = options;
+        if (!/^\d+$/.test(token)) {
+            return { valid: false };
+        }
+        if (token.length !== this.DIGITS) {
+            return { valid: false };
+        }
+        if (!this.SECRET_KEY_REGEX.test(secret)) {
+            throw new Error("Invalid TOTP secret format");
+        }
+        let key;
+        try {
+            key = this.base32Decode(secret);
+        }
+        catch (error) {
+            this.logger.error("Failed to decode TOTP secret");
+            return { valid: false };
+        }
+        const time = Math.floor(Date.now() / 1000 / this.STEP);
+        for (let error_window = -this.WINDOW; error_window <= this.WINDOW; error_window++) {
+            const counter = time + error_window;
+            const generated = this.generateForCounter(key, counter);
+            if (input_validator_util_1.default.isSafeHashCompare(generated, token)) {
+                // 🔒 Replay protection
+                if (typeof last_used_counter === "number" &&
+                    counter <= last_used_counter) {
+                    return { valid: false };
+                }
+                return { valid: true, counter };
+            }
+        }
+        return { valid: false };
+    }
+}
+exports.default = TOTPServiceUtil;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "fiberx-backend-toolkit",
-    "version": "0.0.50",
+    "version": "0.0.52",
     "description": "A TypeScript backend toolkit providing shared domain logic, infrastructure helpers, and utilities for FiberX server-side applications and services.",
     "type": "commonjs",
     "main": "./dist/index.js",