@nitronjs/framework 0.3.0 → 0.3.2

package/cli/create.js

@@ -251,7 +251,8 @@ export default async function create(projectName, options = {}) {
         log(`${COLORS.red}Error: ${validation.error}${COLORS.reset}`);
         console.log();
         log(`${COLORS.dim}Run 'npx @nitronjs/framework --help' for usage information${COLORS.reset}`);
-        process.exit(1);
+        process.exitCode = 1;
+        return;
     }
 
     const projectPath = path.resolve(process.cwd(), projectName);
@@ -260,13 +261,15 @@ export default async function create(projectName, options = {}) {
         log(`${COLORS.red}Error: Directory "${projectName}" already exists${COLORS.reset}`);
         console.log();
         log(`${COLORS.dim}Please choose a different project name or remove the existing directory${COLORS.reset}`);
-        process.exit(1);
+        process.exitCode = 1;
+        return;
     }
 
     if (!fs.existsSync(SKELETON_DIR)) {
         log(`${COLORS.red}Error: Skeleton directory not found${COLORS.reset}`);
         log(`${COLORS.dim}This may indicate a corrupted installation. Try reinstalling NitronJS.${COLORS.reset}`);
-        process.exit(1);
+        process.exitCode = 1;
+        return;
     }
 
     log(`${COLORS.bold}Creating project: ${COLORS.cyan}${projectName}${COLORS.reset}`);

package/cli/njs.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 const COLORS = {
     reset: "\x1b[0m",
@@ -61,25 +61,27 @@ const args = process.argv.slice(2);
 
 if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
     printHelp();
-    process.exit(0);
+}
+else {
+    const command = args[0];
+    const additionalArgs = args.slice(1);
+
+    const KNOWN_COMMANDS = [
+        "dev", "start", "build",
+        "migrate", "migrate:rollback", "migrate:status", "migrate:fresh", "seed",
+        "storage:link",
+        "make:controller", "make:middleware", "make:model", "make:migration", "make:seeder"
+    ];
+
+    const isProjectName = command &&
+        !command.startsWith("-") &&
+        !KNOWN_COMMANDS.includes(command) &&
+        !command.startsWith("make:");
+
+    run(command, additionalArgs, isProjectName);
 }
 
-const command = args[0];
-const additionalArgs = args.slice(1);
-
-const KNOWN_COMMANDS = [
-    "dev", "start", "build",
-    "migrate", "migrate:rollback", "migrate:status", "migrate:fresh", "seed",
-    "storage:link",
-    "make:controller", "make:middleware", "make:model", "make:migration", "make:seeder"
-];
-
-const isProjectName = command &&
-    !command.startsWith("-") &&
-    !KNOWN_COMMANDS.includes(command) &&
-    !command.startsWith("make:");
-
-async function run() {
+async function run(command, additionalArgs, isProjectName) {
     try {
         if (isProjectName) {
             const { default: create } = await import("./create.js");
@@ -166,7 +168,8 @@ async function run() {
                     console.error(`${COLORS.red}Error: Name is required${COLORS.reset}`);
                     console.log(`${COLORS.dim}Usage: njs ${command} <Name>${COLORS.reset}`);
                     console.log(`${COLORS.dim}Example: njs ${command} ${type === "controller" ? "HomeController" : type === "middleware" ? "AuthMiddleware" : type === "model" ? "User" : type === "migration" ? "users" : "UserSeeder"}${COLORS.reset}`);
-                    process.exit(1);
+                    process.exitCode = 1;
+                    return;
                 }
 
                 const { default: Make } = await import("../lib/Console/Commands/MakeCommand.js");
@@ -177,7 +180,8 @@ async function run() {
             default:
                 console.error(`${COLORS.red}Error: Unknown command '${command}'${COLORS.reset}`);
                 console.log(`${COLORS.dim}Run 'njs --help' for available commands${COLORS.reset}`);
-                process.exit(1);
+                process.exitCode = 1;
+                return;
         }
 
         if (exitCode !== null) {
@@ -185,7 +189,8 @@ async function run() {
             await checkForUpdates();
             process.exit(exitCode);
         }
-    } catch (error) {
+    }
+    catch (error) {
         console.error(`${COLORS.red}Error: ${error.message}${COLORS.reset}`);
         if (process.env.DEBUG) {
             console.error(error.stack);
@@ -193,5 +198,3 @@ async function run() {
         process.exit(1);
     }
 }
-
-run();

package/lib/Auth/Auth.js

@@ -1,5 +1,6 @@
 import Hash from "../Hashing/Hash.js";
 import Config from "../Core/Config.js";
+import Mfa from "./Mfa.js";
 
 /**
  * Authentication manager for handling user login, logout, and session management.
@@ -15,21 +16,25 @@ class Auth {
         server.decorateRequest("auth", null);
 
         server.addHook("onRequest", async (req, res) => {
+            req._response = res;
+
             req.auth = {
                 guard: (guardName = null) => ({
                     attempt: (credentials) => Auth.attempt(req, credentials, guardName),
                     logout: () => Auth.logout(req, guardName),
                     user: () => Auth.user(req, guardName),
                     check: () => Auth.check(req, guardName),
-                    home: () => Auth.home(res, guardName),
-                    redirect: () => Auth.redirect(res, guardName)
+                    home: () => Auth.home(req._response, guardName),
+                    redirect: () => Auth.redirect(req._response, guardName),
+                    mfa: new Mfa(req, guardName)
                 }),
                 attempt: (credentials) => Auth.attempt(req, credentials, null),
                 logout: () => Auth.logout(req, null),
                 user: () => Auth.user(req, null),
                 check: () => Auth.check(req, null),
-                home: () => Auth.home(res, null),
-                redirect: () => Auth.redirect(res, null)
+                home: () => Auth.home(req._response, null),
+                redirect: () => Auth.redirect(req._response, null),
+                mfa: new Mfa(req, null)
             };
         });
     }

package/lib/Auth/Mfa.js

@@ -0,0 +1,518 @@
+import crypto from "crypto";
+import { TOTP, Secret } from "otpauth";
+import QRCode from "qrcode";
+import AES from "../Encryption/Encryption.js";
+import Config from "../Core/Config.js";
+
+/**
+ * Multi-Factor Authentication (MFA) manager for NitronJS.
+ * Provides TOTP-based two-factor authentication with recovery codes.
+ *
+ * This class is instantiated per-request via the Auth system.
+ * Access it through `req.auth.mfa` or `req.auth.guard("admin").mfa`.
+ *
+ * @example
+ * // Generate QR code for MFA setup
+ * const { qrCode, secret } = await req.auth.mfa.generate();
+ *
+ * // Confirm MFA setup with a code from authenticator app
+ * const result = await req.auth.mfa.confirmSetup(req.body.code);
+ *
+ * // Verify MFA code during login
+ * const verified = await req.auth.mfa.verify(req.body.code);
+ */
+class Mfa {
+    /**
+     * Creates a new MFA instance for the current request and guard.
+     * This is called automatically by the Auth system — you don't need to create it manually.
+     *
+     * @param {import("fastify").FastifyRequest} req - Fastify request object
+     * @param {string|null} guardName - Guard name (e.g., "admin", "user") or null for default
+     */
+    constructor(req, guardName = null) {
+        const authConfig = Config.all("auth");
+
+        this._req = req;
+        this._guard = guardName || authConfig.defaults.guard;
+        this._guardConfig = authConfig.guards[this._guard];
+    }
+
+    /**
+     * Generates a new TOTP secret and QR code for MFA setup.
+     * The secret is temporarily stored in the session until confirmed with `confirmSetup()`.
+     *
+     * @param {Object} [options] - Optional settings for QR code generation
+     * @param {string} [options.issuer] - App name shown in authenticator (e.g., "My App"). Defaults to APP_NAME env variable.
+     * @param {string} [options.label] - User label shown in authenticator (e.g., email or username). Defaults to the guard identifier field.
+     * @returns {Promise<{qrCode: string, secret: string, otpauthUri: string}>}
+     * - `qrCode` — Base64 data URL PNG image, ready for `<img src="...">`
+     * - `secret` — Plain text secret (for manual entry in authenticator apps)
+     * - `otpauthUri` — otpauth:// URI used to generate the QR code
+     *
+     * @example
+     * // Basic usage (uses APP_NAME env and guard identifier)
+     * const { qrCode, secret } = await req.auth.mfa.generate();
+     *
+     * // With custom issuer and label
+     * const { qrCode, secret } = await req.auth.mfa.generate({
+     *     issuer: "My App Name",
+     *     label: user.email
+     * });
+     */
+    async generate(options = {}) {
+        const user = await this._getUser();
+        const appName = options.issuer || process.env.APP_NAME || "NitronJS App";
+        const identifier = this._guardConfig.identifier;
+        const label = options.label || user[identifier] || "user";
+
+        // Create a new random TOTP secret
+        const totpSecret = new Secret();
+
+        // Create the TOTP instance with app name and user label
+        const totp = new TOTP({
+            issuer: appName,
+            label: label,
+            algorithm: "SHA1",
+            digits: 6,
+            period: 30,
+            secret: totpSecret
+        });
+
+        // Generate the otpauth:// URI for QR code
+        const otpauthUri = totp.toString();
+
+        // Generate QR code as base64 data URL (PNG image)
+        const qrCode = await QRCode.toDataURL(otpauthUri, {
+            width: 256,
+            margin: 2
+        });
+
+        // Store the secret temporarily in session until user confirms with a valid code
+        const secretBase32 = totpSecret.base32;
+
+        this._req.session.set(`mfa_setup_secret_${this._guard}`, secretBase32);
+
+        return {
+            qrCode,
+            secret: secretBase32,
+            otpauthUri
+        };
+    }
+
+    /**
+     * Confirms the MFA setup by verifying a TOTP code against the temporary secret.
+     * On success, encrypts and saves the secret to the user's `mfa` column,
+     * generates recovery codes, and clears the temporary session data.
+     *
+     * @param {string} code - 6-digit TOTP code from the authenticator app
+     * @returns {Promise<{success: boolean, recoveryCodes?: string[]}>}
+     * - On success: `{ success: true, recoveryCodes: ["XXXX-XXXX", ...] }` (8 codes)
+     * - On failure: `{ success: false }`
+     *
+     * @example
+     * const result = await req.auth.mfa.confirmSetup(req.body.code);
+     *
+     * if (result.success) {
+     *     return res.view("mfa/recovery-codes", { codes: result.recoveryCodes });
+     * }
+     *
+     * req.session.flash("error", "Invalid code, please try again");
+     * return res.redirect(route("admin.mfa.setup"));
+     */
+    async confirmSetup(code) {
+        // Get the temporary secret that was stored during generate()
+        const tempSecret = this._req.session.get(`mfa_setup_secret_${this._guard}`);
+
+        if (!tempSecret) {
+            return { success: false };
+        }
+
+        // Verify the code against the temporary secret
+        const isValid = verifyTotpCode(tempSecret, code);
+
+        if (!isValid) {
+            return { success: false };
+        }
+
+        // Code is valid — save MFA data to the database
+        const user = await this._getUser();
+
+        // Generate 8 recovery codes in XXXX-XXXX format
+        const plainRecoveryCodes = generateRecoveryCodes(8);
+
+        // Hash each recovery code with HMAC-SHA256 for secure storage
+        const hashedRecoveryCodes = plainRecoveryCodes.map(
+            recoveryCode => hashRecoveryCode(recoveryCode)
+        );
+
+        // Build the MFA data object to store in the user's mfa column
+        const mfaData = {
+            secret: AES.encrypt(tempSecret),
+            recovery_codes: hashedRecoveryCodes,
+            confirmed_at: new Date().toISOString()
+        };
+
+        // Save to user model and clear temporary session data
+        user.mfa = JSON.stringify(mfaData);
+        await user.save();
+
+        this._req.session.set(`mfa_setup_secret_${this._guard}`, null);
+
+        return {
+            success: true,
+            recoveryCodes: plainRecoveryCodes
+        };
+    }
+
+    /**
+     * Verifies a TOTP code during login.
+     * Reads the encrypted secret from the user's `mfa` column and validates the code.
+     * Allows ±1 time step (±30 seconds) for clock drift tolerance.
+     *
+     * @param {string} code - 6-digit TOTP code from the authenticator app
+     * @returns {Promise<boolean>} True if the code is valid
+     *
+     * @example
+     * const verified = await req.auth.mfa.verify(req.body.code);
+     *
+     * if (verified) {
+     *     req.auth.mfa.clearPending();
+     *     return res.redirect(route("admin.dashboard"));
+     * }
+     *
+     * req.session.flash("error", "Invalid code");
+     * return res.redirect(route("admin.mfa.verify"));
+     */
+    async verify(code) {
+        const mfaData = await this._getMfaData();
+
+        if (!mfaData || !mfaData.confirmed_at) {
+            return false;
+        }
+
+        // Decrypt the stored TOTP secret
+        const decryptedSecret = AES.decrypt(mfaData.secret);
+
+        if (!decryptedSecret) {
+            return false;
+        }
+
+        return verifyTotpCode(decryptedSecret, code);
+    }
+
+    /**
+     * Verifies a recovery code during login (when user lost access to authenticator app).
+     * Recovery codes are single-use — once verified, the code is removed from the database.
+     *
+     * @param {string} code - Recovery code in "XXXX-XXXX" format
+     * @returns {Promise<boolean>} True if the recovery code is valid
+     *
+     * @example
+     * const verified = await req.auth.mfa.verifyRecoveryCode(req.body.recovery_code);
+     *
+     * if (verified) {
+     *     req.auth.mfa.clearPending();
+     *     return res.redirect(route("admin.dashboard"));
+     * }
+     */
+    async verifyRecoveryCode(code) {
+        // Get user and parse MFA data in one query (avoid double DB call)
+        const user = await this._getUser();
+        const rawMfa = user.mfa;
+
+        if (!rawMfa) {
+            return false;
+        }
+
+        const mfaData = typeof rawMfa === "object" ? rawMfa : JSON.parse(rawMfa);
+
+        if (!mfaData.recovery_codes || mfaData.recovery_codes.length === 0) {
+            return false;
+        }
+
+        // Normalize the input: uppercase, trim whitespace
+        const normalizedCode = code.toUpperCase().trim();
+        const hashedInput = hashRecoveryCode(normalizedCode);
+
+        // Find the matching recovery code using timing-safe comparison
+        let matchIndex = -1;
+
+        for (let i = 0; i < mfaData.recovery_codes.length; i++) {
+            const storedHash = mfaData.recovery_codes[i];
+
+            if (timingSafeCompare(hashedInput, storedHash)) {
+                matchIndex = i;
+                break;
+            }
+        }
+
+        if (matchIndex === -1) {
+            return false;
+        }
+
+        // Remove the used recovery code from the array (single-use)
+        mfaData.recovery_codes.splice(matchIndex, 1);
+
+        // Save the updated MFA data back to the database
+        user.mfa = JSON.stringify(mfaData);
+        await user.save();
+
+        return true;
+    }
+
+    /**
+     * Disables MFA for the current user.
+     * Clears all MFA data (secret, recovery codes) from the database and session.
+     *
+     * Important: This method does NOT verify the user's password.
+     * You should handle confirmation (password check, etc.) in your controller before calling this.
+     *
+     * @returns {Promise<void>}
+     *
+     * @example
+     * // In your controller — verify password first, then disable
+     * const user = await req.auth.user();
+     * const passwordValid = await Hash.check(req.body.password, user.password);
+     *
+     * if (!passwordValid) {
+     *     req.session.flash("error", "Invalid password");
+     *     return res.redirect(route("admin.settings"));
+     * }
+     *
+     * await req.auth.mfa.disable();
+     */
+    async disable() {
+        const user = await this._getUser();
+
+        user.mfa = null;
+        await user.save();
+
+        // Clear any pending MFA state from the session
+        this._req.session.set(`mfa_pending_${this._guard}`, null);
+        this._req.session.set(`mfa_setup_secret_${this._guard}`, null);
+    }
+
+    /**
+     * Checks if the current user has MFA enabled (setup completed and confirmed).
+     *
+     * @returns {Promise<boolean>} True if MFA is enabled for this user
+     *
+     * @example
+     * const hasMfa = await req.auth.mfa.enabled();
+     *
+     * if (hasMfa) {
+     *     req.auth.mfa.setPending();
+     *     return res.redirect(route("admin.mfa.verify"));
+     * }
+     */
+    async enabled() {
+        const mfaData = await this._getMfaData();
+
+        if (!mfaData || !mfaData.confirmed_at) {
+            return false;
+        }
+
+        return true;
+    }
+
+    /**
+     * Checks if the current session has a pending MFA verification.
+     * Use this in your middleware to block access until MFA is verified.
+     *
+     * @returns {boolean} True if MFA verification is pending
+     *
+     * @example
+     * // In your MFA middleware:
+     * if (req.auth.mfa.isPending()) {
+     *     return res.redirect(route("admin.mfa.verify"));
+     * }
+     */
+    isPending() {
+        return this._req.session.get(`mfa_pending_${this._guard}`) === true;
+    }
+
+    /**
+     * Marks the current session as needing MFA verification.
+     * Call this after a successful `attempt()` when the user has MFA enabled.
+     *
+     * @returns {void}
+     *
+     * @example
+     * const success = await req.auth.attempt(credentials);
+     *
+     * if (success && await req.auth.mfa.enabled()) {
+     *     req.auth.mfa.setPending();
+     *     return res.redirect(route("admin.mfa.verify"));
+     * }
+     */
+    setPending() {
+        this._req.session.set(`mfa_pending_${this._guard}`, true);
+    }
+
+    /**
+     * Clears the MFA pending state from the session.
+     * Call this after a successful `verify()` or `verifyRecoveryCode()`.
+     *
+     * @returns {void}
+     *
+     * @example
+     * const verified = await req.auth.mfa.verify(req.body.code);
+     *
+     * if (verified) {
+     *     req.auth.mfa.clearPending();
+     *     return res.redirect(route("admin.dashboard"));
+     * }
+     */
+    clearPending() {
+        this._req.session.set(`mfa_pending_${this._guard}`, null);
+    }
+
+    /**
+     * Gets the current authenticated user for this guard.
+     * Internal helper used by other MFA methods.
+     *
+     * @returns {Promise<Object>} User model instance
+     * @throws {Error} If no user is authenticated
+     * @private
+     */
+    async _getUser() {
+        const authConfig = Config.all("auth");
+        const config = authConfig.guards[this._guard];
+        const userId = this._req.session.get(`auth_${this._guard}`);
+
+        if (!userId || !config) {
+            throw new Error("No authenticated user found for MFA operation");
+        }
+
+        return await config.provider.find(userId);
+    }
+
+    /**
+     * Reads and parses the MFA JSON data from the user's mfa column.
+     * Returns null if the user has no MFA data.
+     *
+     * @returns {Promise<Object|null>} Parsed MFA data or null
+     * @private
+     */
+    async _getMfaData() {
+        try {
+            const user = await this._getUser();
+            const rawMfa = user.mfa;
+
+            if (!rawMfa) {
+                return null;
+            }
+
+            // If it's already an object (some DB drivers auto-parse JSON), use it directly
+            if (typeof rawMfa === "object") {
+                return rawMfa;
+            }
+
+            return JSON.parse(rawMfa);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+
+// ============================================================
+// Helper functions (outside the class, module-level)
+// ============================================================
+
+/**
+ * Verifies a TOTP code against a base32 secret.
+ * Allows ±1 time step (±30 seconds) for clock drift tolerance.
+ *
+ * @param {string} secretBase32 - TOTP secret in base32 format
+ * @param {string} code - 6-digit code to verify
+ * @returns {boolean} True if the code is valid
+ */
+function verifyTotpCode(secretBase32, code) {
+    const totp = new TOTP({
+        algorithm: "SHA1",
+        digits: 6,
+        period: 30,
+        secret: Secret.fromBase32(secretBase32)
+    });
+
+    // validate() returns the time step difference (0, -1, +1) if valid, or null if invalid
+    // window: 1 means we accept codes from 30 seconds ago and 30 seconds in the future
+    const result = totp.validate({
+        token: code,
+        window: 1
+    });
+
+    return result !== null;
+}
+
+/**
+ * Generates an array of random recovery codes in "XXXX-XXXX" format.
+ * Uses a safe character set that excludes ambiguous characters (0/O, 1/I/L).
+ *
+ * @param {number} count - Number of recovery codes to generate
+ * @returns {string[]} Array of plain text recovery codes
+ */
+function generateRecoveryCodes(count) {
+    // Safe characters — no 0/O, 1/I/L confusion
+    const charset = "23456789ABCDEFGHJKMNPQRSTUVWXYZ";
+    const codes = [];
+
+    for (let i = 0; i < count; i++) {
+        let code = "";
+
+        // Generate 8 random characters (4 + dash + 4)
+        const randomBytes = crypto.randomBytes(8);
+
+        for (let j = 0; j < 8; j++) {
+            const index = randomBytes[j] % charset.length;
+
+            code += charset[index];
+        }
+
+        // Format as XXXX-XXXX
+        codes.push(code.slice(0, 4) + "-" + code.slice(4, 8));
+    }
+
+    return codes;
+}
+
+/**
+ * Hashes a recovery code using HMAC-SHA256 with APP_KEY.
+ * This is a one-way hash — the original code cannot be recovered.
+ *
+ * @param {string} code - Plain text recovery code
+ * @returns {string} Hex-encoded HMAC-SHA256 hash
+ */
+function hashRecoveryCode(code) {
+    return crypto
+        .createHmac("sha256", process.env.APP_KEY)
+        .update(code)
+        .digest("hex");
+}
+
+/**
+ * Performs a timing-safe comparison of two hex strings.
+ * Prevents timing attacks when comparing recovery code hashes.
+ *
+ * @param {string} a - First hex string
+ * @param {string} b - Second hex string
+ * @returns {boolean} True if the strings are equal
+ */
+function timingSafeCompare(a, b) {
+    if (a.length !== b.length) {
+        return false;
+    }
+
+    try {
+        return crypto.timingSafeEqual(
+            Buffer.from(a, "hex"),
+            Buffer.from(b, "hex")
+        );
+    }
+    catch {
+        return false;
+    }
+}
+
+export default Mfa;