filemayor 2.0.0

package/core/security.js

@@ -0,0 +1,317 @@
+#!/usr/bin/env node
+
+/**
+ * ═══════════════════════════════════════════════════════════════════
+ * FILEMAYOR CORE — SECURITY
+ * Path traversal guards, input sanitization, and safety checks
+ * ═══════════════════════════════════════════════════════════════════
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+// ─── Dangerous Paths ──────────────────────────────────────────────
+const PROTECTED_DIRECTORIES = new Set([
+    // System roots
+    '/', 'C:\\', 'C:\\Windows', 'C:\\Windows\\System32',
+    '/System', '/Library', '/usr', '/bin', '/sbin', '/etc',
+    '/boot', '/dev', '/proc', '/sys', '/run', '/var',
+
+    // User critical
+    path.join(os.homedir()), // Don't organize the entire home dir
+]);
+
+const PROTECTED_PREFIXES = [
+    '/System', '/Library/System',
+    'C:\\Windows', 'C:\\Program Files', 'C:\\Program Files (x86)',
+    'C:\\ProgramData', '/usr/lib', '/usr/bin', '/usr/sbin',
+    '/var/lib', '/var/run', '/boot', '/dev', '/proc', '/sys'
+];
+
+const DANGEROUS_EXTENSIONS = new Set([
+    '.sys', '.drv', '.dll', '.so', '.dylib', '.kext',
+    '.plist', '.reg', '.msc', '.cpl'
+]);
+
+// ─── Path Validation ──────────────────────────────────────────────
+
+/**
+ * Resolve and normalize a path, preventing traversal attacks
+ * @param {string} inputPath - Raw path from user input
+ * @param {string} [basePath] - Optional base to restrict resolution within
+ * @returns {{ valid: boolean, resolved: string, error?: string }}
+ */
+function validatePath(inputPath, basePath = null) {
+    if (!inputPath || typeof inputPath !== 'string') {
+        return { valid: false, resolved: '', error: 'Path is empty or invalid' };
+    }
+
+    // Reject null bytes (path traversal vector)
+    if (inputPath.includes('\0')) {
+        return { valid: false, resolved: '', error: 'Path contains null bytes (rejected)' };
+    }
+
+    // Resolve to absolute
+    const resolved = path.resolve(inputPath);
+
+    // If a basePath is given, ensure resolved path stays within it
+    if (basePath) {
+        const resolvedBase = path.resolve(basePath);
+        if (!resolved.startsWith(resolvedBase + path.sep) && resolved !== resolvedBase) {
+            return {
+                valid: false,
+                resolved,
+                error: `Path escapes base directory: "${resolved}" is outside "${resolvedBase}"`
+            };
+        }
+    }
+
+    // Check against protected directories
+    if (PROTECTED_DIRECTORIES.has(resolved)) {
+        return {
+            valid: false,
+            resolved,
+            error: `Refusing to operate on protected directory: "${resolved}"`
+        };
+    }
+
+    // Check against protected prefixes
+    for (const prefix of PROTECTED_PREFIXES) {
+        const normalizedPrefix = path.resolve(prefix);
+        if (resolved.startsWith(normalizedPrefix + path.sep) || resolved === normalizedPrefix) {
+            return {
+                valid: false,
+                resolved,
+                error: `Refusing to operate on system directory: "${resolved}"`
+            };
+        }
+    }
+
+    return { valid: true, resolved };
+}
+
+/**
+ * Check if a file is safe to move/delete (not a system critical file)
+ * @param {string} filePath - Absolute file path
+ * @returns {{ safe: boolean, reason?: string }}
+ */
+function isFileSafe(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    const basename = path.basename(filePath);
+
+    // Reject system-critical extensions
+    if (DANGEROUS_EXTENSIONS.has(ext)) {
+        return { safe: false, reason: `System file extension "${ext}" is protected` };
+    }
+
+    // Reject Windows system files
+    const systemFiles = ['ntldr', 'bootmgr', 'pagefile.sys', 'swapfile.sys', 'hiberfil.sys'];
+    if (systemFiles.includes(basename.toLowerCase())) {
+        return { safe: false, reason: `System file "${basename}" is protected` };
+    }
+
+    // Reject Unix critical files
+    const unixCritical = ['.bashrc', '.zshrc', '.profile', '.bash_profile', '.ssh'];
+    if (unixCritical.includes(basename.toLowerCase())) {
+        return { safe: false, reason: `User config file "${basename}" is protected` };
+    }
+
+    return { safe: true };
+}
+
+/**
+ * Check if a directory is safe to scan/organize
+ * @param {string} dirPath - Absolute directory path
+ * @returns {{ safe: boolean, reason?: string }}
+ */
+function isDirSafe(dirPath) {
+    const validation = validatePath(dirPath);
+    if (!validation.valid) {
+        return { safe: false, reason: validation.error };
+    }
+
+    // Don't operate on root of any drive
+    const parsed = path.parse(validation.resolved);
+    if (parsed.dir === parsed.root && parsed.base === '') {
+        return { safe: false, reason: 'Cannot operate on filesystem root' };
+    }
+
+    return { safe: true };
+}
+
+// ─── Input Sanitization ───────────────────────────────────────────
+
+/**
+ * Sanitize a filename for safe filesystem operations
+ * @param {string} filename - Raw filename
+ * @returns {string} Sanitized filename
+ */
+function sanitizeFilename(filename) {
+    if (!filename || typeof filename !== 'string') return 'unnamed';
+
+    return filename
+        // Remove null bytes
+        .replace(/\0/g, '')
+        // Remove path separators
+        .replace(/[/\\]/g, '_')
+        // Remove other dangerous characters
+        .replace(/[<>:"|?*]/g, '_')
+        // Remove control characters
+        .replace(/[\x00-\x1f\x80-\x9f]/g, '')
+        // Collapse multiple underscores/spaces
+        .replace(/_{2,}/g, '_')
+        .replace(/\s{2,}/g, ' ')
+        // Remove leading/trailing dots and spaces (Windows issue)
+        .replace(/^[\s.]+|[\s.]+$/g, '')
+        // Ensure not empty after sanitization
+        || 'unnamed';
+}
+
+/**
+ * Sanitize a directory name
+ * @param {string} dirname - Raw directory name
+ * @returns {string} Sanitized directory name
+ */
+function sanitizeDirname(dirname) {
+    return sanitizeFilename(dirname);
+}
+
+// ─── Permission Checks ───────────────────────────────────────────
+
+/**
+ * Check if we have read access to a path
+ * @param {string} targetPath - Path to check
+ * @returns {boolean} Whether we have read access
+ */
+function canRead(targetPath) {
+    try {
+        fs.accessSync(targetPath, fs.constants.R_OK);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Check if we have write access to a path
+ * @param {string} targetPath - Path to check
+ * @returns {boolean} Whether we have write access
+ */
+function canWrite(targetPath) {
+    try {
+        fs.accessSync(targetPath, fs.constants.W_OK);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Check full operation permissions for a directory
+ * @param {string} dirPath - Directory to check
+ * @returns {{ read: boolean, write: boolean, execute: boolean }}
+ */
+function checkPermissions(dirPath) {
+    const result = { read: false, write: false, execute: false };
+    try { fs.accessSync(dirPath, fs.constants.R_OK); result.read = true; } catch { /* */ }
+    try { fs.accessSync(dirPath, fs.constants.W_OK); result.write = true; } catch { /* */ }
+    try { fs.accessSync(dirPath, fs.constants.X_OK); result.execute = true; } catch { /* */ }
+    return result;
+}
+
+// ─── Rate Limiting (for CLI/server use) ───────────────────────────
+
+class OperationThrottle {
+    constructor(maxOps = 1000, windowMs = 60000) {
+        this.maxOps = maxOps;
+        this.windowMs = windowMs;
+        this.operations = [];
+    }
+
+    canProceed() {
+        const now = Date.now();
+        this.operations = this.operations.filter(t => now - t < this.windowMs);
+        if (this.operations.length >= this.maxOps) {
+            return {
+                allowed: false,
+                retryAfterMs: this.windowMs - (now - this.operations[0]),
+                reason: `Rate limit: max ${this.maxOps} operations per ${this.windowMs / 1000}s`
+            };
+        }
+        this.operations.push(now);
+        return { allowed: true };
+    }
+
+    reset() {
+        this.operations = [];
+    }
+}
+
+// ─── Integrity Verification ───────────────────────────────────────
+
+/**
+ * Create a pre-operation snapshot for rollback verification
+ * @param {string} filePath - File to snapshot
+ * @returns {{ exists: boolean, size?: number, modified?: Date, path: string }}
+ */
+function createSnapshot(filePath) {
+    try {
+        const stat = fs.statSync(filePath);
+        return {
+            exists: true,
+            size: stat.size,
+            modified: stat.mtime,
+            path: path.resolve(filePath)
+        };
+    } catch {
+        return { exists: false, path: path.resolve(filePath) };
+    }
+}
+
+/**
+ * Verify a file matches a previous snapshot
+ * @param {string} filePath - File to verify
+ * @param {Object} snapshot - Previous snapshot
+ * @returns {{ matches: boolean, differences: string[] }}
+ */
+function verifySnapshot(filePath, snapshot) {
+    const differences = [];
+    try {
+        const stat = fs.statSync(filePath);
+        if (!snapshot.exists) {
+            differences.push('File now exists but previously did not');
+        } else {
+            if (stat.size !== snapshot.size) {
+                differences.push(`Size changed: ${snapshot.size} → ${stat.size}`);
+            }
+            if (stat.mtime.getTime() !== snapshot.modified.getTime()) {
+                differences.push('Modification time changed');
+            }
+        }
+    } catch {
+        if (snapshot.exists) {
+            differences.push('File no longer exists');
+        }
+    }
+    return { matches: differences.length === 0, differences };
+}
+
+module.exports = {
+    validatePath,
+    isFileSafe,
+    isDirSafe,
+    sanitizeFilename,
+    sanitizeDirname,
+    canRead,
+    canWrite,
+    checkPermissions,
+    OperationThrottle,
+    createSnapshot,
+    verifySnapshot,
+    PROTECTED_DIRECTORIES,
+    PROTECTED_PREFIXES,
+    DANGEROUS_EXTENSIONS
+};