Electron Skills

Electron Skills for LlamaFarm Desktop

Electron 28 + Electron Vite patterns for the LlamaFarm Desktop application.

Overview

This skill extends typescript-skills with Electron-specific patterns for main/renderer process architecture, IPC communication, security, and performance.

Tech Stack

Architecture

electron-app/
  src/
    main/           # Main process (Node.js context)
      index.ts      # App entry, lifecycle, IPC handlers
      backend/      # CLI installer, model downloader
      window-manager.ts
      menu-manager.ts
      logger.ts
    preload/        # Preload scripts (bridge context)
      index.ts      # contextBridge API exposure
    renderer/       # Renderer process (browser context)
      index.html    # Main window
      splash.html   # Splash screen

Core Principles

1. Process isolation - Main, preload, and renderer are separate contexts 2. Context isolation - Always use contextBridge.exposeInMainWorld 3. No Node in renderer - nodeIntegration: false always 4. Type-safe IPC - Define channel types and payload schemas 5. Secure by default - Minimize exposed APIs in preload

Related Documents

• electron.md - IPC patterns, main/renderer communication
• security.md - Context isolation, preload security, CSP
• performance.md - Window management, memory, startup

Shared TypeScript Patterns

This skill inherits from typescript-skills:

• patterns.md - Idiomatic TypeScript
• typing.md - Strict typing, generics
• security.md - Input validation, XSS prevention

Quick Reference

IPC Handler Pattern (Main Process)

ipcMain.handle('cli:info', async () => {
  const isInstalled = await this.cliInstaller.isInstalled()
  return {
    isInstalled,
    path: isInstalled ? this.cliInstaller.getCLIPath() : null
  }
})

Preload Bridge Pattern

const api = {
  cli: {
    getInfo: () => ipcRenderer.invoke('cli:info')
  },
  platform: process.platform,
  version: process.versions.electron
}

contextBridge.exposeInMainWorld('llamafarm', api)

BrowserWindow Configuration

new BrowserWindow({
  webPreferences: {
    preload: path.join(__dirname, '../preload/index.js'),
    nodeIntegration: false,
    contextIsolation: true
  }
})

Checklist Summary

Electron IPC and Process Patterns

Main/renderer process communication and Electron architecture patterns.

Process Model

Electron has three process types with different capabilities:

IPC Communication

Handle/Invoke Pattern (Request/Response)

Main process handler:

import { ipcMain } from 'electron'

// Define typed response
interface CLIInfo {
  isInstalled: boolean
  path: string | null
}

// Register handler
ipcMain.handle('cli:info', async (): Promise<CLIInfo> => {
  const isInstalled = await this.cliInstaller.isInstalled()
  return {
    isInstalled,
    path: isInstalled ? this.cliInstaller.getCLIPath() : null
  }
})

Preload bridge:

import { contextBridge, ipcRenderer } from 'electron'

const api = {
  cli: {
    getInfo: (): Promise<CLIInfo> => ipcRenderer.invoke('cli:info')
  }
}

contextBridge.exposeInMainWorld('llamafarm', api)

Renderer usage:

// Type declaration for exposed API
declare global {
  interface Window {
    llamafarm: {
      cli: {
        getInfo: () => Promise<CLIInfo>
      }
    }
  }
}

// Use the API
const info = await window.llamafarm.getInfo()

Send/On Pattern (One-way Events)

Main to renderer:

// Main process sends
mainWindow.webContents.send('splash-status', {
  message: 'Loading...',
  progress: 50
})

// Preload exposes listener
const api = {
  splash: {
    onStatus: (callback: (status: SplashStatus) => void) => {
      const listener = (_event: IpcRendererEvent, status: SplashStatus) => {
        callback(status)
      }
      ipcRenderer.on('splash-status', listener)
      // Return cleanup function
      return () => ipcRenderer.removeListener('splash-status', listener)
    }
  }
}

Channel Naming Convention

Use namespaced channel names with colons for request-response (handle/invoke) and hyphens for one-way events (send/on):

// Pattern: domain:action (for handle/invoke - request-response)
'cli:info'           // Get CLI information
'cli:install'        // Install CLI
'backend:status'     // Backend status check (invoke)
'backend:restart'    // Restart backend (invoke)

// Pattern: domain-event (for send/on - one-way from main to renderer)
'splash-status'      // Splash screen updates
'backend-status'     // Backend status broadcasts

Note: The colon vs hyphen distinction helps developers quickly identify communication patterns in the codebase.

Window Management

Creating Windows

import { BrowserWindow, screen } from 'electron'

createMainWindow(): BrowserWindow {
  const { width, height } = screen.getPrimaryDisplay().workAreaSize

  const mainWindow = new BrowserWindow({
    width: Math.min(1400, width),
    height: Math.min(900, height),
    show: false, // Don't show until ready
    webPreferences: {
      preload: path.join(__dirname, '../preload/index.js'),
      nodeIntegration: false,
      contextIsolation: true
    },
    titleBarStyle: 'hidden', // Custom title bar
    trafficLightPosition: { x: 20, y: 18 }, // macOS traffic lights
    backgroundColor: '#1a1f2e'
  })

  mainWindow.once('ready-to-show', () => {
    mainWindow.show()
  })

  return mainWindow
}

Splash Screen Pattern

createSplashWindow(): BrowserWindow {
  const splash = new BrowserWindow({
    width: 500,
    height: 400,
    frame: false,
    transparent: true,
    resizable: false,
    alwaysOnTop: false,
    movable: true,
    webPreferences: {
      preload: path.join(__dirname, '../preload/index.js'),
      nodeIntegration: false,
      contextIsolation: true
    }
  })

  // Load embedded HTML or file
  splash.loadURL(`data:text/html;charset=utf-8,${encodeURIComponent(splashHTML)}`)
  splash.center()
  splash.show()

  return splash
}

App Lifecycle

Startup Sequence

class ElectronApp {
  constructor() {
    this.setupEventHandlers()
    this.setupIPCHandlers()
  }

  private setupEventHandlers(): void {
    app.on('ready', () => this.onReady())
    app.on('window-all-closed', () => this.onWindowsClosed())
    app.on('activate', () => this.onActivate()) // macOS dock click
    app.on('before-quit', () => this.onBeforeQuit())
    app.on('will-quit', (event) => this.onWillQuit(event))
  }

  private async onReady(): Promise<void> {
    // 1. Create splash screen
    const splash = this.createSplashWindow()

    try {
      // 2. Initialize services
      await this.initializeServices()

      // 3. Create main window
      this.createMainWindow()
    } catch (error) {
      this.handleStartupError(error)
    }
  }
}

Graceful Shutdown

private async onWillQuit(event: Electron.Event): Promise<void> {
  event.preventDefault()

  try {
    // Stop background services
    await execAsync(`"${this.cliPath}" services stop`, { timeout: 30000 })

    // Cleanup windows
    this.windowManager.cleanup()

    // Close logger
    await logger.close()

    app.exit(0)
  } catch (error) {
    console.error('Shutdown error:', error)
    app.exit(1)
  }
}

External Process Management

Spawning CLI Commands

import { exec } from 'child_process'
import { promisify } from 'util'

const execAsync = promisify(exec)

async startServices(): Promise<void> {
  const timeout = 600000 // 10 minutes for first-time setup

  const { stdout, stderr } = await execAsync(
    `"${this.cliPath}" services start`,
    { timeout }
  )

  console.log('Services output:', stdout)
  if (stderr) console.warn('Services stderr:', stderr)
}

Retry Logic for External Services

async waitForServer(): Promise<void> {
  const maxAttempts = 120
  let attempts = 0
  let delay = 500
  const maxDelay = 2000

  while (attempts < maxAttempts) {
    try {
      const response = await axios.get('http://127.0.0.1:14345/health', {
        timeout: 3000
      })
      if (response.status === 200) return
    } catch {
      // Server not ready yet
    }

    await new Promise(resolve => setTimeout(resolve, delay))
    delay = Math.min(delay * 1.1, maxDelay) // Exponential backoff
    attempts++
  }

  throw new Error(`Server failed to respond after ${maxAttempts} attempts`)
}

---

Checklist

IPC-001: Use handle/invoke for request-response

• Description: Use ipcMain.handle with ipcRenderer.invoke for async operations
• Search: grep -r "ipcMain.on\|ipcRenderer.send" electron-app/src/
• Pass: Request-response uses handle/invoke pattern
• Fail: Using on/send for request-response
• Severity: High
• Fix: Replace with ipcMain.handle and ipcRenderer.invoke

IPC-002: Type IPC channel payloads

• Description: Define TypeScript interfaces for all IPC payloads
• Search: grep -r "ipcMain.handle\|ipcRenderer.invoke" electron-app/src/
• Pass: All handlers have typed parameters and return types
• Fail: Using any or untyped payloads
• Severity: High
• Fix: Define interfaces for each channel's request/response

IPC-003: Return cleanup functions from listeners

• Description: Preload event listeners must return cleanup functions
• Search: grep -r "ipcRenderer.on" electron-app/src/preload/
• Pass: All listeners return removeListener function
• Fail: No cleanup mechanism for event subscriptions
• Severity: Medium
• Fix: Return () => ipcRenderer.removeListener(channel, listener)

IPC-004: Namespace channel names

• Description: IPC channels should use domain:action naming
• Search: grep -rE "ipc(Main|Renderer)\.(handle|invoke|on|send)\(" electron-app/src/
• Pass: All channels follow namespace:action pattern
• Fail: Generic or unclear channel names
• Severity: Low
• Fix: Rename to pattern like 'cli:info', 'backend:status'

IPC-005: Hide window until ready

• Description: Windows should not show until content is loaded
• Search: grep -r "new BrowserWindow" electron-app/src/
• Pass: show: false with ready-to-show listener
• Fail: Window visible during load
• Severity: Medium
• Fix: Set show: false, add once('ready-to-show', () => show())

IPC-006: Quote executable paths

• Description: External command paths must be quoted for spaces
• Search: grep -r "execAsync\|exec(" electron-app/src/
• Pass: All paths wrapped in quotes: "${path}"
• Fail: Unquoted paths that may contain spaces
• Severity: Critical
• Fix: Use template literals with quotes: "${this.cliPath}" command

IPC-007: Set command timeouts

• Description: External commands must have timeouts
• Search: grep -r "execAsync" electron-app/src/
• Pass: All execAsync calls include timeout option
• Fail: Commands without timeout can hang indefinitely
• Severity: High
• Fix: Add { timeout: milliseconds } option

IPC-008: Handle macOS activation

• Description: App should recreate window on dock click
• Search: grep -r "app.on.*activate" electron-app/src/
• Pass: activate handler creates window if none exist
• Fail: Missing or empty activate handler
• Severity: Medium
• Fix: Add if (BrowserWindow.getAllWindows().length === 0) createMainWindow()

Electron Performance Patterns

Window management, memory optimization, and startup performance.

Startup Performance

Deferred Window Display

createMainWindow(): BrowserWindow {
  const mainWindow = new BrowserWindow({
    show: false,  // Don't show until ready
    backgroundColor: '#1a1f2e',  // Prevent white flash
    webPreferences: {
      preload: path.join(__dirname, '../preload/index.js'),
      nodeIntegration: false,
      contextIsolation: true
    }
  })

  // Show when content is ready
  mainWindow.once('ready-to-show', () => {
    mainWindow.show()
  })

  // Fallback timeout to prevent infinite loading
  setTimeout(() => {
    if (!mainWindow.isVisible()) {
      console.log('Main window timeout - showing anyway')
      mainWindow.show()
    }
  }, 5000)

  return mainWindow
}

Splash Screen Pattern

async onReady(): Promise<void> {
  // 1. Show splash immediately
  const splash = this.windowManager.createSplashWindow()

  try {
    // 2. Initialize in background
    await this.ensureCLI()
    await this.waitForServer()
    await this.ensureModels()

    // 3. Create main window (hidden)
    this.windowManager.createMainWindow()

    // 4. Main window shows via ready-to-show, closes splash
  } catch (error) {
    this.handleStartupError(error)
  }
}

Progress Updates During Startup

updateSplash(status: {
  message: string
  progress?: number
  models?: ModelStatus[]
}): void {
  if (this.splashWindow && !this.splashWindow.isDestroyed()) {
    this.splashWindow.webContents.send('splash-status', status)
  }
}

// Usage during initialization
this.windowManager.updateSplash({
  message: 'Checking for LlamaFarm CLI...',
  progress: 10
})

Window Management

Responsive Window Sizing

import { screen } from 'electron'

createMainWindow(): BrowserWindow {
  const { width, height } = screen.getPrimaryDisplay().workAreaSize

  return new BrowserWindow({
    width: Math.min(1400, width),   // Cap at max size
    height: Math.min(900, height),
    minWidth: 800,   // Set minimum sizes
    minHeight: 600
  })
}

Window Reference Management

class WindowManager {
  private splashWindow: BrowserWindow | null = null
  private mainWindow: BrowserWindow | null = null

  // Always check before using
  closeSplash(): void {
    if (this.splashWindow && !this.splashWindow.isDestroyed()) {
      this.splashWindow.close()
      this.splashWindow = null
    }
  }

  // Clear reference on close
  createMainWindow(): BrowserWindow {
    this.mainWindow = new BrowserWindow({ ... })

    this.mainWindow.on('closed', () => {
      this.mainWindow = null  // Prevent memory leak
    })

    return this.mainWindow
  }

  // Cleanup all windows
  cleanup(): void {
    if (this.splashWindow && !this.splashWindow.isDestroyed()) {
      this.splashWindow.close()
    }
    if (this.mainWindow && !this.mainWindow.isDestroyed()) {
      this.mainWindow.close()
    }
  }
}

External Process Management

Exponential Backoff for Health Checks

async waitForServer(): Promise<void> {
  const maxAttempts = 120
  let attempts = 0
  let delay = 500        // Start with 500ms
  const maxDelay = 2000  // Cap at 2 seconds

  while (attempts < maxAttempts) {
    try {
      // Use 127.0.0.1 instead of localhost to avoid IPv6 delays
      const response = await axios.get('http://127.0.0.1:14345/health', {
        timeout: 3000
      })

      if (response.status === 200) {
        console.log('Server is ready!')
        return
      }
    } catch {
      // Server not ready yet
    }

    await new Promise(resolve => setTimeout(resolve, delay))
    delay = Math.min(delay * 1.1, maxDelay)  // Gradual backoff
    attempts++
  }

  throw new Error(`Server failed to respond after ${maxAttempts} attempts`)
}

Retry Logic for Flaky Operations

async startServices(): Promise<void> {
  const timeout = 600000  // 10 minutes for first-time setup
  const maxRetries = 2

  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      if (attempt > 1) {
        console.log(`Retry attempt ${attempt}/${maxRetries}...`)
        await new Promise(resolve => setTimeout(resolve, 3000))
      }

      await execAsync(
        `"${this.cliPath}" services start`,
        { timeout }
      )

      // Verify services started
      await new Promise(resolve => setTimeout(resolve, 2000))
      const verifyResult = await execAsync(
        `"${this.cliPath}" services status`,
        { timeout: 60000 }
      )

      if (verifyResult.stdout.includes('State: running')) {
        return  // Success
      }
    } catch (error) {
      if (attempt >= maxRetries) {
        throw error
      }
    }
  }
}

Memory Management

Logger with File Rotation

class Logger {
  private writeStream: fs.WriteStream | null = null

  async initialize(): Promise<void> {
    // Rotate log if too large (> 10MB)
    try {
      const stats = await fs.promises.stat(this.logFile)
      if (stats.size > 10 * 1024 * 1024) {
        const rotatedPath = this.logFile.replace('.log', `.${Date.now()}.log`)
        await fs.promises.rename(this.logFile, rotatedPath)
      }
    } catch {
      // File doesn't exist yet
    }

    this.writeStream = fs.createWriteStream(this.logFile, { flags: 'a' })
  }

  async close(): Promise<void> {
    if (this.writeStream) {
      await new Promise<void>((resolve) => {
        this.writeStream!.end(() => resolve())
      })
      this.writeStream = null
    }
  }
}

Cleanup Event Listeners

// Preload: Return cleanup functions
const api = {
  backend: {
    onStatusChange: (callback: (status: BackendStatus) => void) => {
      const listener = (_event: IpcRendererEvent, status: BackendStatus) => {
        callback(status)
      }
      ipcRenderer.on('backend-status', listener)

      // Return cleanup function
      return () => ipcRenderer.removeListener('backend-status', listener)
    }
  }
}

// Renderer: Use cleanup on unmount
useEffect(() => {
  const cleanup = window.llamafarm.backend.onStatusChange((status) => {
    setStatus(status)
  })

  return cleanup  // Remove listener on unmount
}, [])

CSS Performance

Inject CSS After Load

mainWindow.webContents.on('did-finish-load', () => {
  mainWindow?.webContents.insertCSS(`
    /* Make the header draggable */
    header {
      -webkit-app-region: drag;
      padding-left: 80px !important;
    }

    /* Keep buttons clickable */
    header button, header a {
      -webkit-app-region: no-drag;
    }
  `)
})

Efficient Splash Screen Updates

// Use efficient DOM updates in splash screen
function renderModels(models: ModelStatus[]): void {
  const container = document.getElementById('models-container')

  // Clear and rebuild (simple for small lists)
  container.innerHTML = ''

  models.forEach(model => {
    const item = document.createElement('div')
    item.className = 'model-item'

    // Use textContent for safety and performance
    const name = document.createElement('div')
    name.textContent = model.display_name

    item.appendChild(name)
    container.appendChild(item)
  })
}

Build Performance

Electron Vite Configuration

// electron.vite.config.ts
import { defineConfig, externalizeDepsPlugin } from 'electron-vite'

export default defineConfig({
  main: {
    plugins: [externalizeDepsPlugin()],  // Externalize Node dependencies
    build: {
      outDir: 'dist/main'
    }
  },
  preload: {
    plugins: [externalizeDepsPlugin()],
    build: {
      outDir: 'dist/preload'
    }
  },
  renderer: {
    root: 'src/renderer',
    build: {
      outDir: '../../dist/renderer'
    }
  }
})

---

Checklist

PERF-001: Hide window until ready

• Description: Windows should not show until content is loaded
• Search: grep -r "new BrowserWindow" electron-app/src/
• Pass: show: false with ready-to-show event handler
• Fail: Window shows immediately or during load
• Severity: High
• Fix: Set show: false, add once('ready-to-show') handler

PERF-002: Set background color

• Description: Windows should have background color to prevent white flash
• Search: grep -r "backgroundColor" electron-app/src/
• Pass: backgroundColor set in BrowserWindow options
• Fail: No background color causes white flash
• Severity: Medium
• Fix: Add backgroundColor matching app theme

PERF-003: Use splash screen for long startups

• Description: Show splash screen during initialization
• Search: grep -r "createSplashWindow\|splash" electron-app/src/
• Pass: Splash shown during async initialization
• Fail: User sees blank/frozen window during startup
• Severity: High
• Fix: Create splash window first, close after main ready

PERF-004: Null window references on close

• Description: Clear window references to prevent memory leaks
• Search: grep -r "on.*closed" electron-app/src/
• Pass: Window variables set to null in closed handler
• Fail: References kept after window closed
• Severity: Medium
• Fix: Add window.on('closed', () => { this.window = null })

PERF-005: Use 127.0.0.1 not localhost

• Description: Use IP address to avoid DNS/IPv6 resolution delays
• Search: grep -r "localhost" electron-app/src/main/
• Pass: Health checks use 127.0.0.1
• Fail: Using localhost for local connections
• Severity: Low
• Fix: Replace localhost with 127.0.0.1 for performance

PERF-006: Implement exponential backoff

• Description: Retries should use increasing delays
• Search: grep -r "while.*attempts\|retry" electron-app/src/
• Pass: Delay increases between retry attempts
• Fail: Fixed delay between retries
• Severity: Medium
• Fix: Use delay = Math.min(delay * multiplier, maxDelay)

PERF-007: Set command timeouts

• Description: External commands must have timeouts
• Search: grep -r "execAsync" electron-app/src/
• Pass: All execAsync calls include timeout option
• Fail: Commands can hang indefinitely
• Severity: High
• Fix: Add { timeout: milliseconds } to all execAsync calls

PERF-008: Return cleanup functions

• Description: Event listener subscriptions must return cleanup
• Search: grep -r "ipcRenderer.on" electron-app/src/preload/
• Pass: All listeners return removeListener function
• Fail: Event subscriptions cannot be cleaned up
• Severity: Medium
• Fix: Return () => ipcRenderer.removeListener(channel, listener)

PERF-009: Rotate log files

• Description: Log files should be rotated to prevent growth
• Search: grep -r "WriteStream\|createWriteStream" electron-app/src/
• Pass: Log rotation implemented for large files
• Fail: Unbounded log file growth
• Severity: Low
• Fix: Check file size and rename before creating new stream

Electron Security Patterns

Context isolation, preload security, and secure Electron configuration.

Security Model

Electron security is built on process isolation:

Main Process (Node.js)     Preload (Bridge)        Renderer (Browser)
-------------------        ----------------        ------------------
Full Node.js access        Limited Node.js         No Node.js access
Native OS APIs             contextBridge only      Web APIs only
File system access         Exposes safe APIs       Uses exposed APIs
Child processes            No direct IPC access    Sandboxed

Context Isolation

Always Enable Context Isolation

new BrowserWindow({
  webPreferences: {
    nodeIntegration: false,    // REQUIRED: Disable Node in renderer
    contextIsolation: true,    // REQUIRED: Isolate preload context
    preload: path.join(__dirname, '../preload/index.js')
  }
})

Why Context Isolation Matters

• Prevents renderer from accessing Node.js globals
• Isolates preload script's execution context
• Protects against prototype pollution attacks
• Limits blast radius of XSS vulnerabilities

Preload Script Security

Expose Minimal API Surface

// GOOD: Expose specific, typed functions
const api = {
  cli: {
    getInfo: () => ipcRenderer.invoke('cli:info')
  },
  platform: process.platform  // Safe read-only value
}

contextBridge.exposeInMainWorld('llamafarm', api)

// BAD: Never expose raw IPC
const badApi = {
  ipcRenderer: ipcRenderer,  // NEVER DO THIS
  invoke: ipcRenderer.invoke // NEVER DO THIS
}

Type-Safe API Exposure

// Define the exposed API type
interface LlamaFarmAPI {
  cli: {
    getInfo: () => Promise<{ isInstalled: boolean; path: string | null }>
  }
  backend: {
    getStatus: () => Promise<BackendStatus>
    onStatusChange: (callback: (status: BackendStatus) => void) => () => void
  }
  platform: NodeJS.Platform
  version: string
}

const api: LlamaFarmAPI = {
  cli: {
    getInfo: () => ipcRenderer.invoke('cli:info')
  },
  backend: {
    getStatus: () => ipcRenderer.invoke('backend:status'),
    onStatusChange: (callback) => {
      const listener = (_event: IpcRendererEvent, status: BackendStatus) => {
        callback(status)
      }
      ipcRenderer.on('backend-status', listener)
      return () => ipcRenderer.removeListener('backend-status', listener)
    }
  },
  platform: process.platform,
  version: process.versions.electron
}

contextBridge.exposeInMainWorld('llamafarm', api)
export type { LlamaFarmAPI }

DOM Security in Embedded HTML

Safe DOM Building

// When building DOM in splash/embedded HTML, use safe methods

// GOOD: textContent escapes HTML
const name = document.createElement('div')
name.className = 'model-name'
name.textContent = model.display_name  // Safe: escapes HTML

// BAD: innerHTML with untrusted data
element.innerHTML = model.display_name  // XSS vulnerability

// GOOD: Sanitize status to allowlist
const VALID_STATUSES = ['present', 'downloading', 'checking', 'error']
const safeStatus = VALID_STATUSES.includes(model.status)
  ? model.status
  : 'checking'

icon.className = 'model-icon ' + safeStatus  // Safe: validated

Sanitize Numeric Values

// Prevent CSS injection through numeric values
const safeProgress = Math.max(0, Math.min(100, Number(model.progress) || 0))
progressBar.style.width = safeProgress + '%'  // Safe: bounded number

Window Security Configuration

Secure BrowserWindow Options

new BrowserWindow({
  webPreferences: {
    nodeIntegration: false,
    contextIsolation: true,
    preload: path.join(__dirname, '../preload/index.js'),

    // Additional security options
    sandbox: true,                    // Enable renderer sandbox
    webSecurity: true,                // Enable same-origin policy
    allowRunningInsecureContent: false,
    experimentalFeatures: false
  }
})

When webSecurity Can Be Disabled

// Only disable for localhost development with trusted content
new BrowserWindow({
  webPreferences: {
    webSecurity: false  // Only for localhost CORS during development
  }
})

// Document the reason and scope
// webSecurity: false - Required for localhost:14345 API access
// The Designer UI is served from localhost and calls localhost APIs

External Content Loading

Validate URLs Before Loading

// Only load from trusted origins
const ALLOWED_ORIGINS = [
  'http://localhost:14345',
  'http://127.0.0.1:14345'
]

loadDesigner(url: string): void {
  const parsed = new URL(url)
  const origin = parsed.origin

  if (!ALLOWED_ORIGINS.includes(origin)) {
    throw new Error(`Untrusted origin: ${origin}`)
  }

  this.mainWindow.loadURL(url)
}

Safe External Link Handling

import { shell } from 'electron'

// Open external links in system browser
{
  label: 'Documentation',
  click: async () => {
    await shell.openExternal('https://docs.llamafarm.dev')
  }
}

// Validate URL before opening
async openExternalSafe(url: string): Promise<void> {
  const parsed = new URL(url)

  if (!['http:', 'https:'].includes(parsed.protocol)) {
    throw new Error(`Invalid protocol: ${parsed.protocol}`)
  }

  await shell.openExternal(url)
}

Auto-Updater Security

Secure Update Configuration

import { autoUpdater } from 'electron-updater'

// Only auto-update in production
if (app.isPackaged) {
  autoUpdater.autoDownload = true
  autoUpdater.autoInstallOnAppQuit = true

  // Verify update signatures (electron-builder handles this)
  // Updates are signed and verified automatically

  autoUpdater.checkForUpdatesAndNotify()
}

Handle Update Errors Gracefully

autoUpdater.on('error', (err) => {
  // Log but don't expose error details to user
  console.error('Auto-updater error:', err)
  // Don't show raw error messages that might leak system info
})

File System Security

Validate File Paths

import * as path from 'path'
import * as os from 'os'

// Ensure paths stay within expected directories
function getSafePath(relativePath: string): string {
  const homeDir = os.homedir()
  const basePath = path.join(homeDir, '.llamafarm')
  const fullPath = path.resolve(basePath, relativePath)

  // Prevent directory traversal
  if (!fullPath.startsWith(basePath)) {
    throw new Error('Path traversal detected')
  }

  return fullPath
}

Secure Executable Permissions

// Set proper permissions on downloaded executables
await fsPromises.chmod(this.cliPath, 0o755)  // rwxr-xr-x

---

Checklist

SEC-001: Context isolation enabled

• Description: All BrowserWindows must have contextIsolation: true
• Search: grep -r "contextIsolation" electron-app/src/
• Pass: contextIsolation: true in all webPreferences
• Fail: contextIsolation: false or missing
• Severity: Critical
• Fix: Set contextIsolation: true in webPreferences

SEC-002: Node integration disabled

• Description: Renderer processes must not have Node.js access
• Search: grep -r "nodeIntegration" electron-app/src/
• Pass: nodeIntegration: false in all webPreferences
• Fail: nodeIntegration: true
• Severity: Critical
• Fix: Set nodeIntegration: false, use preload for IPC

SEC-003: No raw IPC exposure

• Description: Preload must not expose ipcRenderer directly
• Search: grep -r "ipcRenderer" electron-app/src/preload/
• Pass: Only specific functions exposed via contextBridge
• Fail: Raw ipcRenderer or invoke exposed
• Severity: Critical
• Fix: Wrap each IPC call in a specific function

SEC-004: Validate exposed API inputs

• Description: Functions exposed to renderer must validate inputs
• Search: grep -r "contextBridge.exposeInMainWorld" electron-app/src/
• Pass: Exposed functions validate parameters before IPC
• Fail: Parameters passed directly to ipcRenderer
• Severity: High
• Fix: Add input validation in exposed functions

SEC-005: Use textContent not innerHTML

• Description: DOM manipulation must use textContent for untrusted data
• Search: grep -r "innerHTML" electron-app/src/
• Pass: innerHTML only used with static/sanitized content
• Fail: innerHTML with dynamic/untrusted data
• Severity: High
• Fix: Use textContent or createElement with textContent

SEC-006: Allowlist dynamic class names

• Description: Dynamic CSS classes must be validated against allowlist
• Search: grep -r "className.*+" electron-app/src/
• Pass: Dynamic values checked against VALID_* arrays
• Fail: Unvalidated strings concatenated to className
• Severity: Medium
• Fix: Validate against allowlist before concatenation

SEC-007: Sanitize numeric style values

• Description: Numeric values for styles must be bounded
• Search: grep -r "style\.(width|height|left|top)" electron-app/src/
• Pass: Values bounded with Math.max/min
• Fail: Unbounded numbers used in styles
• Severity: Medium
• Fix: Use Math.max(0, Math.min(100, Number(value) || 0))

SEC-008: Validate URLs before loading

• Description: Only load content from trusted origins
• Search: grep -r "loadURL" electron-app/src/
• Pass: URLs validated against allowlist
• Fail: Arbitrary URLs loaded without validation
• Severity: High
• Fix: Check URL origin against ALLOWED_ORIGINS array

SEC-009: Auto-update only in production

• Description: Auto-updater should only run in packaged builds
• Search: grep -r "autoUpdater" electron-app/src/
• Pass: Update checks guarded by app.isPackaged
• Fail: Updates checked in development mode
• Severity: Medium
• Fix: Wrap with if (app.isPackaged) { ... }

SEC-010: Prevent directory traversal

• Description: File paths must be validated to prevent traversal
• Search: grep -r "path.join\|path.resolve" electron-app/src/
• Pass: Paths validated to stay within base directory
• Fail: User input used directly in path operations
• Severity: High
• Fix: Use path.resolve and check startsWith(basePath)