free-framework 4.4.0

package/runtime/views/error.free

@@ -0,0 +1,104 @@
+/**
+* runtime/views/error.free
+*
+* Premium System Diagnostic & Error Interface.
+*/
+
+component Error {
+  style {
+    :root {
+      --error-primary: #ff3366;
+      --error-glow: rgba(255, 51, 102, 0.4);
+    }
+    .error-container {
+      min-height: 100vh;
+      background: #050505;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      padding: 2rem;
+    }
+    .error-card {
+      max-width: 800px;
+      width: 100%;
+      background: rgba(15, 15, 15, 0.8);
+      backdrop-filter: blur(32px);
+      border: 1px solid rgba(255, 51, 102, 0.2);
+      border-radius: 32px;
+      padding: 4rem;
+      box-shadow: 0 40px 100px rgba(0, 0, 0, 0.8), 0 0 40px var(--error-glow);
+      text-align: center;
+    }
+    .error-code {
+      font-size: 8rem;
+      font-weight: 950;
+      line-height: 1;
+      background: linear-gradient(135deg, #ff3366, #ff8833);
+      -webkit-background-clip: text;
+      -webkit-text-fill-color: transparent;
+      letter-spacing: -0.05em;
+      margin-bottom: 2rem;
+    }
+    .stack-trace {
+      text-align: left;
+      background: rgba(0, 0, 0, 0.3);
+      border: 1px solid rgba(255, 255, 255, 0.05);
+      border-radius: 16px;
+      padding: 2rem;
+      font-family: 'JetBrains Mono', 'Fira Code', monospace;
+      font-size: 0.75rem;
+      color: rgba(255, 255, 255, 0.4);
+      overflow-x: auto;
+      margin: 2rem 0;
+      max-height: 300px;
+    }
+    .btn-return {
+      display: inline-block;
+      padding: 1rem 2.5rem;
+      background: white;
+      color: black;
+      font-weight: 900;
+      text-transform: uppercase;
+      letter-spacing: 0.1em;
+      border-radius: 16px;
+      transition: 0.3s;
+      text-decoration: none;
+    }
+    .btn-return:hover {
+      background: var(--error-primary);
+      transform: scale(1.05);
+      box-shadow: 0 0 30px var(--error-glow);
+    }
+  }
+
+  div class="error-container" {
+    div class="error-card animate-fade-in" {
+      div class="error-code" { text "{props.status}" }
+
+      h1 class="text-3xl font-black mb-4 tracking-tight" {
+        text "SYSTEM MALFUNCTION"
+      }
+
+      p class="text-gray-400 text-lg mb-8" {
+        text "{props.message}"
+      }
+
+      condition props.stack {
+        div class="stack-trace" {
+          loop props.stack line {
+            div { text "{line}" }
+          }
+        }
+      }
+
+      div class="flex gap-4 justify-center" {
+        link "GO BACK HOME" "/" class="btn-return"
+        link "DASHBOARD" "/dashboard" class="btn-return bg-transparent border border-white/10 text-white"
+      }
+
+      div class="mt-12 pt-12 border-t border-white/5 opacity-30 text-[10px] font-bold tracking-widest uppercase" {
+        text "Free Ultra Diagnostics Engine v4.0.2"
+      }
+    }
+  }
+}

package/template-engine/renderer.js

@@ -0,0 +1,24 @@
+/**
+ * template-engine/renderer.js
+ * Simple renderer for the Free framework.
+ * Currently wraps EJS but provides a hook for custom syntax.
+ */
+
+const ejs = require("ejs");
+const path = require("path");
+
+class Renderer {
+    static async render(viewName, data = {}, options = {}) {
+        const viewsPath = process.env.VIEWS_PATH || path.join(process.cwd(), "views");
+        const filePath = path.join(viewsPath, `${viewName}.ejs`);
+
+        return new Promise((resolve, reject) => {
+            ejs.renderFile(filePath, data, options, (err, str) => {
+                if (err) return reject(err);
+                resolve(str);
+            });
+        });
+    }
+}
+
+module.exports = { Renderer };

package/templates/app-template/.env

@@ -0,0 +1,23 @@
+# Free Framework Core Template Configuration
+# Production-ready defaults for Database, Security, and Routing
+
+# ── Database (MySQL Recommended) ──────────────────────────────────────────
+DB_CLIENT=mysql2
+DB_HOST=127.0.0.1
+DB_PORT=3306
+DB_USER=root
+DB_PASS=
+DB_NAME=free_db_default
+
+# Connection Pooling Settings
+DB_POOL_MIN=5
+DB_POOL_MAX=20
+
+# ── Security & Authentication ──────────────────────────────────────────────
+# Change these secrets in production!
+APP_KEY=base64:free_secret_key_change_me_in_production
+JWT_SECRET=super_secret_jwt_key_that_should_be_long_and_random
+
+# ── Server configuration ───────────────────────────────────────────────────
+PORT=3000
+NODE_ENV=development

package/templates/app-template/app/Exceptions/Handler.js

@@ -0,0 +1,65 @@
+/**
+ * app/Exceptions/Handler.js
+ * 
+ * --------------------------------------------------------------------------
+ * Global Exception Handler
+ * --------------------------------------------------------------------------
+ * 
+ * This file acts as a centralized "catch-all" for any errors thrown in your
+ * application. Instead of crashing the node process or showing users a 
+ * raw stack trace, this handler elegantly formats the response based on the
+ * environment (production vs local) and logs it to storage/logs/.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const config = require('../../config/app');
+
+module.exports = function GlobalExceptionHandler(err, req, res) {
+    // 1. Determine HTTP Status Code (Default to 500 Internal Server Error)
+    const status = err.status || 500;
+
+    // 2. Log the error to storage/logs/free.log immediately
+    try {
+        const logDir = path.join(process.cwd(), 'storage/logs');
+        if (!fs.existsSync(logDir)) {
+            fs.mkdirSync(logDir, { recursive: true });
+        }
+
+        const timestamp = new Date().toISOString();
+        const logMessage = `[${timestamp}] [${req.method} ${req.url}] HTTP ${status}: ${err.message}\n${err.stack || ''}\n\n`;
+
+        fs.appendFileSync(path.join(logDir, 'free.log'), logMessage);
+    } catch (logErr) {
+        console.error('CRITICAL: Failed to write to storage/logs/free.log', logErr);
+    }
+
+    // 3. Format the Response (Never show stack traces in production!)
+    const isProduction = config.env === 'production' && !config.debug;
+
+    // Set response headers
+    if (!res.headersSent) {
+        res.status(status);
+        res.header('Content-Type', 'application/json');
+    }
+
+    // Special handling for Validation Errors (422)
+    if (status === 422 && err.errors) {
+        return res.send(JSON.stringify({
+            message: 'Unprocessable Entity',
+            errors: err.errors
+        }));
+    }
+
+    // Standard Error Response
+    const responsePayload = {
+        message: isProduction && status >= 500 ? 'Internal Server Error' : err.message,
+    };
+
+    // Append full stack trace only if debug mode is ON
+    if (!isProduction && err.stack) {
+        responsePayload.stack = err.stack.split('\n');
+    }
+
+    res.send(JSON.stringify(responsePayload));
+};

package/templates/app-template/app/Http/Controllers/AuthController.free

@@ -0,0 +1,91 @@
+/**
+* app/Http/Controllers/AuthController.free
+*
+* --------------------------------------------------------------------------
+* Authentication Controller
+* --------------------------------------------------------------------------
+*
+* This controller handles massive-scale user registration and login.
+* It strictly adheres to enterprise security standards:
+* 1. Plain text passwords are NEVER saved. (bcrypt is used).
+* 2. Sessions are stateless and highly scalable via JSON Web Tokens (JWT).
+*
+* @security Ensure the JWT_SECRET in config/auth.js is extremely strong.
+*/
+
+// Handles new user registration via POST /api/register
+action register {
+  // 1. Validate incoming data
+  const { name, email, password } = body;
+  if (!name || !email || !password) {
+    throw new Error("Missing required fields: name, email, password");
+  }
+
+  // 2. Hash the password using bcrypt dynamically
+  // The salt rounds are pulled from config (defaults to 10 for performance/security balance)
+  const bcrypt = require('bcryptjs');
+  const authConfig = require('../../config/auth');
+  const hashedPassword = await bcrypt.hash(password, authConfig.bcrypt_rounds || 10);
+
+  // 3. Save the new user to the database
+  // The ORM's 'create' method automatically sanitizes inputs to prevent SQL Injection
+  const user = await User.create( { name, email, password: hashedPassword });
+
+  // 4. Generate the JWT stateless token
+  const jwt = require('jsonwebtoken');
+  const payload = { id: user.id, email: user.email, role: user.role };
+  const secret = authConfig.jwt_secret;
+  const options = { expiresIn: authConfig.jwt_expires_in || '7d' };
+
+  const token = jwt.sign(payload, secret, options);
+
+  // 5. Return success. CRITICAL: Never return the password hash in the response!
+  return {
+    success: true,
+    message: "User registered securely.",
+    token,
+    user: { id: user.id, name: user.name, email: user.email }
+    };
+  }
+
+  // Handles user login via POST /api/login
+  action login {
+    // 1. Validate inputs
+    const { email, password } = body;
+    if (!email || !password) {
+      throw new Error("Missing credentials");
+    }
+
+    // 2. Look up the user by email (SQL Injection Proof via ORM query builder)
+    const userQuery = await User.query().where( { email }).get();
+    const user = userQuery[0];
+
+    if (!user) {
+      throw new Error("Invalid credentials");
+    }
+
+    // 3. Prevent Timing Attacks & Verify Hash
+    // We strictly use bcrypt.compare instead of manual string comparison
+    const bcrypt = require('bcryptjs');
+    const isMatch = await bcrypt.compare(password, user.password);
+
+    if (!isMatch) {
+      throw new Error("Invalid credentials");
+    }
+
+    // 4. Issue the secure JWT Token
+    const authConfig = require('../../config/auth');
+    const jwt = require('jsonwebtoken');
+    const token = jwt.sign(
+      { id: user.id, email: user.email, role: user.role },
+      authConfig.jwt_secret,
+      { expiresIn: authConfig.jwt_expires_in || '7d' }
+      );
+
+      // 5. Return the payload for the frontend to store (e.g., in localStorage or cookies)
+      return {
+        success: true,
+        token,
+        user: { id: user.id, name: user.name, email: user.email }
+        };
+      }

package/templates/app-template/app/Http/Middleware/AuthGuard.js

@@ -0,0 +1,46 @@
+/**
+ * app/Http/Middleware/AuthGuard.js
+ * 
+ * --------------------------------------------------------------------------
+ * JWT Authentication Guard
+ * --------------------------------------------------------------------------
+ * 
+ * This middleware protects routes from unauthenticated access.
+ * It intercepts incoming HTTP requests, extracts the Bearer token from the
+ * Authorization header, and verifies its cryptographic signature using jsonwebtoken.
+ * 
+ * Usage: Attach this middleware to any sensitive API or Web route.
+ */
+
+const jwt = require('jsonwebtoken');
+const authConfig = require('../../../config/auth');
+
+module.exports = async function AuthGuard(req, res, next) {
+    // 1. Extract the token from the "Authorization: Bearer <token>" header
+    const authHeader = req.headers['authorization'];
+    const token = authHeader && authHeader.split(' ')[1];
+
+    // 2. Reject immediately if no token is found (401 Unauthorized)
+    if (!token) {
+        res.writeHead(401, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Unauthorized: No secure token provided' }));
+        return; // HALT the request lifecycle
+    }
+
+    try {
+        // 3. Cryptographically verify the token's validity and expiration
+        // If the token was tampered with, this will throw an error immediately.
+        const decoded = jwt.verify(token, authConfig.jwt_secret);
+
+        // 4. Attach the decoded user payload securely to the request object
+        // so that subsequent controllers can access `req.user.id`, etc.
+        req.user = decoded;
+
+        // 5. Allow the request to proceed to the next middleware or controller
+        next();
+    } catch (err) {
+        // Token was invalid, expired, or tampered with (403 Forbidden)
+        res.writeHead(403, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Forbidden: Invalid or expired authentication token' }));
+    }
+};

package/templates/app-template/app/Services/Storage.js

@@ -0,0 +1,75 @@
+/**
+ * app/Services/Storage.js
+ * 
+ * --------------------------------------------------------------------------
+ * Enterprise File Storage & Uploads
+ * --------------------------------------------------------------------------
+ * 
+ * This service provides a clean Laravel-like API for saving uploaded files
+ * directly to the 'storage/uploads' directory.
+ * 
+ * Example usage in a controller:
+ * const path = await Storage.put('avatars', req.file);
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+class Storage {
+    /**
+     * Internal method to ensure the storage directory exists.
+     */
+    static _ensureDir(subFolder) {
+        const dest = path.join(process.cwd(), 'storage/uploads', subFolder || '');
+        if (!fs.existsSync(dest)) {
+            fs.mkdirSync(dest, { recursive: true });
+        }
+        return dest;
+    }
+
+    /**
+     * Saves a raw buffer or a multipart file object to the disk.
+     * @param {string} directory - The sub-directory (e.g., 'avatars').
+     * @param {Object|Buffer} file - The file data. If using HyperExpress multipart, it should be the file stream/buffer.
+     * @param {string} [filename] - Optional custom name. Otherwise, a secure random name is generated.
+     * @returns {string} The relative path to the saved file.
+     */
+    static async put(directory, fileBuffer, filename = null) {
+        const destDir = this._ensureDir(directory);
+
+        // Generate a cryptographically secure random filename if none provided
+        // This prevents overwriting files and Directory Traversal attacks.
+        const safeFilename = filename || crypto.randomBytes(16).toString('hex') + '.bin';
+        const finalPath = path.join(destDir, safeFilename);
+
+        return new Promise((resolve, reject) => {
+            fs.writeFile(finalPath, fileBuffer, (err) => {
+                if (err) return reject(err);
+                // Return a relative path that can be stored in the database
+                resolve(`storage/uploads/${directory ? directory + '/' : ''}${safeFilename}`);
+            });
+        });
+    }
+
+    /**
+     * Checks if a file exists.
+     */
+    static exists(filepath) {
+        return fs.existsSync(path.join(process.cwd(), filepath));
+    }
+
+    /**
+     * Deletes a file.
+     */
+    static async delete(filepath) {
+        const fullPath = path.join(process.cwd(), filepath);
+        if (fs.existsSync(fullPath)) {
+            fs.unlinkSync(fullPath);
+            return true;
+        }
+        return false;
+    }
+}
+
+module.exports = Storage;

package/templates/app-template/app/Services/Validator.js

@@ -0,0 +1,91 @@
+/**
+ * app/Services/Validator.js
+ * 
+ * --------------------------------------------------------------------------
+ * Enterprise Input Validation
+ * --------------------------------------------------------------------------
+ * 
+ * This service provides Laravel-style input validation.
+ * Use it to ensure incoming request data is completely sanitized and correctly
+ * formatted before it ever touches your Controllers or Database.
+ * 
+ * Example usage:
+ * const validated = Validator.make(req.body, { email: 'required|email' });
+ */
+
+class Validator {
+    /**
+     * Core validation engine.
+     * @param {Object} data - The incoming data (e.g., req.body)
+     * @param {Object} rules - The validation rules (e.g., { name: 'required|string', age: 'number|min:18' })
+     * @throws {Error} - Throws a detailed 422 Unprocessable Entity error if validation fails.
+     * @returns {Object} - The sanitized, validated data.
+     */
+    static make(data, rules) {
+        let errors = {};
+        let validatedData = {};
+
+        for (const [field, ruleString] of Object.entries(rules)) {
+            const fieldRules = ruleString.split('|');
+            const value = data[field];
+            validatedData[field] = value; // Keep the value if it passes
+
+            for (const rule of fieldRules) {
+                // 1. Required Rule
+                if (rule === 'required' && (value === undefined || value === null || value === '')) {
+                    if (!errors[field]) errors[field] = [];
+                    errors[field].push(`The ${field} field is required.`);
+                    break; // Stop further validation for this field if it's missing
+                }
+
+                // Skip other rules if the field is empty but not required
+                if (value === undefined || value === null || value === '') continue;
+
+                // 2. Email Rule
+                if (rule === 'email') {
+                    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+                    if (!emailRegex.test(value)) {
+                        if (!errors[field]) errors[field] = [];
+                        errors[field].push(`The ${field} must be a valid email address.`);
+                    }
+                }
+
+                // 3. String Rule
+                if (rule === 'string' && typeof value !== 'string') {
+                    if (!errors[field]) errors[field] = [];
+                    errors[field].push(`The ${field} must be a string.`);
+                }
+
+                // 4. Number Rule
+                if (rule === 'number' && isNaN(Number(value))) {
+                    if (!errors[field]) errors[field] = [];
+                    errors[field].push(`The ${field} must be a number.`);
+                }
+
+                // 5. Min/Max Length or Value Rules (e.g., min:8, max:255)
+                if (rule.startsWith('min:')) {
+                    const min = parseFloat(rule.split(':')[1]);
+                    if (typeof value === 'string' && value.length < min) {
+                        if (!errors[field]) errors[field] = [];
+                        errors[field].push(`The ${field} must be at least ${min} characters.`);
+                    } else if (typeof value === 'number' && value < min) {
+                        if (!errors[field]) errors[field] = [];
+                        errors[field].push(`The ${field} must be at least ${min}.`);
+                    }
+                }
+            }
+        }
+
+        if (Object.keys(errors).length > 0) {
+            // Throw a custom validation error that the Global Handler will catch
+            const error = new Error('Validation Failed');
+            error.status = 422;
+            error.errors = errors;
+            throw error;
+        }
+
+        return validatedData;
+    }
+}
+
+module.exports = Validator;

package/templates/app-template/app/controllers/AuthController.free

@@ -0,0 +1,42 @@
+/**
+* AuthController.free
+* Default Authentication Logic (Login, Register).
+*/
+
+action register {
+  const { name, email, password } = body;
+  if (!name || !email || !password) throw new Error("Missing credentials");
+
+  const bcrypt = require('bcryptjs');
+  const hashedPassword = await bcrypt.hash(password, 10);
+
+  const user = await User.create( { name, email, password: hashedPassword });
+
+  // Generate JWT
+  const jwt = require('jsonwebtoken');
+  const secret = process.env.JWT_SECRET || 'super_secret_jwt_key_that_should_be_long_and_random';
+  const token = jwt.sign( { id: user.id, email: user.email, role: user.role }, secret, { expiresIn: '7d' });
+
+  return { success: true, token, user: { id: user.id, name: user.name, email: user.email } };
+}
+
+action login {
+  const { email, password } = body;
+  if (!email || !password) throw new Error("Missing credentials");
+
+  const userQuery = await User.query().where( { email }).get();
+  const user = userQuery[0];
+
+  if (!user) throw new Error("Invalid credentials");
+
+  const bcrypt = require('bcryptjs');
+  const isMatch = await bcrypt.compare(password, user.password);
+  if (!isMatch) throw new Error("Invalid credentials");
+
+  // Generate JWT
+  const jwt = require('jsonwebtoken');
+  const secret = process.env.JWT_SECRET || 'super_secret_jwt_key_that_should_be_long_and_random';
+  const token = jwt.sign( { id: user.id, email: user.email, role: user.role }, secret, { expiresIn: '7d' });
+
+  return { success: true, token, user: { id: user.id, name: user.name, email: user.email } };
+}

package/templates/app-template/app/middleware/auth.js

@@ -0,0 +1,25 @@
+/**
+ * app/middleware/auth.js
+ * Default JWT Authentication Guard
+ */
+const jwt = require('jsonwebtoken');
+
+module.exports = async function authGuard(req, res, next) {
+    const authHeader = req.headers['authorization'];
+    const token = authHeader && authHeader.split(' ')[1];
+
+    if (!token) {
+        res.writeHead(401, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Unauthorized: No token provided' }));
+        return;
+    }
+
+    try {
+        const decoded = jwt.verify(token, process.env.JWT_SECRET || 'super_secret_jwt_key_that_should_be_long_and_random');
+        req.user = decoded; // Attach user payload to request
+        next();
+    } catch (err) {
+        res.writeHead(403, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Forbidden: Invalid or expired token' }));
+    }
+};

package/templates/app-template/app/models/User.free

@@ -0,0 +1,32 @@
+/**
+* app/Models/User.free
+*
+* --------------------------------------------------------------------------
+* User Model
+* --------------------------------------------------------------------------
+*
+* The Free Framework ORM allows you to define database schemas and interact
+* with rows as JavaScript objects. This file represents the 'users' table.
+*
+* Security: The 'password' field should ALWAYS be hashed before saving
+* using bcrypt. Never store plain text passwords.
+*/
+
+model User {
+  // Unique identifier (Primary Key is automatically generated by the Framework)
+
+  // Standard string fields
+  name      string  
+
+  // The 'unique' modifier ensures the database prevents duplicate emails
+  email     string  unique
+
+  // The password hash. NEVER select this field to send to the frontend!
+  password  string  
+
+  // Role-Based Access Control (RBAC). Default is 'user', admins would be 'admin'
+  role      string  default "user"
+
+  // Framework automatically adds 'createdAt' and 'updatedAt' timestamps
+  timestamps
+}

package/templates/app-template/app/routes.free

@@ -0,0 +1,12 @@
+/**
+* Base Application Routes
+* Powered by Free Framework MVC
+*/
+
+get "/" -> Home
+
+// Example of a protected view route (Optional Server-Side checking logic can go here)
+get "/dashboard" {
+  // You can access req.user if middleware is attached globally or per route
+  return Dashboard;
+}

package/templates/app-template/app/styles.css

@@ -0,0 +1,23 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+    body {
+        @apply bg-[#050505] text-white selection:bg-primary/30 font-sans;
+    }
+}
+
+@layer components {
+    .glass {
+        @apply bg-white/5 backdrop-blur-xl border border-white/10 rounded-2xl;
+    }
+
+    .btn-premium {
+        @apply px-6 py-3 bg-gradient-to-r from-primary to-secondary text-black font-black rounded-xl hover:scale-105 active:scale-95 transition-all duration-300 shadow-lg shadow-primary/20;
+    }
+
+    .text-glow {
+        @apply bg-gradient-to-r from-primary to-secondary bg-clip-text text-transparent drop-shadow-[0_0_15px_rgba(0, 255, 136, 0.3)];
+    }
+}