@nitronjs/framework 0.1.0

package/lib/Session/Manager.js

@@ -0,0 +1,259 @@
+import crypto from "crypto";
+import Config from "../Core/Config.js";
+import Memory from "./Memory.js";
+import File from "./File.js";
+import Session from "./Session.js";
+
+/**
+ * SessionManager
+ * 
+ * Singleton that manages all sessions for the application.
+ * Handles loading, creation, persistence, and lifecycle.
+ * 
+ * Features:
+ * - Cookie-based session IDs (signed)
+ * - Pluggable storage drivers (Memory, File)
+ * - Automatic session persistence
+ * - Lifetime management and expiration
+ * - Garbage collection for expired sessions
+ */
+class SessionManager {
+    static instance = null;
+    static #isInternal = false;
+    
+    // Instance properties
+    config = null;
+    store = null;
+    ready = null;
+    gcTimer = null;
+
+    constructor () {
+        if (!SessionManager.#isInternal) {
+            throw new Error("SessionManager must be initialized with await SessionManager.getInstance()");
+        }
+    }
+
+    static getSessionConfig() {
+        return Config.all("session");
+    }
+
+    static async createInstance() {
+        SessionManager.#isInternal = true;
+        const instance = new SessionManager();
+        SessionManager.#isInternal = false;
+        
+        instance.config = this.getSessionConfig();
+        instance.config.cookie.signed = true; // Enforce signed cookies
+        // Load storage driver based on config
+        instance.store = instance.#createDriver(instance.config.driver);
+        // Store ready promise (for File driver initialization)
+        instance.ready = instance.store.ready || Promise.resolve();
+        return instance;
+    }
+
+    /**
+     * Create storage driver instance
+     * @param {string} driver - Driver name (memory, file)
+     * @returns {object} Driver instance
+     */
+    #createDriver(driver) {
+        switch (driver) {
+            case 'file':
+                return new File();
+            case 'memory':
+            default:
+                return new Memory();
+        }
+    }
+
+    /**
+     * Get singleton instance
+     */
+    static async getInstance () {
+        if (!SessionManager.instance) {
+            SessionManager.instance = await SessionManager.createInstance();
+        }
+        return SessionManager.instance;
+    }
+
+    // ========================================
+    // Session Lifecycle
+    // ========================================
+
+    /**
+     * Load existing session or create a new one
+     * 
+     * Validates cookie signature, checks session lifetime,
+     * and retrieves session data from the store.
+     * 
+     * @param {object} request - Fastify request object
+     * @param {object} response - Fastify response object
+     * @returns {Session} Session instance
+     */
+    async load (request, response) {
+        // Wait for store initialization (File driver directory setup)
+        await this.ready;
+        
+        const signedCookie = request.cookies[this.config.cookieName];
+        
+        // No cookie → new session
+        if (!signedCookie) {
+            return this.create(response);
+        }
+
+        // Verify cookie signature
+        const unsignResult = request.unsignCookie(signedCookie);
+        if (!unsignResult.valid) {
+            response.clearCookie(this.config.cookieName);
+            
+            return this.create(response);
+        }
+
+        const sessionId = unsignResult.value;
+        const sessionData = await this.store.get(sessionId);
+
+        // Session not found → new session
+        if (!sessionData) {
+            response.clearCookie(this.config.cookieName);
+
+            return this.create(response);
+        }
+
+        // Check if session expired (lifetime)
+        const lastActivity = sessionData.lastActivity || sessionData.createdAt;
+        if (Date.now() - lastActivity > this.config.lifetime) {
+            await this.store.delete(sessionId);
+            response.clearCookie(this.config.cookieName);
+
+            return this.create(response);
+        }
+
+        return new Session(sessionId, sessionData);
+    }
+
+    /**
+     * Create new session
+     * @param {object} response - Fastify response
+     * @returns {Session} New session instance
+     */
+    async create (response) {
+        const id = crypto.randomBytes(32).toString("hex");
+        const sessionData = {
+            data: {},
+            createdAt: Date.now(),
+        };
+
+        await this.store.set(id, sessionData);
+        
+        // Set signed cookie
+        const cookieOptions = { ...this.config.cookie, signed: true };
+        response.setCookie(this.config.cookieName, id, cookieOptions);
+
+        return new Session(id, sessionData);
+    }
+
+    // ========================================
+    // Garbage Collection
+    // ========================================
+
+    /**
+     * Start automatic garbage collection (every 15 minutes)
+     */
+    startGarbageCollection () {
+        if (typeof this.store.gc !== 'function') {
+            return; // Store doesn't support GC
+        }
+
+        const gcInterval = 15 * 60 * 1000; // 15 minutes
+
+        this.gcTimer = setInterval(async () => {
+            try {
+                const deleted = await this.store.gc(this.config.lifetime);
+                if (deleted > 0) {
+                    console.log(`[Session GC] Deleted ${deleted} expired sessions`);
+                }
+            }
+            catch (error) {
+                console.error('[Session GC] Error:', error.message);
+            }
+        }, gcInterval);
+
+        // Run immediately on startup
+        this.store.gc(this.config.lifetime).catch(err => {
+            console.error('[Session GC] Initial run failed:', err.message);
+        });
+    }
+
+    /**
+     * Stop garbage collection (graceful shutdown)
+     */
+    stopGarbageCollection () {
+        if (this.gcTimer) {
+            clearInterval(this.gcTimer);
+            this.gcTimer = null;
+        }
+    }
+
+    // ========================================
+    // Server Setup
+    // ========================================
+
+    /**
+     * Setup session middleware for Fastify server
+     * @param {object} server - Fastify instance
+     */
+    static async setup (server) {
+        const manager = await SessionManager.getInstance();
+        
+        server.decorateRequest("session", null);
+
+        // Load session before handling request
+        server.addHook('preHandler', async (request, response) => {
+            request.session = await manager.load(request, response);
+        });
+
+        // Handle cookie changes before response is sent
+        server.addHook('onSend', async (request, response, payload) => {
+            if (!request.session) return payload;
+
+            // Handle regeneration - set new session cookie
+            if (request.session.shouldRegenerate()) {
+                response.setCookie(
+                    manager.config.cookieName, 
+                    request.session.id, 
+                    { ...manager.config.cookie, signed: true }
+                );
+            }
+
+            return payload;
+        });
+
+        // Persist session after sending response
+        server.addHook('onResponse', async (request, response) => {
+            if (!request.session) return;
+
+            // Skip persistence for error responses (4xx/5xx)
+            if (response.statusCode >= 400) return;
+
+            // Handle regeneration - delete old session
+            if (request.session.shouldRegenerate()) {
+                const oldId = request.session.getOldId();
+                if (oldId) {
+                    await manager.store.delete(oldId);
+                }
+            }
+
+            // Persist session data
+            await manager.store.set(request.session.id, {
+                data: request.session.all(),
+                createdAt: request.session.createdAt,
+                lastActivity: Date.now(),
+            });
+        });
+
+        // Start garbage collection
+        manager.startGarbageCollection();
+    }
+}
+
+export default SessionManager;

package/lib/Session/Memory.js

@@ -0,0 +1,67 @@
+/**
+ * Memory Session Store
+ * 
+ * In-memory session storage using JavaScript Map.
+ * Fast but not persistent - all data is lost on server restart.
+ * 
+ * Use cases:
+ * - Development and testing
+ * - Single-server deployments with acceptable data loss
+ * 
+ * Production: Use File store for persistence or Redis for clustering.
+ */
+class Memory {
+    constructor () {
+        this.sessions = new Map();
+    }
+
+    /**
+     * Get session data by ID
+     * @param {string} id - Session ID
+     * @returns {object|null} Session data or null if not found
+     */
+    async get (id) {
+        return this.sessions.get(id) || null;
+    }
+
+    /**
+     * Save session data
+     * @param {string} id - Session ID
+     * @param {object} value - Session data
+     */
+    async set (id, value) {
+        this.sessions.set(id, value);
+    }
+
+    /**
+     * Delete session
+     * @param {string} id - Session ID
+     * @returns {boolean} True if deleted
+     */
+    async delete (id) {
+        return this.sessions.delete(id);
+    }
+
+    /**
+     * Garbage collection - remove expired sessions
+     * @param {number} lifetime - Session lifetime in milliseconds
+     * @returns {number} Number of deleted sessions
+     */
+    async gc (lifetime) {
+        const now = Date.now();
+        let deleted = 0;
+
+        for (const [id, sessionData] of this.sessions.entries()) {
+            const lastActivity = sessionData.lastActivity || sessionData.createdAt;
+            
+            if (now - lastActivity > lifetime) {
+                this.sessions.delete(id);
+                deleted++;
+            }
+        }
+
+        return deleted;
+    }
+}
+
+export default Memory;

package/lib/Session/Session.js

@@ -0,0 +1,196 @@
+import crypto from "crypto";
+
+/**
+ * Session
+ * 
+ * Represents a single user session with secure data storage.
+ * All data is private and accessed through controlled methods.
+ * 
+ * Features:
+ * - Private data storage (no external mutation)
+ * - CSRF token generation and verification
+ * - Flash messages (one-time messages)
+ * - Session regeneration (security)
+ * - Session destruction (logout)
+ */
+class Session {
+    // Private fields
+    #id;
+    #data;
+    #createdAt;
+    #lastActivity;
+    #flags = {
+        shouldRegenerate: false,
+        oldId: null
+    };
+
+    constructor (id, sessionData) {
+        this.#id = id;
+        this.#data = sessionData.data || {};
+        this.#createdAt = sessionData.createdAt || Date.now();
+        this.#lastActivity = sessionData.lastActivity || null;
+    }
+
+    // ========================================
+    // Getters
+    // ========================================
+
+    get id () {
+        return this.#id;
+    }
+
+    get createdAt () {
+        return this.#createdAt;
+    }
+
+    get lastActivity () {
+        return this.#lastActivity;
+    }
+
+    // ========================================
+    // Data Management
+    // ========================================
+
+    /**
+     * Get a session value
+     */
+    get (key) {
+        return this.#data[key];
+    }
+
+    /**
+     * Set a session value
+     */
+    set (key, value) {
+        this.#data[key] = value;
+    }
+
+    /**
+     * Get all session data (copy to prevent mutations)
+     */
+    all () {
+        return { ...this.#data };
+    }
+
+    // ========================================
+    // CSRF Protection
+    // ========================================
+
+    /**
+     * Generate new CSRF token
+     * @returns {string} Generated token
+     */
+    generateCsrfToken () {
+        const token = crypto.randomBytes(32).toString('hex');
+        this.set('_csrf', token);
+
+        return token;
+    }
+
+    /**
+     * Get CSRF token (generate if doesn't exist)
+     * @returns {string} CSRF token
+     */
+    getCsrfToken () {
+        return this.get('_csrf') || this.generateCsrfToken();
+    }
+
+    /**
+     * Verify CSRF token (timing-safe comparison)
+     * @param {string} token - Token to verify
+     * @returns {boolean} True if valid
+     */
+    verifyCsrfToken (token) {
+        const sessionToken = this.get('_csrf');
+        
+        if (!sessionToken || !token) return false;
+        
+        try {
+            return crypto.timingSafeEqual(
+                Buffer.from(sessionToken, 'hex'),
+                Buffer.from(token, 'hex')
+            );
+        }
+        catch {
+            return false;
+        }
+    }
+
+    // ========================================
+    // Flash Messages
+    // ========================================
+
+    /**
+     * Store a flash message (available only for the next request)
+     * @param {string} key - Message key
+     * @param {any} value - Message value
+     */
+    flash (key, value) {
+        if (!this.#data._flash) {
+            this.#data._flash = {};
+        }
+        
+        this.#data._flash[key] = value;
+    }
+
+    /**
+     * Get and remove a flash message
+     * @param {string} key - Message key
+     * @returns {any} Message value or undefined
+     */
+    getFlash (key) {
+        if (!this.#data._flash?.[key]) return undefined;
+        
+        const value = this.#data._flash[key];
+
+        delete this.#data._flash[key];
+
+        return value;
+    }
+
+    // ========================================
+    // Lifecycle Management
+    // ========================================
+
+    /**
+     * Regenerate session ID and CSRF token
+     * 
+     * Prevents session fixation attacks by creating a new session ID.
+     * Call this after login, logout, or any privilege escalation.
+     * 
+     * @returns {object} {oldId, newId}
+     */
+    regenerate () {
+        // Guard: Prevent concurrent regeneration (idempotent)
+        if (this.#flags.shouldRegenerate) {
+            return {
+                oldId: this.#flags.oldId,
+                newId: this.#id
+            };
+        }
+        
+        this.#flags.oldId = this.#id;
+        this.#id = crypto.randomBytes(32).toString('hex');
+        this.#flags.shouldRegenerate = true;
+        this.generateCsrfToken();
+        
+        return {
+            oldId: this.#flags.oldId,
+            newId: this.#id
+        };
+    }
+
+    // ========================================
+    // Internal Flags (used by Manager)
+    // ========================================
+
+    shouldRegenerate () {
+        return this.#flags.shouldRegenerate;
+    }
+
+    getOldId () {
+        return this.#flags.oldId;
+    }
+}
+
+export default Session;

package/lib/Support/Str.js

@@ -0,0 +1,100 @@
+class Str {
+    static random(length) {
+        const characters = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+        let result = "";
+        const charactersLength = characters.length;
+
+        for (let i = 0; i < length; i++) {
+            result += characters.charAt(Math.floor(Math.random() * charactersLength));
+        }
+
+        return result;
+    }
+
+    static slug(text) {
+        const normalizedInput = text
+            .toLowerCase()
+            .normalize("NFD")
+            .replace(/[\u0300-\u036f]/g, "");
+
+        const slug = normalizedInput
+            .replace(/ /g, "-")
+            .replace(/ı/g, "i")
+            .replace(/[^\w-]+/g, "");
+
+        return slug;
+    }
+
+    static ucfirst(str) {
+        if (!str) return "";
+        return str.charAt(0).toUpperCase() + str.slice(1);
+    }
+
+    static lcfirst(str) {
+        if (!str) return "";
+        return str.charAt(0).toLowerCase() + str.slice(1);
+    }
+
+    static camel(str) {
+        return str
+            .replace(/[-_\s]+(.)?/g, (_, c) => (c ? c.toUpperCase() : ""))
+            .replace(/^(.)/, (c) => c.toLowerCase());
+    }
+
+    static pascal(str) {
+        return str
+            .replace(/[-_\s]+(.)?/g, (_, c) => (c ? c.toUpperCase() : ""))
+            .replace(/^(.)/, (c) => c.toUpperCase());
+    }
+
+    static snake(str) {
+        return str
+            .replace(/([a-z])([A-Z])/g, "$1_$2")
+            .replace(/[-\s]+/g, "_")
+            .toLowerCase();
+    }
+
+    static kebab(str) {
+        return str
+            .replace(/([a-z])([A-Z])/g, "$1-$2")
+            .replace(/[_\s]+/g, "-")
+            .toLowerCase();
+    }
+
+    static limit(str, length, suffix = "...") {
+        if (!str || str.length <= length) return str;
+        return str.substring(0, length) + suffix;
+    }
+
+    static words(str, count, suffix = "...") {
+        const wordsArray = str.split(/\s+/);
+        if (wordsArray.length <= count) return str;
+        return wordsArray.slice(0, count).join(" ") + suffix;
+    }
+
+    static contains(haystack, needle) {
+        return haystack.includes(needle);
+    }
+
+    static startsWith(haystack, needle) {
+        return haystack.startsWith(needle);
+    }
+
+    static endsWith(haystack, needle) {
+        return haystack.endsWith(needle);
+    }
+
+    static replaceFirst(str, search, replace) {
+        const pos = str.indexOf(search);
+        if (pos === -1) return str;
+        return str.substring(0, pos) + replace + str.substring(pos + search.length);
+    }
+
+    static replaceLast(str, search, replace) {
+        const pos = str.lastIndexOf(search);
+        if (pos === -1) return str;
+        return str.substring(0, pos) + replace + str.substring(pos + search.length);
+    }
+}
+
+export default Str;

package/lib/Translation/Manager.js

@@ -0,0 +1,49 @@
+import fs from "fs";
+import path from "path";
+import Paths from "../Core/Paths.js";
+
+class TranslationManager {
+    static #cache = new Map();
+
+    static get(req, key, params = null) {
+        const currentLang = req.language;
+        const translation = this.#getTranslation(currentLang, key);
+
+        if (params) {
+            return this.#replaceParams(translation, params);
+        }
+
+        return translation;
+    }
+
+    static #getTranslation(lang, key) {
+        const langPath = path.join(Paths.langs, lang + ".json");
+
+        if (!fs.existsSync(langPath)) {
+            return key;
+        }
+
+        let translations = this.#cache.get(lang);
+
+        if (!translations) {
+            const langFile = fs.readFileSync(langPath, { encoding: "utf-8", flag: "r" });
+            translations = JSON.parse(langFile);
+            this.#cache.set(lang, translations);
+        }
+
+        return translations[key] || key;
+    }
+
+    static #replaceParams(text, params) {
+        Object.keys(params).forEach((key) => {
+            text = text.replaceAll(":" + key, params[key]);
+        });
+        return text;
+    }
+
+    static clearCache() {
+        this.#cache.clear();
+    }
+}
+
+export default TranslationManager;

package/lib/Validation/MimeTypes.js

@@ -0,0 +1,39 @@
+export const MIME_TYPES = {
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    png: "image/png",
+    gif: "image/gif",
+    webp: "image/webp",
+    svg: "image/svg+xml",
+    bmp: "image/bmp",
+    ico: "image/x-icon",
+    pdf: "application/pdf",
+    doc: "application/msword",
+    docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    xls: "application/vnd.ms-excel",
+    xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    ppt: "application/vnd.ms-powerpoint",
+    pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    txt: "text/plain",
+    csv: "text/csv",
+    zip: "application/zip",
+    rar: "application/x-rar-compressed",
+    "7z": "application/x-7z-compressed",
+    tar: "application/x-tar",
+    gz: "application/gzip",
+    mp3: "audio/mpeg",
+    wav: "audio/wav",
+    ogg: "audio/ogg",
+    m4a: "audio/mp4",
+    mp4: "video/mp4",
+    avi: "video/x-msvideo",
+    mov: "video/quicktime",
+    wmv: "video/x-ms-wmv",
+    flv: "video/x-flv",
+    webm: "video/webm",
+    json: "application/json",
+    xml: "application/xml",
+    js: "application/javascript",
+    css: "text/css",
+    html: "text/html"
+};