loukai-app 0.3.0

package/src/main/preload.js

@@ -0,0 +1,252 @@
+const { ipcRenderer } = require('electron');
+
+const api = {
+  app: {
+    getVersion: () => ipcRenderer.invoke('app:getVersion'),
+    getState: () => ipcRenderer.invoke('app:getState'),
+  },
+
+  file: {
+    openKai: () => ipcRenderer.invoke('file:openKai'),
+    loadKaiFromPath: (filePath) => ipcRenderer.invoke('file:loadKaiFromPath', filePath),
+  },
+
+  audio: {
+    getDevices: () => ipcRenderer.invoke('audio:getDevices'),
+    enumerateDevices: () => ipcRenderer.invoke('audio:enumerateDevices'),
+    setDevice: (deviceType, deviceId) =>
+      ipcRenderer.invoke('audio:setDevice', deviceType, deviceId),
+
+    onXRun: (callback) => ipcRenderer.on('audio:xrun', callback),
+    onLatencyUpdate: (callback) => ipcRenderer.on('audio:latency', callback),
+
+    removeXRunListener: (callback) => ipcRenderer.removeListener('audio:xrun', callback),
+    removeLatencyListener: (callback) => ipcRenderer.removeListener('audio:latency', callback),
+  },
+
+  mixer: {
+    setMasterGain: (bus, gainDb) => ipcRenderer.invoke('mixer:setMasterGain', bus, gainDb),
+    toggleMasterMute: (bus) => ipcRenderer.invoke('mixer:toggleMasterMute', bus),
+    toggleMute: (stemId, bus) => ipcRenderer.invoke('mixer:toggleMute', stemId, bus),
+
+    onStateChange: (callback) => ipcRenderer.on('mixer:state', callback),
+    removeStateListener: (callback) => ipcRenderer.removeListener('mixer:state', callback),
+
+    // Listen for commands from main process (for web admin)
+    onSetMasterGain: (callback) => ipcRenderer.on('mixer:setMasterGain', callback),
+    onToggleMasterMute: (callback) => ipcRenderer.on('mixer:toggleMasterMute', callback),
+    onSetMasterMute: (callback) => ipcRenderer.on('mixer:setMasterMute', callback),
+  },
+
+  player: {
+    play: () => ipcRenderer.invoke('player:play'),
+    pause: () => ipcRenderer.invoke('player:pause'),
+    seek: (positionSec) => ipcRenderer.invoke('player:seek', positionSec),
+    restart: () => ipcRenderer.invoke('player:restart'),
+    next: () => ipcRenderer.invoke('player:next'),
+
+    onPlaybackState: (callback) => ipcRenderer.on('playback:state', callback),
+    removePlaybackListener: (callback) => ipcRenderer.removeListener('playback:state', callback),
+
+    // Events from main process for playback control
+    onTogglePlayback: (callback) => ipcRenderer.on('player:togglePlayback', callback),
+    onRestart: (callback) => ipcRenderer.on('player:restart', callback),
+    onSetPosition: (callback) => ipcRenderer.on('player:setPosition', callback),
+    removeTogglePlaybackListener: (callback) =>
+      ipcRenderer.removeListener('player:togglePlayback', callback),
+    removeRestartListener: (callback) => ipcRenderer.removeListener('player:restart', callback),
+    removeSetPositionListener: (callback) =>
+      ipcRenderer.removeListener('player:setPosition', callback),
+  },
+
+  autotune: {
+    setEnabled: (enabled) => ipcRenderer.invoke('autotune:setEnabled', enabled),
+    setSettings: (settings) => ipcRenderer.invoke('autotune:setSettings', settings),
+  },
+
+  song: {
+    onLoaded: (callback) => ipcRenderer.on('song:loaded', callback),
+    onData: (callback) => ipcRenderer.on('song:data', callback),
+    onChanged: (callback) => ipcRenderer.on('song:changed', callback),
+    removeSongListener: (callback) => ipcRenderer.removeListener('song:loaded', callback),
+    removeDataListener: (callback) => ipcRenderer.removeListener('song:data', callback),
+    removeChangedListener: (callback) => ipcRenderer.removeListener('song:changed', callback),
+    getCurrentSong: () => ipcRenderer.invoke('song:getCurrentSong'),
+  },
+
+  editor: {
+    loadKai: (filePath) => ipcRenderer.invoke('editor:loadKai', filePath),
+    saveKai: (kaiData, originalPath) => ipcRenderer.invoke('editor:saveKai', kaiData, originalPath),
+    reloadKai: (filePath) => ipcRenderer.invoke('editor:reloadKai', filePath),
+  },
+
+  window: {
+    openCanvas: () => ipcRenderer.invoke('window:openCanvas'),
+  },
+
+  canvas: {
+    startStreaming: () => ipcRenderer.invoke('canvas:startStreaming'),
+    stopStreaming: () => ipcRenderer.invoke('canvas:stopStreaming'),
+    sendImageData: (imageDataArray, width, height) =>
+      ipcRenderer.invoke('canvas:sendImageData', imageDataArray, width, height),
+    sendICECandidate: (source, candidate) =>
+      ipcRenderer.invoke('canvas:sendICECandidate', source, candidate),
+    toggleFullscreen: (shouldBeFullscreen) =>
+      ipcRenderer.invoke('canvas:toggleFullscreen', shouldBeFullscreen),
+    sendFrame: (dataUrl) => ipcRenderer.invoke('canvas:sendFrame', dataUrl),
+  },
+
+  library: {
+    getSongsFolder: () => ipcRenderer.invoke('library:getSongsFolder'),
+    setSongsFolder: () => ipcRenderer.invoke('library:setSongsFolder'),
+    scanFolder: () => ipcRenderer.invoke('library:scanFolder'),
+    syncLibrary: () => ipcRenderer.invoke('library:syncLibrary'),
+    getCachedSongs: () => ipcRenderer.invoke('library:getCachedSongs'),
+    getSongInfo: (filePath) => ipcRenderer.invoke('library:getSongInfo', filePath),
+    search: (query) => ipcRenderer.invoke('library:search', query),
+
+    onFolderSet: (callback) => ipcRenderer.on('library:folderSet', callback),
+    removeFolderSetListener: (callback) =>
+      ipcRenderer.removeListener('library:folderSet', callback),
+  },
+
+  webServer: {
+    getPort: () => ipcRenderer.invoke('webServer:getPort'),
+    getUrl: () => ipcRenderer.invoke('webServer:getUrl'),
+    getSettings: () => ipcRenderer.invoke('webServer:getSettings'),
+    updateSettings: (settings) => ipcRenderer.invoke('webServer:updateSettings', settings),
+    getSongRequests: () => ipcRenderer.invoke('webServer:getSongRequests'),
+    approveRequest: (requestId) => ipcRenderer.invoke('webServer:approveRequest', requestId),
+    rejectRequest: (requestId) => ipcRenderer.invoke('webServer:rejectRequest', requestId),
+    refreshCache: () => ipcRenderer.invoke('webServer:refreshCache'),
+    setAdminPassword: (password) => ipcRenderer.invoke('webServer:setAdminPassword', password),
+    clearAllRequests: () => ipcRenderer.invoke('webServer:clearAllRequests'),
+  },
+
+  settings: {
+    get: (key, defaultValue) => ipcRenderer.invoke('settings:get', key, defaultValue),
+    set: (key, value) => ipcRenderer.invoke('settings:set', key, value),
+    getAll: () => ipcRenderer.invoke('settings:getAll'),
+    updateBatch: (updates) => ipcRenderer.invoke('settings:updateBatch', updates),
+    onUpdate: (callback) => ipcRenderer.on('settings:update', callback),
+    removeUpdateListener: (callback) => ipcRenderer.removeListener('settings:update', callback),
+  },
+
+  queue: {
+    addSong: (queueItem) => ipcRenderer.invoke('queue:addSong', queueItem),
+    removeSong: (itemId) => ipcRenderer.invoke('queue:removeSong', itemId),
+    get: () => ipcRenderer.invoke('queue:get'),
+    clear: () => ipcRenderer.invoke('queue:clear'),
+    load: (itemId) => ipcRenderer.invoke('queue:load', itemId),
+    reorderQueue: (songId, newIndex) => ipcRenderer.invoke('queue:reorderQueue', songId, newIndex),
+
+    onUpdated: (callback) => ipcRenderer.on('queue:updated', callback),
+    removeUpdatedListener: (callback) => ipcRenderer.removeListener('queue:updated', callback),
+  },
+
+  effect: {
+    onNext: (callback) => ipcRenderer.on('effect:next', callback),
+    onPrevious: (callback) => ipcRenderer.on('effect:previous', callback),
+    removeNextListener: (callback) => ipcRenderer.removeListener('effect:next', callback),
+    removePreviousListener: (callback) => ipcRenderer.removeListener('effect:previous', callback),
+  },
+
+  effects: {
+    getList: () => ipcRenderer.invoke('effects:getList'),
+    select: (effectName) => ipcRenderer.invoke('effects:select', effectName),
+    toggle: (effectName, enabled) => ipcRenderer.invoke('effects:toggle', effectName, enabled),
+    next: () => ipcRenderer.invoke('effects:next'),
+    previous: () => ipcRenderer.invoke('effects:previous'),
+    random: () => ipcRenderer.invoke('effects:random'),
+
+    onChanged: (callback) => ipcRenderer.on('effects:changed', callback),
+    removeChangedListener: (callback) => ipcRenderer.removeListener('effects:changed', callback),
+  },
+
+  preferences: {
+    setAutoTune: (prefs) => ipcRenderer.invoke('preferences:setAutoTune', prefs),
+    setMicrophone: (prefs) => ipcRenderer.invoke('preferences:setMicrophone', prefs),
+    setEffects: (prefs) => ipcRenderer.invoke('preferences:setEffects', prefs),
+
+    onUpdated: (callback) => ipcRenderer.on('preferences:updated', callback),
+    removeUpdatedListener: (callback) =>
+      ipcRenderer.removeListener('preferences:updated', callback),
+  },
+
+  // admin.onPlay/onNext/onRestart removed - web admin calls window.app methods directly via executeJavaScript
+
+  renderer: {
+    sendPlaybackState: (state) => ipcRenderer.send('renderer:playbackState', state),
+    updatePlaybackState: (updates) => ipcRenderer.send('renderer:updatePlaybackState', updates),
+    songLoaded: (songData) => ipcRenderer.send('renderer:songLoaded', songData),
+    updateMixerState: (mixerState) => ipcRenderer.send('renderer:updateMixerState', mixerState),
+    updateEffectsState: (effectsState) =>
+      ipcRenderer.send('renderer:updateEffectsState', effectsState),
+    sendEffectsList: (effects) => ipcRenderer.send('effects:getList-response', effects),
+    sendCurrentEffect: (effectName) => ipcRenderer.send('effects:getCurrent-response', effectName),
+    sendDisabledEffects: (disabled) => ipcRenderer.send('effects:getDisabled-response', disabled),
+    sendWebRTCResponse: (command, result) => {
+      // SECURITY FIX (#24): Whitelist allowed WebRTC commands to prevent IPC channel injection
+      const ALLOWED_COMMANDS = [
+        'setupReceiver',
+        'checkReceiverReady',
+        'setOfferAndCreateAnswer',
+        'getReceiverStatus',
+      ];
+      if (!ALLOWED_COMMANDS.includes(command)) {
+        console.warn('Blocked invalid WebRTC command:', command);
+        return;
+      }
+      ipcRenderer.send(`webrtc:${command}-response`, result);
+    },
+  },
+
+  events: {
+    on: (channel, callback) => ipcRenderer.on(channel, callback),
+    removeListener: (channel, callback) => ipcRenderer.removeListener(channel, callback),
+  },
+
+  shell: {
+    openExternal: (url) => ipcRenderer.invoke('shell:openExternal', url),
+  },
+
+  creator: {
+    checkComponents: () => ipcRenderer.invoke('creator:checkComponents'),
+    installComponents: () => ipcRenderer.invoke('creator:installComponents'),
+    getStatus: () => ipcRenderer.invoke('creator:getStatus'),
+    cancelInstall: () => ipcRenderer.invoke('creator:cancelInstall'),
+    searchLyrics: (title, artist) => ipcRenderer.invoke('creator:searchLyrics', title, artist),
+    prepareWhisperContext: (title, artist, existingLyrics) =>
+      ipcRenderer.invoke('creator:prepareWhisperContext', title, artist, existingLyrics),
+    selectFile: () => ipcRenderer.invoke('creator:selectFile'),
+    startConversion: (options) => ipcRenderer.invoke('creator:startConversion', options),
+    cancelConversion: () => ipcRenderer.invoke('creator:cancelConversion'),
+
+    // LLM settings
+    getLLMSettings: () => ipcRenderer.invoke('creator:getLLMSettings'),
+    saveLLMSettings: (settings) => ipcRenderer.invoke('creator:saveLLMSettings', settings),
+    testLLMConnection: (settings) => ipcRenderer.invoke('creator:testLLMConnection', settings),
+
+    onInstallProgress: (callback) => ipcRenderer.on('creator:installProgress', callback),
+    onInstallError: (callback) => ipcRenderer.on('creator:installError', callback),
+    onConversionProgress: (callback) => ipcRenderer.on('creator:conversionProgress', callback),
+    onConversionConsole: (callback) => ipcRenderer.on('creator:conversionConsole', callback),
+    onConversionComplete: (callback) => ipcRenderer.on('creator:conversionComplete', callback),
+    onConversionError: (callback) => ipcRenderer.on('creator:conversionError', callback),
+    removeInstallProgressListener: (callback) =>
+      ipcRenderer.removeListener('creator:installProgress', callback),
+    removeInstallErrorListener: (callback) =>
+      ipcRenderer.removeListener('creator:installError', callback),
+    removeConversionProgressListener: (callback) =>
+      ipcRenderer.removeListener('creator:conversionProgress', callback),
+    removeConversionConsoleListener: (callback) =>
+      ipcRenderer.removeListener('creator:conversionConsole', callback),
+    removeConversionCompleteListener: (callback) =>
+      ipcRenderer.removeListener('creator:conversionComplete', callback),
+    removeConversionErrorListener: (callback) =>
+      ipcRenderer.removeListener('creator:conversionError', callback),
+  },
+};
+
+// Since contextIsolation is disabled, directly assign to window
+window.kaiAPI = api;

package/src/main/settingsManager.js

@@ -0,0 +1,139 @@
+import { app } from 'electron';
+import path from 'path';
+import fs from 'fs/promises';
+import { ALL_DEFAULTS, mergeWithDefaults } from '../shared/defaults.js';
+
+class SettingsManager {
+  constructor() {
+    this.settingsPath = path.join(app.getPath('userData'), 'settings.json');
+    this.settings = null;
+    this.saveTimeout = null;
+    this.isDirty = false;
+  }
+
+  async load() {
+    try {
+      const data = await fs.readFile(this.settingsPath, 'utf8');
+      this.settings = JSON.parse(data);
+    } catch {
+      // Try to restore from backup if main file is corrupted
+      const backupPath = this.settingsPath + '.backup';
+      try {
+        const backupData = await fs.readFile(backupPath, 'utf8');
+        this.settings = JSON.parse(backupData);
+
+        // Save the restored settings back to main file
+        await this.save();
+      } catch {
+        // Backup also failed or doesn't exist, use defaults
+        this.settings = { ...ALL_DEFAULTS };
+      }
+    }
+    return this.settings;
+  }
+
+  /**
+   * Get all settings merged with defaults
+   */
+  getAll() {
+    if (!this.settings) {
+      return { ...ALL_DEFAULTS };
+    }
+    return mergeWithDefaults(this.settings);
+  }
+
+  async save() {
+    if (!this.isDirty) {
+      return; // No changes since last save
+    }
+
+    try {
+      // Validate that settings can be serialized to JSON
+      const jsonString = JSON.stringify(this.settings, null, 2);
+
+      // Validate that it can be parsed back (catch any JSON issues)
+      JSON.parse(jsonString);
+
+      // Create backup of existing file before overwriting
+      const backupPath = this.settingsPath + '.backup';
+      try {
+        await fs.copyFile(this.settingsPath, backupPath);
+      } catch (backupError) {
+        // File might not exist yet, that's okay
+        if (backupError.code !== 'ENOENT') {
+          console.warn('⚠️ Could not create settings backup:', backupError.message);
+        }
+      }
+
+      // Write directly
+      await fs.writeFile(this.settingsPath, jsonString, 'utf8');
+
+      this.isDirty = false;
+    } catch (error) {
+      console.error('❌ Failed to save settings:', error);
+      throw error; // Propagate error so caller knows save failed
+    }
+  }
+
+  get(key, defaultValue = undefined) {
+    if (!this.settings) {
+      throw new Error('Settings not loaded. Call load() first.');
+    }
+
+    // Check if key exists in saved settings
+    if (this.settings[key] !== undefined) {
+      return this.settings[key];
+    }
+
+    // Fall back to provided default, then ALL_DEFAULTS
+    if (defaultValue !== undefined) {
+      return defaultValue;
+    }
+
+    // Check ALL_DEFAULTS for this key
+    if (key in ALL_DEFAULTS) {
+      return ALL_DEFAULTS[key];
+    }
+
+    return null;
+  }
+
+  set(key, value) {
+    if (!this.settings) {
+      throw new Error('Settings not loaded. Call load() first.');
+    }
+    this.settings[key] = value;
+    this.isDirty = true;
+
+    // Debounce saves - wait 1 second after last change before saving
+    if (this.saveTimeout) {
+      clearTimeout(this.saveTimeout);
+    }
+    this.saveTimeout = setTimeout(() => {
+      this.save();
+    }, 1000);
+  }
+
+  /**
+   * Force immediate save (used on app quit)
+   */
+  async saveNow() {
+    if (this.saveTimeout) {
+      clearTimeout(this.saveTimeout);
+      this.saveTimeout = null;
+    }
+    if (this.isDirty) {
+      await this.save();
+    }
+  }
+
+  getSongsFolder() {
+    return this.get('songsFolder');
+  }
+
+  setSongsFolder(folderPath) {
+    this.set('songsFolder', folderPath);
+  }
+}
+
+export default SettingsManager;

package/src/main/statePersistence.js

@@ -0,0 +1,193 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { app } from 'electron';
+
+/**
+ * StatePersistence - Saves and loads AppState to/from disk
+ */
+class StatePersistence {
+  constructor(appState) {
+    this.appState = appState;
+    this.stateFile = path.join(app.getPath('userData'), 'app-state.json');
+    this.saveInterval = null;
+    this.isDirty = false;
+
+    // Mark state as dirty when it changes (don't track playback/queue - those are ephemeral)
+    this.appState.on('mixerChanged', () => {
+      this.isDirty = true;
+    });
+    this.appState.on('effectsChanged', () => {
+      this.isDirty = true;
+    });
+    this.appState.on('preferencesChanged', () => {
+      this.isDirty = true;
+    });
+  }
+
+  /**
+   * Load state from disk on startup
+   */
+  async load() {
+    try {
+      const data = await fs.readFile(this.stateFile, 'utf-8');
+      const savedState = JSON.parse(data);
+
+      // Don't restore queue - it should start empty each time
+      // Queue is ephemeral, only mixer/effects/preferences persist
+
+      // Restore mixer state if available
+      if (savedState.mixer) {
+        this.appState.state.mixer = savedState.mixer;
+        console.log('📂 Loaded mixer state');
+      }
+
+      // Restore effects state if available
+      if (savedState.effects) {
+        this.appState.state.effects = savedState.effects;
+        console.log('📂 Loaded effects state');
+      }
+
+      // Restore preferences if available
+      if (savedState.preferences) {
+        this.appState.state.preferences = {
+          ...this.appState.state.preferences,
+          ...savedState.preferences,
+        };
+        console.log('📂 Loaded preferences');
+      }
+
+      console.log('✅ State loaded from disk');
+      return true;
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        console.log('ℹ️ No saved state found (first run)');
+        return false;
+      }
+
+      // Try to restore from backup if main file is corrupted
+      const backupPath = this.stateFile + '.backup';
+      try {
+        console.warn('⚠️ State file corrupted, attempting backup restore...');
+        const backupData = await fs.readFile(backupPath, 'utf-8');
+        const savedState = JSON.parse(backupData);
+
+        // Restore from backup
+        if (savedState.mixer) {
+          this.appState.state.mixer = savedState.mixer;
+          console.log('📂 Loaded mixer state from backup');
+        }
+
+        if (savedState.effects) {
+          this.appState.state.effects = savedState.effects;
+          console.log('📂 Loaded effects state from backup');
+        }
+
+        if (savedState.preferences) {
+          this.appState.state.preferences = {
+            ...this.appState.state.preferences,
+            ...savedState.preferences,
+          };
+          console.log('📂 Loaded preferences from backup');
+        }
+
+        console.log('✅ State restored from backup');
+
+        // Mark as dirty to save the restored state
+        this.isDirty = true;
+        await this.save();
+
+        return true;
+      } catch (backupError) {
+        console.error('❌ Failed to load state from backup:', backupError);
+        return false;
+      }
+    }
+  }
+
+  /**
+   * Save state to disk
+   */
+  async save() {
+    if (!this.isDirty) {
+      return; // No changes since last save
+    }
+
+    try {
+      const snapshot = this.appState.getSnapshot();
+
+      // Don't save playback state (position, isPlaying) or queue - those are ephemeral
+      const stateToSave = {
+        mixer: snapshot.mixer,
+        effects: snapshot.effects,
+        preferences: snapshot.preferences,
+        savedAt: new Date().toISOString(),
+      };
+
+      // Validate that state can be serialized to JSON
+      const jsonString = JSON.stringify(stateToSave, null, 2);
+
+      // Validate that it can be parsed back (catch any JSON issues)
+      JSON.parse(jsonString);
+
+      // Create backup of existing file before overwriting
+      const backupPath = this.stateFile + '.backup';
+      try {
+        await fs.copyFile(this.stateFile, backupPath);
+      } catch (backupError) {
+        // File might not exist yet, that's okay
+        if (backupError.code !== 'ENOENT') {
+          console.warn('⚠️ Could not create state backup:', backupError.message);
+        }
+      }
+
+      // Write to temp file first, then rename (atomic operation)
+      const tempPath = this.stateFile + '.tmp';
+      await fs.writeFile(tempPath, jsonString, 'utf-8');
+      await fs.rename(tempPath, this.stateFile);
+
+      this.isDirty = false;
+      console.log('💾 State saved to disk');
+    } catch (error) {
+      console.error('❌ Failed to save state:', error);
+      throw error; // Propagate error so caller knows save failed
+    }
+  }
+
+  /**
+   * Start periodic saving (every 30 seconds if dirty)
+   */
+  startPeriodicSave() {
+    if (this.saveInterval) {
+      clearInterval(this.saveInterval);
+    }
+
+    this.saveInterval = setInterval(async () => {
+      if (this.isDirty) {
+        await this.save();
+      }
+    }, 30000); // 30 seconds
+
+    console.log('⏰ Started periodic state persistence (30s interval)');
+  }
+
+  /**
+   * Stop periodic saving
+   */
+  stopPeriodicSave() {
+    if (this.saveInterval) {
+      clearInterval(this.saveInterval);
+      this.saveInterval = null;
+      console.log('⏸️ Stopped periodic state persistence');
+    }
+  }
+
+  /**
+   * Save and cleanup
+   */
+  async cleanup() {
+    this.stopPeriodicSave();
+    await this.save(); // Final save
+  }
+}
+
+export default StatePersistence;

package/src/main/utils/pathValidator.js

@@ -0,0 +1,112 @@
+/**
+ * Path Validation Utility
+ * Prevents path traversal attacks by validating paths against allowed directories
+ */
+
+import path from 'path';
+import fs from 'fs';
+
+/**
+ * Validates that a file path is within the allowed songs directory
+ * @param {string} filePath - The path to validate
+ * @param {string} songsFolder - The allowed songs directory
+ * @returns {{ valid: boolean, resolvedPath?: string, error?: string }}
+ */
+export function validateSongPath(filePath, songsFolder) {
+  // Check for empty/null inputs
+  if (!filePath || typeof filePath !== 'string') {
+    return { valid: false, error: 'File path is required' };
+  }
+
+  if (!songsFolder || typeof songsFolder !== 'string') {
+    return { valid: false, error: 'Songs folder not configured' };
+  }
+
+  // Normalize and resolve both paths to absolute paths
+  const resolvedSongsFolder = path.resolve(songsFolder);
+  const resolvedFilePath = path.resolve(songsFolder, filePath);
+
+  // Check if the resolved path starts with the songs folder
+  // This prevents ../../../etc/passwd style attacks
+  if (!resolvedFilePath.startsWith(resolvedSongsFolder + path.sep) && 
+      resolvedFilePath !== resolvedSongsFolder) {
+    return { 
+      valid: false, 
+      error: 'Access denied: path is outside songs directory' 
+    };
+  }
+
+  // Additional check: if the path was absolute, verify it's within songs folder
+  if (path.isAbsolute(filePath)) {
+    const resolvedAbsolute = path.resolve(filePath);
+    if (!resolvedAbsolute.startsWith(resolvedSongsFolder + path.sep) &&
+        resolvedAbsolute !== resolvedSongsFolder) {
+      return { 
+        valid: false, 
+        error: 'Access denied: absolute path is outside songs directory' 
+      };
+    }
+    // Use the absolute path as-is if it's valid
+    return { valid: true, resolvedPath: resolvedAbsolute };
+  }
+
+  return { valid: true, resolvedPath: resolvedFilePath };
+}
+
+/**
+ * Validates a base64-encoded path (used in editor audio endpoints)
+ * @param {string} encodedPath - The base64url encoded path
+ * @param {string} songsFolder - The allowed songs directory
+ * @returns {{ valid: boolean, decodedPath?: string, error?: string }}
+ */
+export function validateBase64Path(encodedPath, songsFolder) {
+  if (!encodedPath || typeof encodedPath !== 'string') {
+    return { valid: false, error: 'Encoded path is required' };
+  }
+
+  try {
+    const decoded = Buffer.from(encodedPath, 'base64url').toString('utf8');
+    
+    // The decoded format is "path:filename" or "path:trackName:trackIndex"
+    const parts = decoded.split(':');
+    if (parts.length < 2) {
+      return { valid: false, error: 'Invalid encoded path format' };
+    }
+
+    const filePath = parts[0];
+    
+    // Validate the file path portion
+    const validation = validateSongPath(filePath, songsFolder);
+    if (!validation.valid) {
+      return validation;
+    }
+
+    return { 
+      valid: true, 
+      decodedPath: decoded,
+      resolvedPath: validation.resolvedPath 
+    };
+  } catch (error) {
+    return { valid: false, error: 'Invalid base64 encoding' };
+  }
+}
+
+/**
+ * Check if a path exists and is a file
+ * @param {string} filePath - The path to check
+ * @returns {boolean}
+ */
+export function isValidFile(filePath) {
+  try {
+    const stats = fs.statSync(filePath);
+    return stats.isFile();
+  } catch {
+    return false;
+  }
+}
+
+export default {
+  validateSongPath,
+  validateBase64Path,
+  isValidFile
+};