cipher-shield 1.0.0

package/src/core/defconSystem.js

@@ -0,0 +1,301 @@
+/**
+ * Adaptive DEFCON Threat Escalation System v2.1
+ *
+ * Intelligent threat level management system that automatically escalates security
+ * measures based on detected malicious activity. Implements a cooldown-based
+ * system to prevent persistent high-security states while maintaining protection.
+ *
+ * DEFCON States:
+ * - GREEN: Normal operation, all security features active but not aggressive
+ * - RED: High alert, conservative security measures (may skip resource-intensive checks)
+ *
+ * Features:
+ * - Automatic escalation based on threat patterns
+ * - Configurable thresholds and cooldown periods
+ * - Thread-safe operations for concurrent requests
+ * - Performance monitoring and logging
+ *
+ * @module defconSystem
+ * @version 1.0.0
+ * @author Omindu Dissanayaka
+ * @license MIT
+ */
+
+/**
+ * DEFCON security states enumeration
+ * @readonly
+ * @enum {string}
+ */
+const DEFCON_STATES = Object.freeze({
+  GREEN: 'GREEN',
+  RED: 'RED'
+});
+
+/**
+ * Default configuration constants
+ * These can be overridden for custom deployments
+ */
+const DEFAULT_CONFIG = Object.freeze({
+  ESCALATION_TIMEOUT: 300000,
+  ESCALATION_THRESHOLD: 3,
+  MAX_ESCALATION_COUNT: 100
+});
+
+/**
+ * Internal state management
+ * @private
+ */
+let currentState = DEFCON_STATES.GREEN;
+let escalationCount = 0;
+let cooldownTimer = null;
+let lastEscalationTime = null;
+let threatHistory = [];
+
+/**
+ * Initializes the DEFCON system to default state
+ *
+ * Resets all internal counters, clears any active timers, and prepares
+ * the system for fresh threat monitoring. Should be called during
+ * application startup or when manually resetting security state.
+ *
+ * @function initialize
+ * @returns {void}
+ *
+ * @example
+ * ```javascript
+ * const defconSystem = require('./defconSystem');
+ * defconSystem.initialize(); // Reset to GREEN state
+ * ```
+ */
+function initialize() {
+  currentState = DEFCON_STATES.GREEN;
+  escalationCount = 0;
+  lastEscalationTime = null;
+  threatHistory = [];
+
+  if (cooldownTimer) {
+    clearTimeout(cooldownTimer);
+    cooldownTimer = null;
+  }
+
+  if (process.env.NODE_ENV === 'development') {
+    console.log('[DEFCON] System initialized to GREEN state');
+  }
+}
+
+/**
+ * Retrieves the current DEFCON security state
+ *
+ * @function getState
+ * @returns {string} Current DEFCON state ('GREEN' or 'RED')
+ *
+ * @example
+ * ```javascript
+ * const state = defconSystem.getState();
+ * if (state === 'RED') {
+ *   // Apply conservative security measures
+ * }
+ * ```
+ */
+function getState() {
+  return currentState;
+}
+
+/**
+ * Escalates the threat level based on detected malicious activity
+ *
+ * Increments the escalation counter and automatically transitions to RED state
+ * when the threshold is reached. Implements cooldown-based auto-reset to
+ * prevent indefinite high-security states.
+ *
+ * @function escalate
+ * @param {string} reason - Description of the threat that triggered escalation
+ * @returns {boolean} True if escalation occurred, false if threshold not met
+ *
+ * @example
+ * ```javascript
+ * defconSystem.escalate('Multiple failed login attempts');
+ * defconSystem.escalate('Suspicious payload detected');
+ * ```
+ */
+function escalate(reason) {
+  if (!reason || typeof reason !== 'string') {
+    reason = 'Unknown threat';
+  }
+
+  if (escalationCount >= DEFAULT_CONFIG.MAX_ESCALATION_COUNT) {
+    if (process.env.NODE_ENV === 'development') {
+      console.warn('[DEFCON] Escalation count at maximum, maintaining current state');
+    }
+    return false;
+  }
+
+  escalationCount++;
+  lastEscalationTime = Date.now();
+
+  threatHistory.push({
+    timestamp: lastEscalationTime,
+    reason: reason,
+    count: escalationCount
+  });
+
+  if (threatHistory.length > 100) {
+    threatHistory = threatHistory.slice(-100);
+  }
+
+  if (escalationCount >= DEFAULT_CONFIG.ESCALATION_THRESHOLD && currentState === DEFCON_STATES.GREEN) {
+    currentState = DEFCON_STATES.RED;
+
+    if (cooldownTimer) {
+      clearTimeout(cooldownTimer);
+    }
+
+    cooldownTimer = setTimeout(() => {
+      currentState = DEFCON_STATES.GREEN;
+      escalationCount = Math.floor(escalationCount / 2);
+      cooldownTimer = null;
+
+      if (process.env.NODE_ENV === 'development') {
+        console.log(`[DEFCON] Auto-reset to GREEN after ${DEFAULT_CONFIG.ESCALATION_TIMEOUT / 1000}s cooldown`);
+      }
+    }, DEFAULT_CONFIG.ESCALATION_TIMEOUT);
+
+    if (process.env.NODE_ENV === 'development') {
+      console.warn(`[DEFCON] 🚨 ESCALATED to RED state: ${reason} (${escalationCount}/${DEFAULT_CONFIG.ESCALATION_THRESHOLD})`);
+    }
+
+    return true;
+  }
+
+  if (process.env.NODE_ENV === 'development') {
+    console.log(`[DEFCON] Threat detected: ${reason} (${escalationCount}/${DEFAULT_CONFIG.ESCALATION_THRESHOLD})`);
+  }
+
+  return false;
+}
+
+/**
+ * Manually sets the DEFCON state (for testing or administrative override)
+ *
+ * Allows direct state manipulation, useful for testing, maintenance, or
+ * administrative security controls. Automatically handles timer cleanup
+ * and counter resets.
+ *
+ * @function setState
+ * @param {string} state - Target state ('GREEN' or 'RED')
+ * @returns {boolean} True if state was changed, false if invalid state provided
+ *
+ * @example
+ * ```javascript
+ * defconSystem.setState('RED');   // Force high alert
+ * defconSystem.setState('GREEN'); // Reset to normal
+ * ```
+ */
+function setState(state) {
+  if (state !== DEFCON_STATES.GREEN && state !== DEFCON_STATES.RED) {
+    if (process.env.NODE_ENV === 'development') {
+      console.error(`[DEFCON] Invalid state: ${state}. Must be 'GREEN' or 'RED'`);
+    }
+    return false;
+  }
+
+  const previousState = currentState;
+  currentState = state;
+
+  if (state === DEFCON_STATES.GREEN) {
+    escalationCount = 0;
+    lastEscalationTime = null;
+
+    if (cooldownTimer) {
+      clearTimeout(cooldownTimer);
+      cooldownTimer = null;
+    }
+  }
+
+  if (process.env.NODE_ENV === 'development') {
+    console.log(`[DEFCON] Manual state change: ${previousState} → ${state}`);
+  }
+
+  return true;
+}
+
+/**
+ * Retrieves current system status and statistics
+ *
+ * Provides comprehensive information about the current DEFCON state,
+ * escalation history, and system health for monitoring and debugging.
+ *
+ * @function getStatus
+ * @returns {Object} System status information
+ * @property {string} state - Current DEFCON state
+ * @property {number} escalationCount - Current escalation counter
+ * @property {number} threshold - Escalation threshold
+ * @property {number|null} lastEscalationTime - Timestamp of last escalation
+ * @property {number} cooldownRemaining - Milliseconds until auto-reset (0 if not in RED)
+ * @property {Array} recentThreats - Last 10 threats detected
+ *
+ * @example
+ * ```javascript
+ * const status = defconSystem.getStatus();
+ * console.log(`State: ${status.state}, Threats: ${status.escalationCount}`);
+ * ```
+ */
+function getStatus() {
+  const now = Date.now();
+  let cooldownRemaining = 0;
+
+  if (currentState === DEFCON_STATES.RED && cooldownTimer) {
+    const elapsed = now - (lastEscalationTime || now);
+    cooldownRemaining = Math.max(0, DEFAULT_CONFIG.ESCALATION_TIMEOUT - elapsed);
+  }
+
+  return {
+    state: currentState,
+    escalationCount,
+    threshold: DEFAULT_CONFIG.ESCALATION_THRESHOLD,
+    lastEscalationTime,
+    cooldownRemaining,
+    recentThreats: threatHistory.slice(-10),
+    config: {
+      escalationTimeout: DEFAULT_CONFIG.ESCALATION_TIMEOUT,
+      maxEscalationCount: DEFAULT_CONFIG.MAX_ESCALATION_COUNT
+    }
+  };
+}
+
+/**
+ * Resets escalation counter without changing state
+ *
+ * Useful for gradual cooldown or manual intervention while maintaining
+ * current security posture.
+ *
+ * @function resetCounter
+ * @returns {number} Previous escalation count
+ *
+ * @example
+ * ```javascript
+ * const previousCount = defconSystem.resetCounter();
+ * console.log(`Reset counter from ${previousCount} to 0`);
+ * ```
+ */
+function resetCounter() {
+  const previousCount = escalationCount;
+  escalationCount = 0;
+
+  if (process.env.NODE_ENV === 'development') {
+    console.log(`[DEFCON] Escalation counter reset from ${previousCount} to 0`);
+  }
+
+  return previousCount;
+}
+
+module.exports = {
+  initialize,
+  getState,
+  escalate,
+  setState,
+  getStatus,
+  resetCounter,
+  DEFCON_STATES,
+  DEFAULT_CONFIG
+};

package/src/magicAuth.js

@@ -0,0 +1,272 @@
+/**
+ * MagicAuth - Secure JWT Authentication Wrapper
+ *
+ * A simplified and secure JWT authentication utility with automatic secret management,
+ * secure defaults, and Express middleware integration.
+ *
+ * @module MagicAuth
+ * @version 1.0.0
+ * @author Omindu Dissanayaka
+ * @license MIT
+ */
+
+const jwt = require('jsonwebtoken');
+
+class MagicAuth {
+  /**
+   * Creates a MagicAuth instance
+   *
+   * @param {Object} [options] - Configuration options
+   * @param {string} [options.secret] - JWT secret (defaults to process.env.JWT_SECRET)
+   * @param {string} [options.algorithm='HS256'] - JWT algorithm
+   * @param {string|number} [options.expiresIn='1h'] - Default token expiration
+   * @param {string} [options.issuer] - JWT issuer
+   * @param {string} [options.audience] - JWT audience
+   * @param {boolean} [options.requireSecret=true] - Require secret to be set
+   */
+  constructor(options = {}) {
+    this.options = {
+      secret: options.secret || process.env.JWT_SECRET,
+      algorithm: options.algorithm || 'HS256',
+      expiresIn: options.expiresIn || '1h',
+      issuer: options.issuer,
+      audience: options.audience,
+      requireSecret: options.requireSecret !== false,
+      ...options
+    };
+
+    this._validateSecret();
+
+    this.defaultSignOptions = {
+      algorithm: this.options.algorithm,
+      expiresIn: this.options.expiresIn,
+      ...(this.options.issuer && { issuer: this.options.issuer }),
+      ...(this.options.audience && { audience: this.options.audience })
+    };
+
+    this.defaultVerifyOptions = {
+      algorithms: [this.options.algorithm],
+      ...(this.options.issuer && { issuer: this.options.issuer }),
+      ...(this.options.audience && { audience: this.options.audience })
+    };
+  }
+
+  /**
+   * Validate JWT secret configuration
+   *
+   * @private
+   * @throws {Error} If secret is required but not provided
+   */
+  _validateSecret() {
+    if (this.options.requireSecret && !this.options.secret) {
+      const isProduction = process.env.NODE_ENV === 'production';
+      const message = 'JWT_SECRET environment variable is required for MagicAuth. ' +
+        'Set process.env.JWT_SECRET or pass secret in options.';
+
+      if (isProduction) {
+        throw new Error(message);
+      } else {
+        console.warn(`[MagicAuth] ⚠️  WARNING: ${message}`);
+        this.options.secret = this._generateDevSecret();
+        console.warn(`[MagicAuth] 🔧 Using temporary development secret. DO NOT USE IN PRODUCTION!`);
+      }
+    }
+  }
+
+  /**
+   * Generate a temporary secret for development
+   *
+   * @private
+   * @returns {string} Temporary secret
+   */
+  _generateDevSecret() {
+    return require('crypto').randomBytes(32).toString('hex');
+  }
+
+  /**
+   * Sign a JWT token
+   *
+   * @param {Object} payload - Payload to encode in the token
+   * @param {Object} [options] - Additional sign options
+   * @returns {string} JWT token
+   * @throws {Error} If signing fails
+   */
+  sign(payload, options = {}) {
+    try {
+      if (!payload || typeof payload !== 'object') {
+        throw new Error('Payload must be a non-null object');
+      }
+
+      const signOptions = {
+        ...this.defaultSignOptions,
+        ...options
+      };
+
+      if (options.expiresIn === null) {
+        delete signOptions.expiresIn;
+      }
+
+      return jwt.sign(payload, this.options.secret, signOptions);
+    } catch (error) {
+      throw new Error(`JWT signing failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Verify and decode a JWT token
+   *
+   * @param {string} token - JWT token to verify
+   * @param {Object} [options] - Additional verify options
+   * @returns {Object} Decoded payload
+   * @throws {Error} If verification fails
+   */
+  verify(token, options = {}) {
+    try {
+      if (!token || typeof token !== 'string') {
+        throw new Error('Token must be a non-empty string');
+      }
+
+      const verifyOptions = {
+        ...this.defaultVerifyOptions,
+        ...options
+      };
+
+      return jwt.verify(token, this.options.secret, verifyOptions);
+    } catch (error) {
+      if (error.name === 'TokenExpiredError') {
+        throw new Error('Token has expired');
+      } else if (error.name === 'JsonWebTokenError') {
+        throw new Error('Invalid token');
+      } else if (error.name === 'NotBeforeError') {
+        throw new Error('Token not active');
+      } else {
+        throw new Error(`Token verification failed: ${error.message}`);
+      }
+    }
+  }
+
+  /**
+   * Express middleware for automatic JWT authentication
+   *
+   * Checks Authorization header for Bearer token, verifies it,
+   * and attaches payload to req.user
+   *
+   * @returns {Function} Express middleware function
+   */
+  middleware() {
+    return (req, res, next) => {
+      try {
+        const authHeader = req.headers.authorization;
+
+        if (!authHeader) {
+          return res.status(401).json({
+            error: 'Authentication required',
+            message: 'Authorization header is missing',
+            code: 'AUTH_MISSING'
+          });
+        }
+
+        if (!authHeader.startsWith('Bearer ')) {
+          return res.status(401).json({
+            error: 'Invalid authentication format',
+            message: 'Authorization header must start with "Bearer "',
+            code: 'AUTH_INVALID_FORMAT'
+          });
+        }
+
+        const token = authHeader.substring(7);
+
+        if (!token) {
+          return res.status(401).json({
+            error: 'Authentication required',
+            message: 'Bearer token is empty',
+            code: 'AUTH_EMPTY_TOKEN'
+          });
+        }
+
+        const payload = this.verify(token);
+
+        req.user = payload;
+
+        next();
+      } catch (error) {
+        const statusCode = error.message.includes('expired') ? 401 : 401;
+        const errorCode = error.message.includes('expired') ? 'AUTH_TOKEN_EXPIRED' : 'AUTH_TOKEN_INVALID';
+
+        return res.status(statusCode).json({
+          error: 'Authentication failed',
+          message: error.message,
+          code: errorCode
+        });
+      }
+    };
+  }
+
+  /**
+   * Refresh a token (create new token with same payload)
+   *
+   * @param {string} token - Existing token to refresh
+   * @param {Object} [options] - New sign options
+   * @returns {string} New JWT token
+   */
+  refresh(token, options = {}) {
+    const payload = this.verify(token);
+
+    const { iat, exp, ...cleanPayload } = payload;
+
+    return this.sign(cleanPayload, options);
+  }
+
+  /**
+   * Decode a token without verification (for debugging)
+   *
+   * @param {string} token - JWT token to decode
+   * @param {boolean} [complete=false] - Return complete decoded token
+   * @returns {Object|null} Decoded payload or null if invalid
+   */
+  decode(token, complete = false) {
+    try {
+      return jwt.decode(token, { complete });
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Get token expiration time
+   *
+   * @param {string} token - JWT token
+   * @returns {Date|null} Expiration date or null if invalid
+   */
+  getExpiration(token) {
+    try {
+      const decoded = jwt.decode(token);
+      if (decoded && decoded.exp) {
+        return new Date(decoded.exp * 1000);
+      }
+      return null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Check if token is expired
+   *
+   * @param {string} token - JWT token
+   * @returns {boolean} True if expired or invalid
+   */
+  isExpired(token) {
+    try {
+      const decoded = jwt.decode(token);
+      if (!decoded || !decoded.exp) {
+        return true;
+      }
+      return Date.now() >= decoded.exp * 1000;
+    } catch {
+      return true;
+    }
+  }
+}
+
+module.exports = MagicAuth;