free-framework 4.4.0

package/plugins/auth.js

@@ -0,0 +1,212 @@
+/**
+ * plugins/auth.js
+ * Official Authentication System for Free Framework.
+ * Features: JWT auth, session cookies, password reset tokens, email verification.
+ */
+const jwt = require('jsonwebtoken');
+const bcrypt = require('bcrypt');
+const crypto = require('crypto');
+
+// In-memory token store — in production, persist to Redis/DB
+const resetTokens = new Map();       // token → { email, expiresAt }
+const verifyTokens = new Map();      // token → { email, expiresAt }
+
+function AuthPlugin(config = {}) {
+    return {
+        install(server) {
+            const secret = process.env.JWT_SECRET || 'free-ultra-secret-key';
+            const loginPath = config.login || '/login';
+            const resetExpiry = config.resetExpiry || 60 * 60 * 1000; // 1 hour
+
+            // ── Global Middleware: Token Verification ───────────────────────
+            server.middleware((req, res, next) => {
+                // Support both cookie-based and Bearer token auth
+                let token = (req.cookies && req.cookies.free_token);
+                if (!token) {
+                    const authHeader = req.headers['authorization'] || '';
+                    token = authHeader.startsWith('Bearer ') ? authHeader.slice(7) : null;
+                }
+
+                if (token) {
+                    try {
+                        const decoded = jwt.verify(token, secret);
+                        res.context = res.context || {};
+                        res.context.user = decoded;
+                    } catch (e) {
+                        // Invalid token? Just ignore, contextual user remains null
+                    }
+                }
+
+                // Auth helper methods
+                res.login = (userObj, expiresIn = '7d') => {
+                    const token = jwt.sign(userObj, secret, { expiresIn });
+                    const isProd = process.env.NODE_ENV === 'production';
+                    res.cookie('free_token', token, {
+                        httpOnly: true,
+                        secure: isProd,
+                        sameSite: isProd ? 'none' : 'lax', // 'none' requires Secure
+                        maxAge: 7 * 24 * 60 * 60 * 1000,
+                    });
+                    return token;
+                };
+                res.logout = () => res.clearCookie('free_token');
+
+                // Password helpers
+                req.hashPassword = (pw) => bcrypt.hash(pw, 12);
+                req.verifyPassword = (pw, hash) => bcrypt.compare(pw, hash);
+
+                next();
+            });
+
+            // ── Named 'auth' middleware: Enforcement only ───────────────────
+            const authMW = (req, res, next) => {
+                if (res.context && res.context.user) {
+                    return next();
+                }
+                res.redirect(loginPath);
+            };
+            server.registerMiddleware('auth', authMW);
+            server.registerMiddleware('AuthGuard', authMW);
+
+            // ── Built-in Auth API Endpoints ──────────────────────────────────
+            server.app.post('/_free/auth/register', async (req, res) => {
+                try {
+                    console.log("📝 Auth: Registration request received");
+                    const body = await req.json().catch(() => ({}));
+                    const { name, email, password } = body;
+                    if (!email || !password) return res.status(400).json({ success: false, error: 'Email and password are required' });
+
+                    // Use server-attached modelsRegistry to avoid circular require
+                    const User = server.modelsRegistry && server.modelsRegistry['User'];
+                    if (!User) {
+                        console.error("❌ Auth Error: User model not found in registry.");
+                        return res.status(500).json({ success: false, error: 'User model not found.' });
+                    }
+
+                    console.log(`🔍 Auth: Checking if user ${email} exists...`);
+                    const existing = await User.where('email', email).first();
+                    if (existing) {
+                        console.log(`⚠️ Auth: Email ${email} already registered.`);
+                        return res.status(409).json({ success: false, error: 'Email already registered' });
+                    }
+
+                    console.log("🔐 Auth: Hashing password...");
+                    // Use bcryptjs safely or native bcrypt
+                    const hashed = await bcrypt.hash(password, 12);
+
+                    console.log("💾 Auth: Creating user record...");
+                    const user = await User.create({ name: name || email.split('@')[0], email, password: hashed });
+
+                    console.log(`✅ Auth: User ${user.id} registered successfully.`);
+                    res.login({ id: user.id, email, name: user.name });
+                    res.json({ success: true, user: { id: user.id, email, name: user.name } });
+                } catch (e) {
+                    console.error("❌ Auth Registration Exception:", e);
+                    res.status(500).json({ success: false, error: e.message });
+                }
+            });
+
+            server.app.post('/_free/auth/login', async (req, res) => {
+                try {
+                    const body = await req.json().catch(() => ({}));
+                    const { email, password } = body;
+                    if (!email || !password) return res.status(400).json({ success: false, error: 'Email and password are required' });
+
+                    const User = server.modelsRegistry && server.modelsRegistry['User'];
+                    if (!User) return res.status(500).json({ success: false, error: 'User model not found.' });
+
+                    const user = await User.where('email', email).first();
+                    if (!user) return res.status(401).json({ success: false, error: 'Invalid credentials' });
+
+                    const match = await bcrypt.compare(password, user.password);
+                    if (!match) return res.status(401).json({ success: false, error: 'Invalid credentials' });
+
+                    res.login({ id: user.id, email: user.email, name: user.name });
+                    res.json({ success: true, user: { id: user.id, email: user.email, name: user.name } });
+                } catch (e) {
+                    res.status(500).json({ success: false, error: e.message });
+                }
+            });
+
+            server.app.post('/_free/auth/logout', (req, res) => {
+                res.clearCookie('free_token');
+                res.json({ success: true });
+            });
+
+            // ── Password Reset ───────────────────────────────────────────────
+
+            /**
+             * Generate a password reset token for an email.
+             * @returns {string} reset token — send this via email
+             */
+            server.auth = server.auth || {};
+
+            server.auth.createResetToken = async (email) => {
+                const token = crypto.randomBytes(32).toString('hex');
+                if (server.cache) {
+                    await server.cache.set(`reset_token:${token}`, email, resetExpiry / 1000);
+                } else {
+                    resetTokens.set(token, { email, expiresAt: Date.now() + resetExpiry });
+                }
+                return token;
+            };
+
+            server.auth.verifyResetToken = async (token) => {
+                if (server.cache) {
+                    return await server.cache.get(`reset_token:${token}`);
+                }
+                const entry = resetTokens.get(token);
+                if (!entry) return null;
+                if (Date.now() > entry.expiresAt) {
+                    resetTokens.delete(token);
+                    return null;
+                }
+                return entry.email;
+            };
+
+            server.auth.consumeResetToken = async (token) => {
+                const email = await server.auth.verifyResetToken(token);
+                if (email) {
+                    if (server.cache) await server.cache.forget(`reset_token:${token}`);
+                    else resetTokens.delete(token);
+                }
+                return email;
+            };
+
+            // ── Email Verification ───────────────────────────────────────────
+
+            server.auth.createVerifyToken = async (email) => {
+                const token = crypto.randomBytes(32).toString('hex');
+                if (server.cache) {
+                    await server.cache.set(`verify_token:${token}`, email, resetExpiry / 1000);
+                } else {
+                    verifyTokens.set(token, { email, expiresAt: Date.now() + resetExpiry });
+                }
+                return token;
+            };
+
+            server.auth.consumeVerifyToken = async (token) => {
+                let email = null;
+                if (server.cache) {
+                    email = await server.cache.get(`verify_token:${token}`);
+                    if (email) await server.cache.forget(`verify_token:${token}`);
+                } else {
+                    const entry = verifyTokens.get(token);
+                    if (entry && Date.now() <= entry.expiresAt) {
+                        email = entry.email;
+                    }
+                    verifyTokens.delete(token);
+                }
+                return email;
+            };
+
+            // ── JWT token generator (for API use) ────────────────────────────
+            server.auth.sign = (payload, expiresIn = '7d') => jwt.sign(payload, secret, { expiresIn });
+            server.auth.verify = (token) => jwt.verify(token, secret);
+
+            console.log("🔒 Auth Plugin installed. JWT + sessions + password reset + email verify.");
+        }
+    };
+}
+
+module.exports = AuthPlugin;

package/plugins/cache.js

@@ -0,0 +1,85 @@
+/**
+ * plugins/cache.js
+ * Application Cache Plugin for Free Framework.
+ * Drivers: memory (LRU), redis.
+ * 
+ * Usage:
+ *   server.cache.set("posts", data, 60);   // 60 seconds TTL
+ *   server.cache.get("posts");             // returns data or null
+ *   server.cache.forget("posts");          // invalidate
+ *   server.cache.flush();                  // clear all
+ *   server.cache.stats();                  // hit/miss/size info
+ */
+
+const { LRUCache } = require('lru-cache');
+
+function CachePlugin(config = {}) {
+    const driver = config.driver || 'memory';  // 'memory' | 'redis'
+
+    return {
+        install(server) {
+            let backend;
+
+            if (driver === 'redis') {
+                // Redis driver — requires: npm install ioredis
+                const Redis = (() => {
+                    try { return require('ioredis'); }
+                    catch { throw new Error('CachePlugin redis driver: run npm install ioredis'); }
+                })();
+                const redis = new Redis(config.redis || process.env.REDIS_URL || 'redis://127.0.0.1:6379');
+                let hits = 0, misses = 0;
+
+                backend = {
+                    async set(key, value, ttlSeconds = 300) {
+                        await redis.set(key, JSON.stringify(value), 'EX', ttlSeconds);
+                    },
+                    async get(key) {
+                        const raw = await redis.get(key);
+                        if (raw === null) { misses++; return null; }
+                        hits++;
+                        return JSON.parse(raw);
+                    },
+                    async forget(key) { await redis.del(key); },
+                    async flush() { await redis.flushdb(); },
+                    stats() { return { driver: 'redis', hits, misses }; },
+                };
+            } else {
+                // Memory driver (LRU)
+                const cache = new LRUCache({
+                    max: config.max || 1000,
+                    ttl: (config.defaultTtl || 300) * 1000, // ms
+                });
+                let hits = 0, misses = 0;
+
+                backend = {
+                    async set(key, value, ttlSeconds) {
+                        cache.set(key, value, ttlSeconds ? { ttl: ttlSeconds * 1000 } : undefined);
+                    },
+                    async get(key) {
+                        const val = cache.get(key);
+                        if (val === undefined) { misses++; return null; }
+                        hits++;
+                        return val;
+                    },
+                    async forget(key) { cache.delete(key); },
+                    async flush() { cache.clear(); },
+                    stats() {
+                        return {
+                            driver: 'memory',
+                            size: cache.size,
+                            maxSize: cache.max,
+                            hits,
+                            misses,
+                            hitRate: hits + misses > 0 ? ((hits / (hits + misses)) * 100).toFixed(1) + '%' : 'N/A',
+                        };
+                    },
+                };
+            }
+
+            server.cache = backend;
+            console.log(`🗄️  Cache Plugin installed. Driver: ${driver}`);
+        }
+    };
+}
+
+module.exports = CachePlugin;

package/plugins/chat.js

@@ -0,0 +1,32 @@
+/**
+ * plugins/chat.js
+ * Real-Time Chat Plugin for Free Framework.
+ * Exposes WebSocket Server over HyperExpress using native pub/sub capabilities.
+ */
+
+function ChatPlugin() {
+    return {
+        install(server) {
+            server.app.ws('/ws/chat', {
+                idle_timeout: 120,
+                open: (ws) => {
+                    ws.subscribe('global_chat');
+                    // Notify room
+                    server.app.publish('global_chat', '👋 A new user has joined the chat.');
+                },
+                message: (ws, message, isBinary) => {
+                    const text = Buffer.from(message).toString();
+                    // Echo message to everyone in the room
+                    server.app.publish('global_chat', `💬 User: ${text}`);
+                },
+                close: (ws, code, message) => {
+                    server.app.publish('global_chat', '🚪 A user left the chat.');
+                }
+            });
+
+            console.log("🟢 Chat Plugin installed. WebSocket active on ws://localhost/ws/chat");
+        }
+    };
+}
+
+module.exports = ChatPlugin;

package/plugins/mail.js

@@ -0,0 +1,53 @@
+/**
+ * plugins/mail.js
+ * Official Mail Plugin for Free Framework.
+ * Powered by Nodemailer with support for SMTP and JSON-based templates.
+ */
+
+const nodemailer = require('nodemailer');
+
+function MailPlugin(config = {}) {
+    let transporter = nodemailer.createTransport(config.transport || {
+        host: process.env.MAIL_HOST || 'localhost',
+        port: process.env.MAIL_PORT || 1025,
+        auth: {
+            user: process.env.MAIL_USER,
+            pass: process.env.MAIL_PASS
+        }
+    });
+
+    return {
+        install(server) {
+            server.mail = {
+                /**
+                 * Send a basic email.
+                 */
+                async send(options) {
+                    return await transporter.sendMail({
+                        from: options.from || config.from || '"Free Framework" <no-reply@freejs.dev>',
+                        to: options.to,
+                        subject: options.subject,
+                        text: options.text,
+                        html: options.html
+                    });
+                },
+
+                /**
+                 * Send using a template (Simple placeholder replacement).
+                 */
+                async sendTemplate(to, subject, templateHtml, data = {}) {
+                    let html = templateHtml;
+                    Object.keys(data).forEach(key => {
+                        const regex = new RegExp(`{{${key}}}`, 'g');
+                        html = html.replace(regex, data[key]);
+                    });
+                    return this.send({ to, subject, html });
+                }
+            };
+
+            console.log('📧 Mail Plugin installed (Ready to send)');
+        }
+    };
+}
+
+module.exports = MailPlugin;

package/plugins/metrics.js

@@ -0,0 +1,126 @@
+/**
+ * plugins/metrics.js
+ * Observability Plugin for Free Framework.
+ * Exposes:
+ *   GET /metrics  — Prometheus-compatible metrics
+ *   GET /health   — Health check JSON
+ *   Live request tracing (configurable via LOG_REQUESTS=true)
+ */
+
+function MetricsPlugin(config = {}) {
+    return {
+        install(server) {
+            const startTime = Date.now();
+            const counters = {
+                requests_total: 0,
+                requests_success: 0,
+                requests_error: 0,
+            };
+            const durations = [];  // last 1000 request durations (ms)
+            const routeCounts = {};
+
+            // ── Request tracing middleware ───────────────────────────────────
+            server.app.use((req, res, next) => {
+                const start = Date.now();
+                counters.requests_total++;
+                const routeKey = `${req.method} ${req.path}`;
+                routeCounts[routeKey] = (routeCounts[routeKey] || 0) + 1;
+
+                const originalSend = res.send.bind(res);
+                res.send = (body) => {
+                    const duration = Date.now() - start;
+                    durations.push(duration);
+                    if (durations.length > 1000) durations.shift(); // rolling window
+
+                    if ((res.statusCode || 200) >= 400) {
+                        counters.requests_error++;
+                    } else {
+                        counters.requests_success++;
+                    }
+
+                    if (process.env.LOG_REQUESTS === 'true') {
+                        const status = res.statusCode || 200;
+                        const color = status >= 500 ? '\x1b[31m' : status >= 400 ? '\x1b[33m' : '\x1b[32m';
+                        console.log(`${color}${req.method}\x1b[0m ${req.path} \x1b[90m${status} ${duration}ms\x1b[0m`);
+                    }
+
+                    return originalSend(body);
+                };
+
+                next();
+            });
+
+            // ── Helper computations ──────────────────────────────────────────
+            function getPercentile(arr, p) {
+                if (arr.length === 0) return 0;
+                const sorted = [...arr].sort((a, b) => a - b);
+                const idx = Math.floor((p / 100) * sorted.length);
+                return sorted[idx] || 0;
+            }
+
+            function getMemory() {
+                const m = process.memoryUsage();
+                return {
+                    heap_used_mb: (m.heapUsed / 1024 / 1024).toFixed(2),
+                    heap_total_mb: (m.heapTotal / 1024 / 1024).toFixed(2),
+                    rss_mb: (m.rss / 1024 / 1024).toFixed(2),
+                };
+            }
+
+            // ── Health endpoint ──────────────────────────────────────────────
+            server.app.get('/health', (req, res) => {
+                const mem = getMemory();
+                res.json({
+                    status: 'ok',
+                    uptime: `${((Date.now() - startTime) / 1000).toFixed(0)}s`,
+                    memory: mem,
+                    requests: {
+                        total: counters.requests_total,
+                        success: counters.requests_success,
+                        error: counters.requests_error,
+                    },
+                });
+            });
+
+            // ── Prometheus-compatible /metrics ───────────────────────────────
+            server.app.get('/metrics', (req, res) => {
+                const mem = getMemory();
+                const avg = durations.length > 0 ? (durations.reduce((a, b) => a + b, 0) / durations.length).toFixed(1) : 0;
+                const p95 = getPercentile(durations, 95);
+                const p99 = getPercentile(durations, 99);
+                const uptime = ((Date.now() - startTime) / 1000).toFixed(0);
+
+                let out = '';
+                out += `# HELP free_requests_total Total HTTP requests\n`;
+                out += `# TYPE free_requests_total counter\n`;
+                out += `free_requests_total ${counters.requests_total}\n\n`;
+                out += `free_requests_success ${counters.requests_success}\n`;
+                out += `free_requests_error ${counters.requests_error}\n\n`;
+
+                out += `# HELP free_request_duration_ms Request duration percentiles\n`;
+                out += `free_request_duration_avg ${avg}\n`;
+                out += `free_request_duration_p95 ${p95}\n`;
+                out += `free_request_duration_p99 ${p99}\n\n`;
+
+                out += `# HELP free_memory_heap_used_bytes Heap memory used\n`;
+                out += `free_memory_heap_used_mb ${mem.heap_used_mb}\n`;
+                out += `free_memory_rss_mb ${mem.rss_mb}\n\n`;
+
+                out += `free_uptime_seconds ${uptime}\n\n`;
+
+                out += `# HELP free_route_requests_total Requests per route\n`;
+                for (const [route, count] of Object.entries(routeCounts)) {
+                    const safeLabel = route.replace(/"/g, '\\"');
+                    out += `free_route_requests_total{route="${safeLabel}"} ${count}\n`;
+                }
+
+                res.setHeader('Content-Type', 'text/plain; version=0.0.4');
+                res.send(out);
+            });
+
+            console.log('📊 Metrics Plugin installed. Endpoints: GET /health  GET /metrics');
+        }
+    };
+}
+
+module.exports = MetricsPlugin;

package/plugins/payments.js

@@ -0,0 +1,59 @@
+/**
+ * plugins/payments.js
+ * Payments Plugin for Free Framework.
+ * Native integration with Stripe and unified checkout flow.
+ */
+
+function PaymentsPlugin(config = {}) {
+    const stripeKey = config.secretKey || process.env.STRIPE_SECRET_KEY;
+    let stripe = null;
+
+    return {
+        install(server) {
+            if (stripeKey) {
+                try {
+                    const Stripe = require('stripe');
+                    stripe = new Stripe(stripeKey);
+                } catch (e) {
+                    console.warn('PaymentsPlugin: Stripe module not found. Run npm install stripe');
+                }
+            }
+
+            server.payments = {
+                /**
+                 * Create a Stripe Checkout session.
+                 */
+                async createCheckout(items, successUrl, cancelUrl) {
+                    if (!stripe) throw new Error('Stripe not initialized. Check STRIPE_SECRET_KEY');
+
+                    return await stripe.checkout.sessions.create({
+                        payment_method_types: ['card'],
+                        line_items: items.map(item => ({
+                            price_data: {
+                                currency: config.currency || 'usd',
+                                product_data: { name: item.name },
+                                unit_amount: item.amount, // in cents
+                            },
+                            quantity: item.quantity || 1,
+                        })),
+                        mode: 'payment',
+                        success_url: successUrl,
+                        cancel_url: cancelUrl,
+                    });
+                },
+
+                /**
+                 * Handle webhook events (e.g. payment success notification)
+                 */
+                async verifyWebhook(body, sig, secret) {
+                    if (!stripe) return null;
+                    return stripe.webhooks.constructEvent(body, sig, secret);
+                }
+            };
+
+            console.log('💳 Payments Plugin installed (Stripe Ready)');
+        }
+    };
+}
+
+module.exports = PaymentsPlugin;