voltjs-framework 1.0.0

package/src/security/cors.js

@@ -0,0 +1,80 @@
+/**
+ * VoltJS CORS Handler
+ * 
+ * Cross-Origin Resource Sharing configuration.
+ * Secure by default, fully customizable.
+ */
+
+'use strict';
+
+class CORSHandler {
+  /** Apply CORS headers to a response */
+  static apply(req, res, options = {}) {
+    const config = {
+      origin: options.origin || '*',
+      methods: options.methods || ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
+      allowedHeaders: options.allowedHeaders || ['Content-Type', 'Authorization', 'X-Requested-With', 'X-CSRF-Token'],
+      exposedHeaders: options.exposedHeaders || [],
+      credentials: options.credentials !== undefined ? options.credentials : true,
+      maxAge: options.maxAge || 86400,
+    };
+
+    // Handle origin
+    const requestOrigin = req.headers.origin;
+
+    if (typeof config.origin === 'function') {
+      const allowed = config.origin(requestOrigin);
+      if (allowed) {
+        res.setHeader('Access-Control-Allow-Origin', typeof allowed === 'string' ? allowed : requestOrigin);
+      }
+    } else if (Array.isArray(config.origin)) {
+      if (config.origin.includes(requestOrigin)) {
+        res.setHeader('Access-Control-Allow-Origin', requestOrigin);
+      }
+    } else if (config.origin === '*' && !config.credentials) {
+      res.setHeader('Access-Control-Allow-Origin', '*');
+    } else if (requestOrigin) {
+      if (config.origin === '*' || config.origin === requestOrigin) {
+        res.setHeader('Access-Control-Allow-Origin', requestOrigin);
+      }
+    }
+
+    // Methods
+    res.setHeader('Access-Control-Allow-Methods', config.methods.join(', '));
+
+    // Allowed headers
+    res.setHeader('Access-Control-Allow-Headers', config.allowedHeaders.join(', '));
+
+    // Exposed headers
+    if (config.exposedHeaders.length > 0) {
+      res.setHeader('Access-Control-Expose-Headers', config.exposedHeaders.join(', '));
+    }
+
+    // Credentials
+    if (config.credentials) {
+      res.setHeader('Access-Control-Allow-Credentials', 'true');
+    }
+
+    // Max age (for preflight cache)
+    res.setHeader('Access-Control-Max-Age', String(config.maxAge));
+
+    // Vary header
+    res.setHeader('Vary', 'Origin');
+  }
+
+  /** Middleware: CORS */
+  static middleware(options = {}) {
+    return (req, res) => {
+      CORSHandler.apply(req, res, options);
+
+      // Handle preflight requests
+      if (req.method === 'OPTIONS') {
+        res.writeHead(204);
+        res.end();
+        return false;
+      }
+    };
+  }
+}
+
+module.exports = { CORSHandler };

package/src/security/csrf.js

@@ -0,0 +1,125 @@
+/**
+ * VoltJS CSRF Protection
+ * 
+ * Protects against Cross-Site Request Forgery attacks using
+ * double-submit cookie pattern and synchronizer tokens.
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+
+class CSRF {
+  constructor(options = {}) {
+    this._secret = options.secret || crypto.randomBytes(32).toString('hex');
+    this._tokenLength = options.tokenLength || 32;
+    this._cookieName = options.cookieName || '_volt_csrf';
+    this._headerName = options.headerName || 'x-csrf-token';
+    this._fieldName = options.fieldName || '_csrf';
+    this._safeMethods = new Set(['GET', 'HEAD', 'OPTIONS']);
+    this._excludePaths = new Set(options.exclude || []);
+    this._tokens = new Map();
+  }
+
+  /** Generate a CSRF token */
+  generateToken(sessionId = 'default') {
+    const token = crypto.randomBytes(this._tokenLength).toString('hex');
+    const salt = crypto.randomBytes(8).toString('hex');
+    const hash = crypto
+      .createHmac('sha256', this._secret)
+      .update(`${token}${salt}`)
+      .digest('hex');
+
+    this._tokens.set(token, {
+      hash,
+      sessionId,
+      createdAt: Date.now(),
+      expiresAt: Date.now() + 60 * 60 * 1000, // 1 hour
+    });
+
+    return token;
+  }
+
+  /** Verify a CSRF token */
+  verifyToken(token, sessionId = 'default') {
+    const stored = this._tokens.get(token);
+    if (!stored) return false;
+    if (stored.expiresAt < Date.now()) {
+      this._tokens.delete(token);
+      return false;
+    }
+    if (stored.sessionId !== sessionId) return false;
+
+    // Delete after use (one-time use tokens)
+    this._tokens.delete(token);
+    return true;
+  }
+
+  /** Middleware: CSRF protection */
+  middleware(options = {}) {
+    return (req, res) => {
+      // Skip safe methods
+      if (this._safeMethods.has(req.method)) {
+        // Attach token generator to response for forms
+        req.csrfToken = () => {
+          const token = this.generateToken(req.cookies?.[this._cookieName] || 'default');
+          res.cookie(this._cookieName, token, {
+            httpOnly: true,
+            sameSite: 'Strict',
+            secure: req.headers['x-forwarded-proto'] === 'https',
+          });
+          return token;
+        };
+        return;
+      }
+
+      // Skip excluded paths
+      if (this._excludePaths.has(req.path)) return;
+
+      // Get token from request
+      const token = 
+        req.body?.[this._fieldName] ||
+        req.headers[this._headerName] ||
+        req.query?.[this._fieldName];
+
+      if (!token) {
+        res.json({ error: 'CSRF token missing' }, 403);
+        return false;
+      }
+
+      if (!this.verifyToken(token)) {
+        res.json({ error: 'CSRF token invalid' }, 403);
+        return false;
+      }
+
+      // Generate new token for next request
+      req.csrfToken = () => this.generateToken();
+    };
+  }
+
+  /** Cleanup expired tokens periodically */
+  cleanup() {
+    const now = Date.now();
+    for (const [token, data] of this._tokens) {
+      if (data.expiresAt < now) {
+        this._tokens.delete(token);
+      }
+    }
+  }
+
+  /** Start auto-cleanup */
+  startAutoCleanup(intervalMs = 300000) {
+    this._cleanupInterval = setInterval(() => this.cleanup(), intervalMs);
+    return this;
+  }
+
+  /** Stop auto-cleanup */
+  stopAutoCleanup() {
+    if (this._cleanupInterval) {
+      clearInterval(this._cleanupInterval);
+    }
+    return this;
+  }
+}
+
+module.exports = { CSRF };

package/src/security/encryption.js

@@ -0,0 +1,110 @@
+/**
+ * VoltJS Encryption Utilities
+ * 
+ * AES-256-GCM encryption, key derivation, and token generation.
+ * Uses Node.js native crypto — zero external dependencies.
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+
+class Encryption {
+  constructor(secretKey) {
+    this._key = secretKey
+      ? crypto.scryptSync(secretKey, 'volt-salt', 32)
+      : crypto.randomBytes(32);
+  }
+
+  /** Encrypt a string using AES-256-GCM */
+  encrypt(plaintext) {
+    const iv = crypto.randomBytes(16);
+    const cipher = crypto.createCipheriv('aes-256-gcm', this._key, iv);
+
+    let encrypted = cipher.update(plaintext, 'utf8', 'hex');
+    encrypted += cipher.final('hex');
+    const authTag = cipher.getAuthTag();
+
+    return `${iv.toString('hex')}:${authTag.toString('hex')}:${encrypted}`;
+  }
+
+  /** Decrypt an AES-256-GCM encrypted string */
+  decrypt(ciphertext) {
+    try {
+      const [ivHex, authTagHex, encrypted] = ciphertext.split(':');
+      const iv = Buffer.from(ivHex, 'hex');
+      const authTag = Buffer.from(authTagHex, 'hex');
+      const decipher = crypto.createDecipheriv('aes-256-gcm', this._key, iv);
+      decipher.setAuthTag(authTag);
+
+      let decrypted = decipher.update(encrypted, 'hex', 'utf8');
+      decrypted += decipher.final('utf8');
+      return decrypted;
+    } catch {
+      throw new Error('Decryption failed — invalid ciphertext or key');
+    }
+  }
+
+  /** Encrypt an object (serializes to JSON) */
+  encryptObject(obj) {
+    return this.encrypt(JSON.stringify(obj));
+  }
+
+  /** Decrypt to an object */
+  decryptObject(ciphertext) {
+    return JSON.parse(this.decrypt(ciphertext));
+  }
+
+  /** Generate a cryptographically secure random token */
+  static generateToken(length = 32) {
+    return crypto.randomBytes(length).toString('hex');
+  }
+
+  /** Generate a secure random string (URL-safe) */
+  static generateUrlSafeToken(length = 32) {
+    return crypto.randomBytes(length).toString('base64url');
+  }
+
+  /** Generate a numeric OTP */
+  static generateOTP(digits = 6) {
+    const max = Math.pow(10, digits);
+    const otp = crypto.randomInt(0, max);
+    return String(otp).padStart(digits, '0');
+  }
+
+  /** SHA-256 hash */
+  static sha256(input) {
+    return crypto.createHash('sha256').update(input).digest('hex');
+  }
+
+  /** SHA-512 hash */
+  static sha512(input) {
+    return crypto.createHash('sha512').update(input).digest('hex');
+  }
+
+  /** MD5 hash (not for security — for checksums) */
+  static md5(input) {
+    return crypto.createHash('md5').update(input).digest('hex');
+  }
+
+  /** HMAC-SHA256 */
+  static hmac(input, secret) {
+    return crypto.createHmac('sha256', secret).update(input).digest('hex');
+  }
+
+  /** Compare two strings in constant time (prevent timing attacks) */
+  static timingSafeCompare(a, b) {
+    if (typeof a !== 'string' || typeof b !== 'string') return false;
+    if (a.length !== b.length) return false;
+    return crypto.timingSafeEqual(Buffer.from(a), Buffer.from(b));
+  }
+
+  /** Derive a key from password using scrypt */
+  static deriveKey(password, salt, keyLength = 32) {
+    const actualSalt = salt || crypto.randomBytes(16).toString('hex');
+    const key = crypto.scryptSync(password, actualSalt, keyLength);
+    return { key: key.toString('hex'), salt: actualSalt };
+  }
+}
+
+module.exports = { Encryption };

package/src/security/helmet.js

@@ -0,0 +1,103 @@
+/**
+ * VoltJS Security Headers (Helmet)
+ * 
+ * Sets secure HTTP headers to protect against common web vulnerabilities.
+ * All protections enabled by default.
+ */
+
+'use strict';
+
+class SecurityHeaders {
+  /** Apply all security headers */
+  static apply(res, options = {}) {
+    const headers = {
+      // Prevent MIME type sniffing
+      'X-Content-Type-Options': 'nosniff',
+
+      // Prevent clickjacking
+      'X-Frame-Options': options.frameOptions || 'DENY',
+
+      // XSS filter
+      'X-XSS-Protection': '1; mode=block',
+
+      // Referrer policy
+      'Referrer-Policy': options.referrerPolicy || 'strict-origin-when-cross-origin',
+
+      // Strict Transport Security
+      'Strict-Transport-Security': options.hsts || 'max-age=31536000; includeSubDomains; preload',
+
+      // Content Security Policy
+      'Content-Security-Policy': options.csp || SecurityHeaders._defaultCSP(options),
+
+      // Permissions Policy
+      'Permissions-Policy': options.permissionsPolicy || SecurityHeaders._defaultPermissions(),
+
+      // Prevent browsers from caching sensitive pages
+      ...(options.noCache && {
+        'Cache-Control': 'no-store, no-cache, must-revalidate, proxy-revalidate',
+        'Pragma': 'no-cache',
+        'Expires': '0',
+        'Surrogate-Control': 'no-store',
+      }),
+
+      // Cross-Origin headers
+      'Cross-Origin-Opener-Policy': options.coop || 'same-origin',
+      'Cross-Origin-Resource-Policy': options.corp || 'same-origin',
+
+      // Remove X-Powered-By (optionally re-add as VoltJS)
+      'X-Powered-By': options.poweredBy !== false ? 'VoltJS' : undefined,
+    };
+
+    for (const [key, value] of Object.entries(headers)) {
+      if (value !== undefined) {
+        res.setHeader(key, value);
+      }
+    }
+  }
+
+  /** Middleware: Apply security headers */
+  static middleware(options = {}) {
+    return (req, res) => {
+      SecurityHeaders.apply(res, options);
+    };
+  }
+
+  /** Default Content Security Policy */
+  static _defaultCSP(options = {}) {
+    const directives = {
+      'default-src': ["'self'"],
+      'script-src': ["'self'"],
+      'style-src': ["'self'", "'unsafe-inline'"],
+      'img-src': ["'self'", 'data:', 'https:'],
+      'font-src': ["'self'"],
+      'connect-src': ["'self'"],
+      'media-src': ["'self'"],
+      'object-src': ["'none'"],
+      'frame-src': ["'none'"],
+      'base-uri': ["'self'"],
+      'form-action': ["'self'"],
+      'frame-ancestors': ["'none'"],
+      ...(options.cspDirectives || {}),
+    };
+
+    return Object.entries(directives)
+      .map(([key, values]) => `${key} ${values.join(' ')}`)
+      .join('; ');
+  }
+
+  /** Default Permissions Policy */
+  static _defaultPermissions() {
+    return [
+      'camera=()',
+      'microphone=()',
+      'geolocation=()',
+      'payment=()',
+      'usb=()',
+      'magnetometer=()',
+      'gyroscope=()',
+      'accelerometer=()',
+    ].join(', ');
+  }
+}
+
+module.exports = { SecurityHeaders };

package/src/security/index.js

@@ -0,0 +1,75 @@
+/**
+ * VoltJS Security Module
+ * 
+ * All-in-one security for your application.
+ * Everything is ON by default — secure out of the box.
+ */
+
+'use strict';
+
+const { Auth } = require('./auth');
+const { CSRF } = require('./csrf');
+const { XSSProtection } = require('./xss');
+const { CORSHandler } = require('./cors');
+const { RateLimiter } = require('./rateLimit');
+const { Encryption } = require('./encryption');
+const { SecurityHeaders } = require('./helmet');
+const { InputSanitizer } = require('./sanitizer');
+
+class Security {
+  /**
+   * Apply all security middleware at once
+   */
+  static all(options = {}) {
+    return (req, res, next) => {
+      // Apply security headers
+      SecurityHeaders.apply(res, options.headers);
+
+      // CORS
+      CORSHandler.apply(req, res, options.cors);
+
+      // Rate limiting
+      const rateResult = RateLimiter.check(req, options.rateLimit);
+      if (!rateResult.allowed) {
+        res.writeHead(429, { 'Content-Type': 'application/json', 'Retry-After': rateResult.retryAfter });
+        res.end(JSON.stringify({ error: 'Too many requests', retryAfter: rateResult.retryAfter }));
+        return;
+      }
+
+      // XSS sanitize input
+      if (req.body && options.xss !== false) {
+        req.body = XSSProtection.sanitizeObject(req.body);
+      }
+      if (req.query && options.xss !== false) {
+        req.query = XSSProtection.sanitizeObject(req.query);
+      }
+
+      // Input sanitization
+      if (options.sanitize !== false) {
+        InputSanitizer.sanitizeRequest(req);
+      }
+
+      next();
+    };
+  }
+
+  /**
+   * Quick setup: add all security to a Volt app
+   */
+  static secure(app, options = {}) {
+    app.use(Security.all(options));
+    return app;
+  }
+}
+
+module.exports = {
+  Security,
+  Auth,
+  CSRF,
+  XSSProtection,
+  CORSHandler,
+  RateLimiter,
+  Encryption,
+  SecurityHeaders,
+  InputSanitizer,
+};

package/src/security/rateLimit.js

@@ -0,0 +1,119 @@
+/**
+ * VoltJS Rate Limiter
+ * 
+ * Protects against brute force and DDoS attacks.
+ * Memory-based by default, supports custom stores.
+ */
+
+'use strict';
+
+class RateLimiter {
+  constructor(options = {}) {
+    this._windowMs = options.windowMs || 15 * 60 * 1000; // 15 min
+    this._max = options.max || 100;
+    this._message = options.message || 'Too many requests, please try again later';
+    this._statusCode = options.statusCode || 429;
+    this._keyGenerator = options.keyGenerator || ((req) => {
+      return req.headers['x-forwarded-for'] || req.socket.remoteAddress || 'unknown';
+    });
+    this._skipIf = options.skipIf || null;
+    this._store = new Map();
+    this._cleanup = setInterval(() => this._cleanupExpired(), this._windowMs);
+  }
+
+  /** Check if a request is rate limited */
+  check(req) {
+    const key = this._keyGenerator(req);
+    const now = Date.now();
+
+    if (!this._store.has(key)) {
+      this._store.set(key, { count: 1, startTime: now, resetTime: now + this._windowMs });
+      return { allowed: true, remaining: this._max - 1, resetTime: now + this._windowMs };
+    }
+
+    const entry = this._store.get(key);
+
+    // Check if window has expired
+    if (now > entry.resetTime) {
+      this._store.set(key, { count: 1, startTime: now, resetTime: now + this._windowMs });
+      return { allowed: true, remaining: this._max - 1, resetTime: now + this._windowMs };
+    }
+
+    entry.count++;
+    this._store.set(key, entry);
+
+    if (entry.count > this._max) {
+      return {
+        allowed: false,
+        remaining: 0,
+        resetTime: entry.resetTime,
+        retryAfter: Math.ceil((entry.resetTime - now) / 1000),
+      };
+    }
+
+    return { allowed: true, remaining: this._max - entry.count, resetTime: entry.resetTime };
+  }
+
+  /** Middleware: Rate limiting */
+  static middleware(options = {}) {
+    const limiter = new RateLimiter(options);
+
+    return (req, res) => {
+      // Skip if condition met
+      if (limiter._skipIf && limiter._skipIf(req)) return;
+
+      const result = limiter.check(req);
+
+      // Set rate limit headers
+      res.setHeader('X-RateLimit-Limit', limiter._max);
+      res.setHeader('X-RateLimit-Remaining', Math.max(0, result.remaining));
+      res.setHeader('X-RateLimit-Reset', Math.ceil(result.resetTime / 1000));
+
+      if (!result.allowed) {
+        res.setHeader('Retry-After', result.retryAfter);
+        res.json({
+          error: limiter._message,
+          retryAfter: result.retryAfter,
+        }, limiter._statusCode);
+        return false;
+      }
+    };
+  }
+
+  /** Create API-specific rate limiter (stricter) */
+  static apiLimiter(options = {}) {
+    return RateLimiter.middleware({
+      windowMs: options.windowMs || 60 * 1000, // 1 minute
+      max: options.max || 30,
+      ...options,
+    });
+  }
+
+  /** Create auth-specific rate limiter (very strict) */
+  static authLimiter(options = {}) {
+    return RateLimiter.middleware({
+      windowMs: options.windowMs || 15 * 60 * 1000, // 15 min
+      max: options.max || 5,
+      message: 'Too many login attempts, please try again later',
+      ...options,
+    });
+  }
+
+  /** Clean up expired entries */
+  _cleanupExpired() {
+    const now = Date.now();
+    for (const [key, entry] of this._store) {
+      if (now > entry.resetTime) {
+        this._store.delete(key);
+      }
+    }
+  }
+
+  /** Destroy the rate limiter (clear interval) */
+  destroy() {
+    clearInterval(this._cleanup);
+    this._store.clear();
+  }
+}
+
+module.exports = { RateLimiter };