agentvibes 3.5.9 → 4.0.0

package/src/utils/audio-format-validator.js

@@ -0,0 +1,277 @@
+/**
+ * Audio Format Validator - Magic Number Detection
+ * Story 4.2: Audio Format Detection (Magic Number Validation)
+ *
+ * Validates audio file format by checking file headers (magic numbers).
+ * Supported formats: MP3, WAV, OGG, M4A
+ *
+ * @module audio-format-validator
+ * @requires fs
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Supported audio formats with their magic number signatures
+ */
+const AUDIO_FORMATS = {
+  mp3: {
+    extension: '.mp3',
+    magicNumbers: [
+      // MPEG-1/2/2.5 Audio Frame Header
+      { bytes: Buffer.from([0xFF, 0xFB]), offset: 0, name: 'MP3 MPEG-2 Layer III' },
+      { bytes: Buffer.from([0xFF, 0xFA]), offset: 0, name: 'MP3 MPEG-1 Layer III' },
+      // ID3 Tag (v2.x and v2.4)
+      { bytes: Buffer.from([0x49, 0x44, 0x33]), offset: 0, name: 'ID3v2 Tag' } // "ID3"
+    ]
+  },
+  wav: {
+    extension: '.wav',
+    magicNumbers: [
+      { bytes: Buffer.from('RIFF'), offset: 0, name: 'RIFF Header' },
+      { bytes: Buffer.from('WAVE'), offset: 8, name: 'WAV Format' }
+    ]
+  },
+  ogg: {
+    extension: '.ogg',
+    magicNumbers: [
+      { bytes: Buffer.from('OggS'), offset: 0, name: 'OggS Header' }
+    ]
+  },
+  m4a: {
+    extension: '.m4a',
+    magicNumbers: [
+      { bytes: Buffer.from('ftypisom'), offset: 4, name: 'M4A ISO Base Media' },
+      { bytes: Buffer.from('ftypM4A'), offset: 4, name: 'M4A Apple iTunes' }
+    ]
+  }
+};
+
+const SUPPORTED_EXTENSIONS = Object.values(AUDIO_FORMATS).map(f => f.extension);
+
+/**
+ * Story 4.2: Detect audio format by checking magic numbers in file header
+ *
+ * Reads the first 256 bytes of the file to check magic number signatures.
+ * Does NOT require the file to have the correct extension matching format.
+ *
+ * @param {string} filePath - Path to audio file (must already be validated with isPathSafe)
+ * @returns {Object} { isValid: boolean, error: string|null, format: string|null, detectedFormat: string|null }
+ *
+ * Object properties:
+ * - isValid: true if file is valid audio format
+ * - error: null on success, error message on failure
+ * - format: detected format ('mp3', 'wav', 'ogg', 'm4a') or null
+ * - detectedFormat: human-readable format name (e.g., "MP3 MPEG-1 Layer III")
+ */
+function detectAudioFormat(filePath) {
+  try {
+    if (!filePath || typeof filePath !== 'string') {
+      return {
+        isValid: false,
+        error: 'File path must be a non-empty string',
+        format: null,
+        detectedFormat: null
+      };
+    }
+
+    // Check file exists and is readable
+    if (!fs.existsSync(filePath)) {
+      return {
+        isValid: false,
+        error: 'File does not exist',
+        format: null,
+        detectedFormat: null
+      };
+    }
+
+    const stats = fs.statSync(filePath);
+    if (!stats.isFile()) {
+      return {
+        isValid: false,
+        error: 'Path must be a regular file',
+        format: null,
+        detectedFormat: null
+      };
+    }
+
+    // Check minimum file size (at least 12 bytes for WAV format check)
+    if (stats.size < 12) {
+      return {
+        isValid: false,
+        error: 'File is too small to be a valid audio file (minimum 12 bytes)',
+        format: null,
+        detectedFormat: null
+      };
+    }
+
+    // Read first 256 bytes for magic number detection
+    const buffer = Buffer.alloc(256);
+    const fd = fs.openSync(filePath, 'r');
+    try {
+      fs.readSync(fd, buffer, 0, 256, 0);
+    } finally {
+      fs.closeSync(fd);
+    }
+
+    // Check each format's magic numbers
+    for (const [formatKey, formatInfo] of Object.entries(AUDIO_FORMATS)) {
+      for (const magicInfo of formatInfo.magicNumbers) {
+        // Check if magic bytes exist at the specified offset
+        const isMatch = buffer.subarray(magicInfo.offset, magicInfo.offset + magicInfo.bytes.length)
+          .equals(magicInfo.bytes);
+
+        if (isMatch) {
+          return {
+            isValid: true,
+            error: null,
+            format: formatKey,
+            detectedFormat: magicInfo.name
+          };
+        }
+      }
+    }
+
+    // No magic numbers matched
+    return {
+      isValid: false,
+      error: `Unsupported audio format. Supported formats: ${SUPPORTED_EXTENSIONS.join(', ')}`,
+      format: null,
+      detectedFormat: null
+    };
+
+  } catch (err) {
+    return {
+      isValid: false,
+      error: `Error detecting audio format: ${err.message}`,
+      format: null,
+      detectedFormat: null
+    };
+  }
+}
+
+/**
+ * Story 4.2: Validate that file extension matches detected audio format
+ *
+ * Ensures the file extension is correct for the detected format.
+ * This prevents accidental misnamed files (e.g., .txt file with MP3 content).
+ *
+ * @param {string} filePath - Path to audio file
+ * @param {string} detectedFormat - Format from detectAudioFormat() result
+ * @returns {Object} { isValid: boolean, error: string|null }
+ */
+function validateFileExtension(filePath, detectedFormat) {
+  try {
+    if (!filePath || !detectedFormat) {
+      return {
+        isValid: false,
+        error: 'File path and detected format are required'
+      };
+    }
+
+    const ext = path.extname(filePath).toLowerCase();
+    const expectedExt = AUDIO_FORMATS[detectedFormat]?.extension;
+
+    if (!expectedExt) {
+      return {
+        isValid: false,
+        error: `Unknown detected format: ${detectedFormat}`
+      };
+    }
+
+    if (ext === expectedExt) {
+      return {
+        isValid: true,
+        error: null
+      };
+    }
+
+    // Extension doesn't match - return specific error
+    return {
+      isValid: false,
+      error: `File extension (${ext || 'none'}) doesn't match actual format (.${detectedFormat})`
+    };
+
+  } catch (err) {
+    return {
+      isValid: false,
+      error: `Error validating file extension: ${err.message}`
+    };
+  }
+}
+
+/**
+ * Story 4.2: Comprehensive audio file validation
+ *
+ * Combines format detection and extension validation in one call.
+ * Returns false only if BOTH format is unsupported AND extension is wrong.
+ * Returns true if format is valid (even if extension differs).
+ *
+ * @param {string} filePath - Path to audio file
+ * @param {Object} options - Validation options
+ * @param {boolean} options.strictExtension - If true, reject files with wrong extension (default: false)
+ * @returns {Object} { isValid: boolean, error: string|null, format: string|null, detectedFormat: string|null, extensionMatch: boolean }
+ */
+function validateAudioFile(filePath, options = {}) {
+  const { strictExtension = false } = options;
+
+  try {
+    // Detect format first
+    const formatResult = detectAudioFormat(filePath);
+
+    if (!formatResult.isValid) {
+      return {
+        isValid: false,
+        error: formatResult.error,
+        format: null,
+        detectedFormat: null,
+        extensionMatch: false
+      };
+    }
+
+    // Check extension if strict mode enabled
+    if (strictExtension) {
+      const extResult = validateFileExtension(filePath, formatResult.format);
+      if (!extResult.isValid) {
+        return {
+          isValid: false,
+          error: extResult.error,
+          format: formatResult.format,
+          detectedFormat: formatResult.detectedFormat,
+          extensionMatch: false
+        };
+      }
+    }
+
+    // Format is valid - check if extension matches (informational)
+    const ext = path.extname(filePath).toLowerCase();
+    const expectedExt = AUDIO_FORMATS[formatResult.format]?.extension;
+    const extensionMatch = ext === expectedExt;
+
+    return {
+      isValid: true,
+      error: null,
+      format: formatResult.format,
+      detectedFormat: formatResult.detectedFormat,
+      extensionMatch
+    };
+
+  } catch (err) {
+    return {
+      isValid: false,
+      error: `Unexpected validation error: ${err.message}`,
+      format: null,
+      detectedFormat: null,
+      extensionMatch: false
+    };
+  }
+}
+
+export {
+  detectAudioFormat,
+  validateFileExtension,
+  validateAudioFile,
+  AUDIO_FORMATS,
+  SUPPORTED_EXTENSIONS
+};

package/src/utils/dependency-checker.js

@@ -147,7 +147,7 @@ function buildLinuxPackages(missing) {
   const pacman = [];
 
   const packageMap = {
-    sox: { apt: 'sox', dnf: 'sox', pacman: 'sox' },
+    sox: { apt: 'sox libsox-fmt-mp3', dnf: 'sox', pacman: 'sox' },
     ffmpeg: { apt: 'ffmpeg', dnf: 'ffmpeg', pacman: 'ffmpeg' },
     python: { apt: 'python3-pip', dnf: 'python3-pip', pacman: 'python-pip' },
     pipx: { apt: 'pipx', dnf: 'pipx', pacman: 'python-pipx' },
@@ -368,8 +368,8 @@ function buildCoreMissingList(missing, results) {
 function buildOptionalMissingList(missing) {
   const optionalMap = {
     curl: '• curl (downloading Piper TTS and voices)',
-    sox: '• sox (audio effects)',
-    ffmpeg: '• ffmpeg (background music, RDP optimization)',
+    sox: '• sox (background music mixing, audio effects)',
+    ffmpeg: '• ffmpeg (audio processing, RDP optimization)',
     bc: '• bc (audio processing calculations)',
     pipx: '• pipx (Piper TTS installation)',
     flock: '• flock (TTS queue file locking)',

package/src/utils/file-ownership-verifier.js

@@ -0,0 +1,358 @@
+/**
+ * File Ownership Verifier - Cross-Platform Security Validation
+ * Story 4.3: File Ownership Verification
+ *
+ * Verifies that files are owned by the current user before processing.
+ * This prevents malicious files planted by other users from being used.
+ *
+ * Handles platform-specific differences:
+ * - Unix/Linux/macOS: UID-based ownership checking
+ * - Windows: Uses fs.statSync().uid if available, graceful fallback
+ * - Network mounts: Documented limitation, best-effort checking
+ *
+ * @module file-ownership-verifier
+ * @requires fs
+ * @requires os
+ * @requires path
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/**
+ * Story 4.3: Verify file is owned by current user
+ *
+ * On Unix-like systems (Linux, macOS):
+ * - Compares fs.statSync().uid with process.getuid()
+ *
+ * On Windows:
+ * - Attempts UID comparison if available
+ * - Gracefully falls back to path/permission checks if UID unavailable
+ * - Network mount files may not have reliable ownership info
+ *
+ * Performance: Typically < 5ms (stat operation only, no I/O)
+ *
+ * @param {string} filePath - Path to file to check
+ * @param {Object} options - Verification options
+ * @param {boolean} options.allowNetworkMounts - Allow verification to succeed on network mounts (default: true)
+ * @param {Function} options.logger - Optional logger function for sanitized logs
+ * @returns {Object} {
+ *   isOwned: boolean,
+ *   error: string|null,
+ *   ownerUid: number|null,
+ *   currentUid: number|null,
+ *   isNetworkMount: boolean,
+ *   platform: string
+ * }
+ */
+export function verifyFileOwnership(filePath, options = {}) {
+  const { allowNetworkMounts = true, logger = null } = options;
+
+  try {
+    if (!filePath || typeof filePath !== 'string') {
+      const error = 'File path must be a non-empty string';
+      logger?.(`ownership-check: invalid-path - ${error}`);
+      return {
+        isOwned: false,
+        error,
+        ownerUid: null,
+        currentUid: null,
+        isNetworkMount: false,
+        platform: process.platform
+      };
+    }
+
+    // Check file exists
+    if (!fs.existsSync(filePath)) {
+      const error = 'File does not exist';
+      logger?.(`ownership-check: missing-file - ${filePath}`);
+      return {
+        isOwned: false,
+        error,
+        ownerUid: null,
+        currentUid: null,
+        isNetworkMount: false,
+        platform: process.platform
+      };
+    }
+
+    // Get file stats
+    const stats = fs.statSync(filePath);
+
+    // Check if it's a regular file
+    if (!stats.isFile()) {
+      const error = 'Path must be a regular file';
+      logger?.(`ownership-check: not-file - ${filePath}`);
+      return {
+        isOwned: false,
+        error,
+        ownerUid: null,
+        currentUid: null,
+        isNetworkMount: false,
+        platform: process.platform
+      };
+    }
+
+    const currentUid = process.getuid ? process.getuid() : null;
+    const fileUid = stats.uid;
+
+    // Determine platform type for logging
+    const platformType = getPlatformType();
+    const isNetworkMount = checkIsNetworkMount(filePath);
+
+    // Log verification attempt (sanitized - no sensitive paths)
+    logger?.(`ownership-check: started - platform=${platformType}, network=${isNetworkMount}`);
+
+    // Platform-specific ownership verification
+    if (process.platform === 'win32') {
+      return verifyWindowsOwnership(filePath, stats, currentUid, isNetworkMount, allowNetworkMounts, logger);
+    } else {
+      // Unix-like systems (Linux, macOS)
+      return verifyUnixOwnership(filePath, stats, currentUid, isNetworkMount, allowNetworkMounts, logger);
+    }
+
+  } catch (err) {
+    const error = `Error verifying file ownership: ${err.message}`;
+    logger?.(`ownership-check: error - ${error}`);
+    return {
+      isOwned: false,
+      error,
+      ownerUid: null,
+      currentUid: null,
+      isNetworkMount: false,
+      platform: process.platform
+    };
+  }
+}
+
+/**
+ * Unix/Linux/macOS ownership verification
+ * Uses UID comparison for reliable security
+ *
+ * @private
+ */
+function verifyUnixOwnership(filePath, stats, currentUid, isNetworkMount, allowNetworkMounts, logger) {
+  if (currentUid === null) {
+    const error = 'Unable to determine current user UID (not available on this platform)';
+    logger?.(`ownership-check: no-uid-support`);
+    return {
+      isOwned: false,
+      error,
+      ownerUid: stats.uid,
+      currentUid: null,
+      isNetworkMount,
+      platform: process.platform
+    };
+  }
+
+  // Check if UIDs match
+  if (stats.uid === currentUid) {
+    logger?.(`ownership-check: success - uid=${currentUid}`);
+    return {
+      isOwned: true,
+      error: null,
+      ownerUid: stats.uid,
+      currentUid,
+      isNetworkMount,
+      platform: process.platform
+    };
+  }
+
+  // UIDs don't match - file owned by different user
+  const error = 'File not owned by current user (security check failed)';
+  logger?.(`ownership-check: failed - file-uid=${stats.uid}, user-uid=${currentUid}`);
+  return {
+    isOwned: false,
+    error,
+    ownerUid: stats.uid,
+    currentUid,
+    isNetworkMount,
+    platform: process.platform
+  };
+}
+
+/**
+ * Windows ownership verification
+ * Windows doesn't have traditional UID system, use file permissions
+ *
+ * @private
+ */
+function verifyWindowsOwnership(filePath, stats, currentUid, isNetworkMount, allowNetworkMounts, logger) {
+  // On Windows, process.getuid() is typically undefined
+  // Try to verify through accessible permissions instead
+
+  // If running in WSL (Windows Subsystem for Linux), we have UID available
+  if (currentUid !== null && stats.uid !== undefined) {
+    if (stats.uid === currentUid) {
+      logger?.(`ownership-check: windows-wsl-success - uid=${currentUid}`);
+      return {
+        isOwned: true,
+        error: null,
+        ownerUid: stats.uid,
+        currentUid,
+        isNetworkMount,
+        platform: process.platform
+      };
+    }
+
+    const error = 'File not owned by current user (security check failed)';
+    logger?.(`ownership-check: windows-wsl-failed - file-uid=${stats.uid}, user-uid=${currentUid}`);
+    return {
+      isOwned: false,
+      error,
+      ownerUid: stats.uid,
+      currentUid,
+      isNetworkMount,
+      platform: process.platform
+    };
+  }
+
+  // Native Windows without UID support
+  // Check if file is readable and writable by current user (best effort)
+  try {
+    // Try to read and write to verify we own it
+    fs.accessSync(filePath, fs.constants.R_OK | fs.constants.W_OK);
+
+    // If we can read and write, assume we own it
+    logger?.(`ownership-check: windows-native-success - readable-writable`);
+    return {
+      isOwned: true,
+      error: null,
+      ownerUid: null,
+      currentUid: null,
+      isNetworkMount,
+      platform: process.platform
+    };
+  } catch (err) {
+    // Can't read/write - likely not owned by us or permission issue
+    const error = `File not owned by current user or not accessible (Windows): ${err.message}`;
+    logger?.(`ownership-check: windows-native-failed - ${err.code}`);
+    return {
+      isOwned: false,
+      error,
+      ownerUid: null,
+      currentUid: null,
+      isNetworkMount,
+      platform: process.platform
+    };
+  }
+}
+
+/**
+ * Determine if path is likely a network mount
+ * Used to set expectations for ownership checking reliability
+ *
+ * @private
+ */
+function checkIsNetworkMount(filePath) {
+  const resolvedPath = path.resolve(filePath);
+
+  if (process.platform === 'win32') {
+    // Windows: check for UNC paths (\\server\share) or mapped drives
+    // Also check for paths under %APPDATA% or similar which might be network-synced
+    return resolvedPath.startsWith('\\\\') ||
+           resolvedPath.match(/^[A-Z]:\\[^\\]*\\netshare/i);
+  } else {
+    // Unix: check for common network mount prefixes
+    // /mnt, /media, NFS mount points
+    return resolvedPath.startsWith('/mnt/') ||
+           resolvedPath.startsWith('/media/') ||
+           resolvedPath.includes(':/');  // NFS mount indicators
+  }
+}
+
+/**
+ * Get human-readable platform type
+ *
+ * @private
+ */
+function getPlatformType() {
+  switch (process.platform) {
+    case 'linux':
+      return 'linux';
+    case 'darwin':
+      return 'macos';
+    case 'win32':
+      return 'windows';
+    default:
+      return process.platform;
+  }
+}
+
+/**
+ * Story 4.3: Get current user information for logging/debugging
+ *
+ * Returns user info in a sanitized format safe for logging.
+ * Does NOT include sensitive paths or full usernames.
+ *
+ * @returns {Object} {
+ *   uid: number|null,
+ *   gid: number|null,
+ *   username: string,
+ *   platform: string
+ * }
+ */
+export function getCurrentUserInfo() {
+  try {
+    const uid = process.getuid ? process.getuid() : null;
+    const gid = process.getgid ? process.getgid() : null;
+    const username = os.userInfo().username || 'unknown';
+
+    return {
+      uid,
+      gid,
+      username,
+      platform: getPlatformType()
+    };
+  } catch (err) {
+    return {
+      uid: null,
+      gid: null,
+      username: 'unknown',
+      platform: getPlatformType()
+    };
+  }
+}
+
+/**
+ * Story 4.3: Batch verify ownership of multiple files
+ *
+ * Efficiently checks ownership of multiple files.
+ * Returns detailed results for each file.
+ *
+ * @param {string[]} filePaths - Array of file paths to check
+ * @param {Object} options - Verification options (passed to verifyFileOwnership)
+ * @returns {Object} {
+ *   allOwned: boolean,
+ *   results: Array<{path: string, isOwned: boolean, error: string|null}>
+ * }
+ */
+export function verifyMultipleFiles(filePaths, options = {}) {
+  const results = [];
+  let allOwned = true;
+
+  for (const filePath of filePaths) {
+    const result = verifyFileOwnership(filePath, options);
+    results.push({
+      path: filePath,
+      isOwned: result.isOwned,
+      error: result.error
+    });
+
+    if (!result.isOwned) {
+      allOwned = false;
+    }
+  }
+
+  return {
+    allOwned,
+    results
+  };
+}
+
+export default {
+  verifyFileOwnership,
+  getCurrentUserInfo,
+  verifyMultipleFiles
+};