security

name	security
description	Security best practices for Electron and web applications. Use when implementing authentication, handling user input, managing secrets, or reviewing code for security. Triggers on security, auth, validation, sanitize, XSS, CSRF, injection, secrets, permissions.

Security Best Practices

Security patterns and practices for building secure Electron applications with proper input validation, authentication, and defense against common vulnerabilities.

When to Use This Skill

• Implementing authentication/authorization
• Handling user input
• Managing secrets and API keys
• Processing external data
• Reviewing code for security issues
• Setting up Electron security

Core Security Principles

Defense in Depth

Layer multiple security controls:

// Layer 1: Input validation at entry point
function handleUserInput(input: string): void {
  const validated = validateInput(input);
  
  // Layer 2: Sanitization before processing
  const sanitized = sanitizeForProcessing(validated);
  
  // Layer 3: Parameterized queries (no string concatenation)
  await db.query('SELECT * FROM items WHERE name = ?', [sanitized]);
  
  // Layer 4: Output encoding for display
  const encoded = encodeForHTML(sanitized);
}

Principle of Least Privilege

Request only necessary permissions:

// ❌ Overly permissive
mainWindow = new BrowserWindow({
  webPreferences: {
    nodeIntegration: true,  // Dangerous!
    contextIsolation: false,  // Dangerous!
  }
});

// ✅ Minimal permissions
mainWindow = new BrowserWindow({
  webPreferences: {
    nodeIntegration: false,
    contextIsolation: true,
    sandbox: true,
    webSecurity: true,
    preload: path.join(__dirname, 'preload.js'),
  }
});

Electron Security

Secure Window Configuration

// src/main/window.ts
export function createSecureWindow(): BrowserWindow {
  const mainWindow = new BrowserWindow({
    width: 1200,
    height: 800,
    webPreferences: {
      // Security essentials
      nodeIntegration: false,
      contextIsolation: true,
      sandbox: true,
      webSecurity: true,
      allowRunningInsecureContent: false,
      
      // Preload for safe IPC
      preload: path.join(__dirname, 'preload.js'),
    },
  });
  
  // Prevent navigation to external URLs
  mainWindow.webContents.on('will-navigate', (event, url) => {
    const allowed = ['http://localhost:', 'file://'];
    if (!allowed.some(prefix => url.startsWith(prefix))) {
      event.preventDefault();
      console.warn('Blocked navigation to:', url);
    }
  });
  
  // Prevent new windows
  mainWindow.webContents.setWindowOpenHandler(({ url }) => {
    shell.openExternal(url);  // Open in system browser
    return { action: 'deny' };
  });
  
  return mainWindow;
}

Safe IPC Communication

// ❌ DANGEROUS: Exposing Node APIs
contextBridge.exposeInMainWorld('api', {
  exec: require('child_process').exec,  // Never do this!
  readFile: require('fs').readFileSync,
});

// ✅ SAFE: Expose specific, validated functions
// preload.ts
contextBridge.exposeInMainWorld('api', {
  // Expose only what renderer needs
  getSession: (id: string) => ipcRenderer.invoke('session:get', id),
  startSession: (outcomeId: string) => ipcRenderer.invoke('session:start', outcomeId),
  onSessionUpdate: (callback: (data: unknown) => void) => {
    ipcRenderer.on('session:update', (_, data) => callback(data));
    return () => ipcRenderer.removeListener('session:update', callback);
  },
});

// main process handler - VALIDATE INPUTS
ipcMain.handle('session:get', async (event, id: unknown) => {
  // Validate input type
  if (typeof id !== 'string') {
    throw new Error('Invalid session ID');
  }
  
  // Validate format
  if (!/^[a-zA-Z0-9-]{1,50}$/.test(id)) {
    throw new Error('Invalid session ID format');
  }
  
  // Validate sender
  if (event.senderFrame.url !== expectedURL) {
    throw new Error('Unauthorized sender');
  }
  
  return sessionService.getSession(id);
});

Content Security Policy

// Set CSP header
session.defaultSession.webRequest.onHeadersReceived((details, callback) => {
  callback({
    responseHeaders: {
      ...details.responseHeaders,
      'Content-Security-Policy': [
        "default-src 'self'",
        "script-src 'self'",
        "style-src 'self' 'unsafe-inline'",  // Needed for styled-components
        "img-src 'self' data: https:",
        "font-src 'self'",
        "connect-src 'self' https://api.openai.com https://api.anthropic.com",
      ].join('; ')
    }
  });
});

Input Validation

Schema-Based Validation

import { z } from 'zod';

// Define strict schemas
const OutcomeSchema = z.object({
  id: z.string().uuid(),
  title: z.string().min(1).max(500),
  description: z.string().max(5000).optional(),
  status: z.enum(['pending', 'active', 'completed']),
  createdAt: z.coerce.date(),
});

const CreateTaskSchema = z.object({
  outcomeId: z.string().uuid(),
  title: z.string().min(1).max(200).trim(),
  priority: z.number().int().min(1).max(5).default(3),
});

// Validate at boundaries
async function createTask(input: unknown): Promise<Task> {
  // Parse validates and transforms
  const validated = CreateTaskSchema.parse(input);
  
  // Now safe to use
  return db.insert(tasks).values({
    id: generateId(),
    ...validated,
  }).returning().get();
}

Type Guards for Runtime Safety

// Runtime type checking for external data
function isValidAgentResponse(data: unknown): data is AgentResponse {
  if (typeof data !== 'object' || data === null) return false;
  
  const obj = data as Record<string, unknown>;
  return (
    typeof obj.id === 'string' &&
    typeof obj.content === 'string' &&
    (obj.status === 'complete' || obj.status === 'streaming')
  );
}

async function processAgentResponse(raw: unknown) {
  if (!isValidAgentResponse(raw)) {
    throw new Error('Invalid agent response format');
  }
  
  // TypeScript now knows raw is AgentResponse
  return raw;
}

Injection Prevention

SQL Injection

// ❌ DANGEROUS: String interpolation
const user = db.query(`SELECT * FROM users WHERE id = '${userId}'`);

// ✅ SAFE: Parameterized query
const user = db.query('SELECT * FROM users WHERE id = ?', [userId]);

// ✅ SAFE: With Drizzle ORM (parameterized by default)
const user = await db.select()
  .from(users)
  .where(eq(users.id, userId))
  .get();

// ❌ DANGEROUS: Dynamic column/table names
const column = userInput;
db.query(`SELECT ${column} FROM users`);  // SQL injection!

// ✅ SAFE: Whitelist allowed values
const allowedColumns = ['id', 'name', 'email'] as const;
function selectColumn(column: string) {
  if (!allowedColumns.includes(column as any)) {
    throw new Error('Invalid column');
  }
  return db.select({ [column]: users[column] }).from(users);
}

Command Injection

// ❌ DANGEROUS: Shell command with user input
import { exec } from 'child_process';
exec(`grep ${userInput} /var/log/app.log`);  // Command injection!

// ✅ SAFE: Use array form (no shell)
import { execFile } from 'child_process';
execFile('grep', [userInput, '/var/log/app.log']);

// ✅ SAFE: Use dedicated APIs
import * as fs from 'fs/promises';
const content = await fs.readFile('/var/log/app.log', 'utf8');
const matches = content.split('\n').filter(line => line.includes(userInput));

Path Traversal

// ❌ DANGEROUS: Unvalidated file paths
async function readUserFile(filename: string) {
  return fs.readFile(`./uploads/${filename}`);  // ../../../etc/passwd
}

// ✅ SAFE: Validate and resolve path
import * as path from 'path';

async function readUserFile(filename: string) {
  const uploadsDir = path.resolve('./uploads');
  const filePath = path.resolve(uploadsDir, filename);
  
  // Ensure path stays within uploads directory
  if (!filePath.startsWith(uploadsDir + path.sep)) {
    throw new Error('Invalid file path');
  }
  
  // Additional: validate filename
  if (!/^[\w.-]+$/.test(path.basename(filePath))) {
    throw new Error('Invalid filename');
  }
  
  return fs.readFile(filePath);
}

Secrets Management

Never Commit Secrets

# .gitignore
.env
.env.local
.env.*.local
*.pem
*.key
secrets/

Environment Variables

// ❌ DANGEROUS: Hardcoded secrets
const apiKey = 'sk-1234567890';

// ✅ SAFE: Environment variables
const apiKey = process.env.OPENAI_API_KEY;
if (!apiKey) {
  throw new Error('OPENAI_API_KEY not configured');
}

// ✅ SAFER: Validate at startup
function loadConfig() {
  const config = {
    openaiKey: process.env.OPENAI_API_KEY,
    anthropicKey: process.env.ANTHROPIC_API_KEY,
    dbPath: process.env.DATABASE_PATH ?? './data/agentop.db',
  };
  
  if (!config.openaiKey && !config.anthropicKey) {
    throw new Error('At least one AI provider key required');
  }
  
  return config;
}

Electron Secure Storage

import { safeStorage } from 'electron';

// Encrypt sensitive data before storing
function storeApiKey(key: string): Buffer {
  if (!safeStorage.isEncryptionAvailable()) {
    throw new Error('Encryption not available');
  }
  return safeStorage.encryptString(key);
}

function retrieveApiKey(encrypted: Buffer): string {
  return safeStorage.decryptString(encrypted);
}

// Store encrypted in config
const config = {
  apiKey: storeApiKey(userProvidedKey).toString('base64'),
};

XSS Prevention

Render User Content Safely

// ❌ DANGEROUS: Rendering raw HTML
function Message({ html }: { html: string }) {
  return <div dangerouslySetInnerHTML={{ __html: html }} />;
}

// ✅ SAFE: Text content (auto-escaped by React)
function Message({ text }: { text: string }) {
  return <div>{text}</div>;
}

// ✅ SAFE: Sanitize if HTML needed
import DOMPurify from 'dompurify';

function SafeHTML({ html }: { html: string }) {
  const clean = DOMPurify.sanitize(html, {
    ALLOWED_TAGS: ['p', 'br', 'strong', 'em', 'code', 'pre'],
    ALLOWED_ATTR: ['class'],
  });
  return <div dangerouslySetInnerHTML={{ __html: clean }} />;
}

// ✅ SAFE: Use markdown renderer with sanitization
import ReactMarkdown from 'react-markdown';

function MarkdownContent({ content }: { content: string }) {
  return (
    <ReactMarkdown
      allowedElements={['p', 'code', 'pre', 'strong', 'em', 'ul', 'ol', 'li']}
    >
      {content}
    </ReactMarkdown>
  );
}

URL Validation

// ❌ DANGEROUS: Opening arbitrary URLs
shell.openExternal(userProvidedUrl);

// ✅ SAFE: Validate URL
function openSafeURL(url: string): boolean {
  try {
    const parsed = new URL(url);
    
    // Only allow https
    if (parsed.protocol !== 'https:') {
      console.warn('Blocked non-HTTPS URL:', url);
      return false;
    }
    
    // Optional: whitelist domains
    const allowedDomains = ['github.com', 'docs.example.com'];
    if (!allowedDomains.includes(parsed.hostname)) {
      console.warn('Blocked untrusted domain:', parsed.hostname);
      return false;
    }
    
    shell.openExternal(url);
    return true;
  } catch {
    console.warn('Invalid URL:', url);
    return false;
  }
}

Security Checklist

Before Shipping

• No hardcoded secrets in code
• .env files in .gitignore
• nodeIntegration: false
• contextIsolation: true
• sandbox: true
• All IPC inputs validated
• Navigation restricted
• New window creation blocked or controlled
• CSP headers configured
• User input sanitized before display
• Parameterized database queries
• Path traversal prevented for file operations
• Dependencies audited (npm audit)
• Error messages don't leak sensitive info

Code Review Security Questions

Question	Why It Matters
Is user input validated at entry?	Prevents injection attacks
Are queries parameterized?	Prevents SQL injection
Is output encoded/sanitized?	Prevents XSS
Are file paths validated?	Prevents path traversal
Are secrets in environment variables?	Prevents credential leaks
Is contextIsolation enabled?	Prevents renderer privilege escalation
Are IPC handlers validating senders?	Prevents unauthorized access