@joystick.js/db-canary 0.0.0-canary.2209

package/src/server/lib/query_engine.js

@@ -0,0 +1,243 @@
+/**
+ * @fileoverview Core database engine using LMDB for persistent storage with automatic map size management.
+ * 
+ * Provides the foundational database layer for JoystickDB, handling LMDB initialization,
+ * document key generation, collection management, and automatic database growth.
+ * Integrates with index and auto-index managers for comprehensive data management.
+ */
+
+import * as lmdb from 'lmdb';
+import { rmSync, existsSync } from 'fs';
+import create_logger from './logger.js';
+import { calculate_map_size, get_disk_size, should_grow_map_size } from './disk_utils.js';
+import { initialize_index_database, cleanup_index_database } from './index_manager.js';
+import { initialize_auto_index_database, cleanup_auto_index_database } from './auto_index_manager.js';
+
+const { create_context_logger } = create_logger('query_engine');
+
+/** @type {lmdb.Database|null} Main LMDB database instance */
+let db_instance = null;
+
+/** @type {number|null} Current database map size in bytes */
+let current_map_size = null;
+
+/** @type {string|null} Path to database directory */
+let database_path = null;
+
+/**
+ * Initializes the LMDB database with automatic map size calculation and compression.
+ * Sets up the main database instance along with index and auto-index databases.
+ * @param {string} [db_path='./data'] - Path to database directory
+ * @returns {lmdb.Database} Initialized database instance
+ */
+const initialize_database = (db_path = './data') => {
+  const log = create_context_logger();
+  
+  if (!db_instance) {
+    database_path = db_path;
+    
+    calculate_map_size(database_path).then((map_size) => {
+      current_map_size = map_size;
+      
+      if (db_instance && db_instance.resize) {
+        db_instance.resize(current_map_size);
+        
+        log.info('Database map_size updated', {
+          path: database_path,
+          map_size: current_map_size,
+          map_size_gb: Math.round(current_map_size / (1024 * 1024 * 1024) * 100) / 100
+        });
+      }
+    }).catch((error) => {
+      log.warn('Failed to calculate map_size, using default', {
+        database_path,
+        error: error.message
+      });
+    });
+    
+    const default_map_size = 1024 * 1024 * 1024 * 10;
+    current_map_size = default_map_size;
+    
+    db_instance = lmdb.open({
+      path: database_path,
+      compression: true,
+      useVersions: false,
+      encoding: 'msgpack',
+      mapSize: current_map_size
+    });
+    
+    log.info('Database initialized', {
+      path: database_path,
+      map_size: current_map_size,
+      map_size_gb: Math.round(current_map_size / (1024 * 1024 * 1024) * 100) / 100
+    });
+    
+    initialize_index_database();
+    initialize_auto_index_database();
+  }
+  return db_instance;
+};
+
+/**
+ * Checks database usage and automatically grows map size if needed.
+ * Monitors database statistics and disk space to determine optimal growth.
+ * @returns {Promise<void>}
+ */
+const check_and_grow_map_size = async () => {
+  if (!db_instance || !database_path) {
+    return;
+  }
+  
+  const log = create_context_logger();
+  
+  try {
+    const stats = db_instance.getStats ? db_instance.getStats() : {};
+    const used_size = stats.ms_psize * stats.ms_leaf_pages || 0;
+    
+    if (used_size === 0) {
+      return;
+    }
+    
+    const disk_size = await get_disk_size(database_path);
+    const new_map_size = should_grow_map_size(current_map_size, used_size, disk_size);
+    
+    if (new_map_size) {
+      log.info('Growing map_size', {
+        current_map_size,
+        new_map_size,
+        used_size,
+        usage_percentage: Math.round((used_size / current_map_size) * 100)
+      });
+      
+      db_instance.resize(new_map_size);
+      current_map_size = new_map_size;
+      
+      log.info('Map size grown successfully', {
+        new_map_size,
+        new_map_size_gb: Math.round(new_map_size / (1024 * 1024 * 1024) * 100) / 100
+      });
+    }
+  } catch (error) {
+    log.error('Failed to check/grow map_size', { error: error.message });
+  }
+};
+
+/**
+ * Gets the initialized database instance.
+ * @returns {lmdb.Database} Database instance
+ * @throws {Error} When database is not initialized
+ */
+const get_database = () => {
+  if (!db_instance) {
+    throw new Error('Database not initialized. Call initialize_database first.');
+  }
+  return db_instance;
+};
+
+/**
+ * Generates a unique document ID using timestamp and random string.
+ * @returns {string} Unique document identifier
+ */
+const generate_document_id = () => {
+  return `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+};
+
+/**
+ * Builds a database key for a document in a collection.
+ * @param {string} database_name - Name of the database
+ * @param {string} collection_name - Name of the collection
+ * @param {string} document_id - Document identifier
+ * @returns {string} Database key in format "database:collection:document_id"
+ */
+const build_collection_key = (database_name, collection_name, document_id) => {
+  return `${database_name}:${collection_name}:${document_id}`;
+};
+
+/**
+ * Parses a database key to extract database name, collection name and document ID.
+ * @param {string} key - Database key in format "database:collection:document_id"
+ * @returns {Object} Parsed key components
+ * @returns {string} returns.database - Database name
+ * @returns {string} returns.collection - Collection name
+ * @returns {string} returns.document_id - Document identifier
+ */
+const parse_collection_key = (key) => {
+  const parts = key.split(':');
+  return {
+    database: parts[0],
+    collection: parts[1],
+    document_id: parts.slice(2).join(':')
+  };
+};
+
+/**
+ * Cleanly shuts down the database and all associated resources.
+ * Closes index databases, auto-index databases, and the main database instance.
+ * @param {boolean} [remove_directory=false] - Whether to remove the database directory from disk
+ * @returns {Promise<void>}
+ */
+const cleanup_database = async (remove_directory = false) => {
+  const log = create_context_logger();
+  const path_to_remove = database_path;
+  
+  if (db_instance) {
+    try {
+      // Wait a bit to ensure all operations are complete
+      await new Promise(resolve => setTimeout(resolve, 100));
+      
+      // Cleanup databases first
+      cleanup_auto_index_database();
+      cleanup_index_database();
+      
+      // Close the main database
+      await db_instance.close();
+      log.info('Database closed successfully');
+    } catch (error) {
+      log.warn('Error closing database', { error: error.message });
+    }
+    
+    // Reset all state
+    db_instance = null;
+    current_map_size = null;
+    database_path = null;
+  }
+  
+  // Remove directory if requested and it's a test directory
+  if (remove_directory && path_to_remove && is_test_database_path(path_to_remove)) {
+    try {
+      if (existsSync(path_to_remove)) {
+        rmSync(path_to_remove, { recursive: true, force: true });
+        log.info('Test database directory removed', { path: path_to_remove });
+      }
+    } catch (error) {
+      log.warn('Failed to remove test database directory', { 
+        path: path_to_remove, 
+        error: error.message 
+      });
+    }
+  }
+};
+
+/**
+ * Determines if a database path is a test database that can be safely removed.
+ * @param {string} path - Database path to check
+ * @returns {boolean} True if it's a test database path
+ */
+const is_test_database_path = (path) => {
+  return path && (
+    path.includes('test_data') || 
+    path.startsWith('./test_') ||
+    path.startsWith('test_')
+  );
+};
+
+export {
+  initialize_database,
+  get_database,
+  generate_document_id,
+  build_collection_key,
+  parse_collection_key,
+  check_and_grow_map_size,
+  cleanup_database,
+  is_test_database_path
+};

package/src/server/lib/recovery_manager.js

@@ -0,0 +1,388 @@
+/**
+ * @fileoverview Emergency password recovery system for JoystickDB authentication.
+ * Provides secure token-based password recovery with rate limiting, expiration handling,
+ * and lockout protection. Enables emergency password changes when normal authentication
+ * is compromised or unavailable, with comprehensive security measures and audit logging.
+ */
+
+import { readFileSync, writeFileSync, existsSync, unlinkSync } from 'fs';
+import crypto from 'crypto';
+import bcrypt from 'bcrypt';
+import create_logger from './logger.js';
+
+const { create_context_logger } = create_logger('recovery_manager');
+const log = create_context_logger();
+
+/** @type {string} Path to recovery token storage file */
+const RECOVERY_TOKEN_FILE = './recovery_token.json';
+
+import { load_settings as load_joystick_settings, get_settings as get_joystick_settings, has_settings } from './load_settings.js';
+
+/** @type {number} Recovery token expiration time in minutes */
+const TOKEN_EXPIRY_MINUTES = 10;
+
+/** @type {number} Bcrypt salt rounds for password hashing */
+const SALT_ROUNDS = 12;
+
+/** @type {number} Maximum failed recovery attempts before lockout */
+const MAX_RECOVERY_ATTEMPTS = 3;
+
+/** @type {Object} Current recovery state tracking */
+let recovery_state = {
+  token: null,
+  expires_at: null,
+  failed_attempts: 0,
+  locked_until: null
+};
+
+/**
+ * Generates a cryptographically secure recovery token.
+ * Uses Node.js crypto.randomUUID() for secure token generation.
+ * @returns {string} Secure UUID token for recovery authentication
+ */
+const generate_recovery_token = () => {
+  return crypto.randomUUID();
+};
+
+/**
+ * Creates a new recovery token with expiration and saves it to file.
+ * Generates a secure token, sets expiration time, and stores recovery state
+ * both in memory and persistent storage with restricted file permissions.
+ * @returns {Object} Recovery token information
+ * @returns {string} returns.token - Generated recovery token
+ * @returns {number} returns.expires_at - Token expiration timestamp
+ * @returns {string} returns.url - Complete recovery URL with token
+ * @throws {Error} When token file cannot be saved
+ */
+const create_recovery_token = () => {
+  const token = generate_recovery_token();
+  const expires_at = Date.now() + (TOKEN_EXPIRY_MINUTES * 60 * 1000);
+  
+  recovery_state = {
+    token,
+    expires_at,
+    failed_attempts: 0,
+    locked_until: null
+  };
+  
+  // NOTE: Store token temporarily in memory and file.
+  try {
+    writeFileSync(RECOVERY_TOKEN_FILE, JSON.stringify(recovery_state, null, 2), { mode: 0o600 });
+    log.info('Recovery token generated', { expires_at: new Date(expires_at).toISOString() });
+  } catch (error) {
+    log.error('Failed to save recovery token', { error: error.message });
+    throw new Error(`Failed to save recovery token: ${error.message}`);
+  }
+  
+  return {
+    token,
+    expires_at,
+    url: `http://localhost:1984/recovery?token=${token}`
+  };
+};
+
+/**
+ * Loads recovery state from persistent storage file.
+ * Reads recovery token file and parses state, falling back to defaults
+ * if file doesn't exist or parsing fails. Handles corrupted state gracefully.
+ * @returns {void}
+ */
+const load_recovery_state = () => {
+  try {
+    if (!existsSync(RECOVERY_TOKEN_FILE)) {
+      recovery_state = {
+        token: null,
+        expires_at: null,
+        failed_attempts: 0,
+        locked_until: null
+      };
+      return;
+    }
+    
+    const raw_data = readFileSync(RECOVERY_TOKEN_FILE, 'utf8');
+    const parsed_data = JSON.parse(raw_data);
+    
+    recovery_state = {
+      token: parsed_data.token || null,
+      expires_at: parsed_data.expires_at || null,
+      failed_attempts: parsed_data.failed_attempts || 0,
+      locked_until: parsed_data.locked_until || null
+    };
+    
+    log.info('Recovery state loaded');
+  } catch (error) {
+    log.warn('Failed to load recovery state, using defaults', { error: error.message });
+    recovery_state = {
+      token: null,
+      expires_at: null,
+      failed_attempts: 0,
+      locked_until: null
+    };
+  }
+};
+
+/**
+ * Saves current recovery state to persistent storage file.
+ * Writes recovery state to file with restricted permissions for security.
+ * Logs errors but doesn't throw to avoid disrupting recovery operations.
+ * @returns {void}
+ */
+const save_recovery_state = () => {
+  try {
+    writeFileSync(RECOVERY_TOKEN_FILE, JSON.stringify(recovery_state, null, 2), { mode: 0o600 });
+  } catch (error) {
+    log.error('Failed to save recovery state', { error: error.message });
+  }
+};
+
+/**
+ * Cleans up recovery token and resets state.
+ * Resets in-memory state and removes recovery token file from disk.
+ * Used after successful recovery or token expiration.
+ * @returns {void}
+ */
+const cleanup_recovery_token = () => {
+  recovery_state = {
+    token: null,
+    expires_at: null,
+    failed_attempts: 0,
+    locked_until: null
+  };
+  
+  try {
+    if (existsSync(RECOVERY_TOKEN_FILE)) {
+      unlinkSync(RECOVERY_TOKEN_FILE);
+    }
+  } catch (error) {
+    log.warn('Failed to cleanup recovery token file', { error: error.message });
+  }
+};
+
+/**
+ * Validates a provided recovery token against current state.
+ * Checks token existence, expiration, lockout status, and token match.
+ * Reloads state from file to ensure latest data and handles cleanup.
+ * @param {string} provided_token - Token to validate
+ * @returns {Object} Validation result
+ * @returns {boolean} returns.valid - Whether token is valid
+ * @returns {string} returns.reason - Reason for invalidity if applicable
+ */
+const is_token_valid = (provided_token) => {
+  // NOTE: Always reload state from file to get latest data.
+  load_recovery_state();
+  
+  const now = Date.now();
+  
+  // NOTE: Check if recovery is locked due to too many failed attempts.
+  if (recovery_state.locked_until && now < recovery_state.locked_until) {
+    return { valid: false, reason: 'locked' };
+  }
+  
+  // NOTE: Check if token exists and hasn't expired.
+  if (!recovery_state.token || !recovery_state.expires_at) {
+    return { valid: false, reason: 'no_token' };
+  }
+  
+  if (now > recovery_state.expires_at) {
+    cleanup_recovery_token();
+    return { valid: false, reason: 'expired' };
+  }
+  
+  if (provided_token !== recovery_state.token) {
+    return { valid: false, reason: 'invalid' };
+  }
+  
+  return { valid: true };
+};
+
+/**
+ * Records a failed recovery attempt and applies lockout if needed.
+ * Increments failed attempt counter and locks recovery if maximum attempts
+ * are exceeded. Saves state to persistent storage and logs security events.
+ * @param {string} ip - IP address of failed attempt for audit logging
+ * @returns {void}
+ */
+const record_failed_recovery_attempt = (ip) => {
+  recovery_state.failed_attempts += 1;
+  
+  log.warn('Failed recovery attempt', {
+    ip,
+    attempt_count: recovery_state.failed_attempts
+  });
+  
+  if (recovery_state.failed_attempts >= MAX_RECOVERY_ATTEMPTS) {
+    const lock_duration = 30 * 60 * 1000; // 30 minutes
+    recovery_state.locked_until = Date.now() + lock_duration;
+    
+    log.warn('Recovery locked due to too many failed attempts', {
+      ip,
+      locked_until: new Date(recovery_state.locked_until).toISOString()
+    });
+  }
+  
+  save_recovery_state();
+};
+
+/**
+ * Validates password strength requirements for recovery.
+ * Checks password existence, type, and minimum length requirements
+ * to ensure secure password policies are enforced.
+ * @param {string} password - Password to validate
+ * @returns {Object} Validation result
+ * @returns {boolean} returns.valid - Whether password meets requirements
+ * @returns {string} returns.message - Error message if validation fails
+ */
+const validate_password_strength = (password) => {
+  if (!password || typeof password !== 'string') {
+    return { valid: false, message: 'Password is required' };
+  }
+  
+  if (password.length < 12) {
+    return { valid: false, message: 'Password must be at least 12 characters long' };
+  }
+  
+  return { valid: true };
+};
+
+/**
+ * Changes the database password through emergency recovery process.
+ * Validates password strength, hashes new password, updates settings file,
+ * terminates existing connections, and cleans up recovery state. Provides
+ * atomic updates with rollback protection and comprehensive audit logging.
+ * @param {string} new_password - New password to set
+ * @param {string} client_ip - IP address of recovery request for audit
+ * @param {Function|null} [connection_terminator=null] - Function to terminate active connections
+ * @returns {Promise<Object>} Password change result
+ * @returns {boolean} returns.success - Whether password change succeeded
+ * @returns {string} returns.timestamp - ISO timestamp of password change
+ * @returns {string} returns.message - Success message
+ * @throws {Error} When password validation fails or settings update fails
+ */
+const change_password = async (new_password, client_ip, connection_terminator = null) => {
+  const validation = validate_password_strength(new_password);
+  if (!validation.valid) {
+    throw new Error(validation.message);
+  }
+  
+  try {
+    // NOTE: Load current settings from environment variable.
+    if (!has_settings()) {
+      throw new Error('JOYSTICK_DB_SETTINGS environment variable not found');
+    }
+    
+    const settings_data = load_joystick_settings();
+    
+    if (!settings_data.authentication) {
+      throw new Error('Authentication not configured');
+    }
+    
+    // NOTE: Hash new password.
+    const new_password_hash = await bcrypt.hash(new_password, SALT_ROUNDS);
+    const now = new Date().toISOString();
+    
+    // NOTE: Update authentication section.
+    settings_data.authentication.password_hash = new_password_hash;
+    settings_data.authentication.last_updated = now;
+    settings_data.authentication.failed_attempts = {};
+    settings_data.authentication.rate_limits = {};
+    
+    // NOTE: Update the environment variable with the new settings.
+    process.env.JOYSTICK_DB_SETTINGS = JSON.stringify(settings_data);
+    
+    // NOTE: Terminate all existing connections if terminator function provided.
+    if (connection_terminator && typeof connection_terminator === 'function') {
+      try {
+        connection_terminator();
+        log.info('All existing connections terminated due to password change');
+      } catch (termination_error) {
+        log.warn('Failed to terminate some connections', { error: termination_error.message });
+      }
+    }
+    
+    // NOTE: Cleanup recovery token after successful password change.
+    cleanup_recovery_token();
+    
+    log.info('Emergency password change completed', {
+      client_ip,
+      timestamp: now
+    });
+    
+    return {
+      success: true,
+      timestamp: now,
+      message: 'Password changed successfully'
+    };
+  } catch (error) {
+    log.error('Emergency password change failed', {
+      client_ip,
+      error: error.message
+    });
+    throw error;
+  }
+};
+
+/**
+ * Gets current recovery system status and state information.
+ * Returns comprehensive status including token validity, expiration,
+ * failed attempts, and lockout status for monitoring and debugging.
+ * @returns {Object} Recovery status information
+ * @returns {boolean} returns.token_active - Whether a valid token exists
+ * @returns {number|null} returns.expires_at - Token expiration timestamp
+ * @returns {number} returns.failed_attempts - Number of failed attempts
+ * @returns {number|null} returns.locked_until - Lockout expiration timestamp
+ * @returns {boolean} returns.is_locked - Whether recovery is currently locked
+ */
+const get_recovery_status = () => {
+  const now = Date.now();
+  
+  return {
+    token_active: !!(recovery_state.token && recovery_state.expires_at && now < recovery_state.expires_at),
+    expires_at: recovery_state.expires_at,
+    failed_attempts: recovery_state.failed_attempts,
+    locked_until: recovery_state.locked_until,
+    is_locked: !!(recovery_state.locked_until && now < recovery_state.locked_until)
+  };
+};
+
+/**
+ * Initializes the recovery manager and cleans up expired state.
+ * Loads recovery state from file, cleans up expired tokens and locks,
+ * and ensures the recovery system is in a consistent state on startup.
+ * @returns {void}
+ */
+const initialize_recovery_manager = () => {
+  load_recovery_state();
+  
+  // NOTE: Clean up expired tokens on startup.
+  const now = Date.now();
+  if (recovery_state.expires_at && now > recovery_state.expires_at) {
+    cleanup_recovery_token();
+  }
+  
+  // NOTE: Clean up expired locks.
+  if (recovery_state.locked_until && now > recovery_state.locked_until) {
+    recovery_state.locked_until = null;
+    recovery_state.failed_attempts = 0;
+    save_recovery_state();
+  }
+};
+
+/**
+ * Resets all recovery state and cleans up tokens.
+ * Completely clears recovery state and removes token files.
+ * Used for administrative cleanup or system reset operations.
+ * @returns {void}
+ */
+const reset_recovery_state = () => {
+  cleanup_recovery_token();
+};
+
+export {
+  create_recovery_token,
+  is_token_valid,
+  record_failed_recovery_attempt,
+  change_password,
+  get_recovery_status,
+  initialize_recovery_manager,
+  reset_recovery_state
+};