@schalkneethling/toolkit 0.2.0 → 0.4.0

package/skills/frontend-security/references/dom-security.md

@@ -0,0 +1,229 @@
+# DOM Security Reference
+
+## DOM-Based XSS Prevention
+
+### Rule #1: HTML Subcontext
+
+Untrusted data in HTML element content:
+
+```javascript
+// UNSAFE
+element.innerHTML = '<div>' + userInput + '</div>';
+
+// SAFE - use textContent
+element.textContent = userInput;
+
+// SAFE - create elements programmatically
+const div = document.createElement('div');
+div.textContent = userInput;
+parent.appendChild(div);
+```
+
+### Rule #2: JavaScript Context
+
+Untrusted data in JavaScript:
+
+```javascript
+// UNSAFE - string concatenation in script
+const script = 'var x = "' + userInput + '"';
+
+// UNSAFE - dynamic property access
+window[userInput]();
+
+// SAFE - use data attributes
+element.dataset.value = userInput;
+const value = element.dataset.value;
+```
+
+### Rule #3: HTML Attribute Context
+
+```javascript
+// UNSAFE - event handlers
+element.setAttribute('onclick', userInput);
+
+// UNSAFE - dangerous attributes
+element.setAttribute('href', userInput);  // javascript: URLs
+element.setAttribute('src', userInput);   // script injection
+
+// SAFE - safe attributes only
+const safeAttributes = ['title', 'alt', 'class', 'id', 'name'];
+if (safeAttributes.includes(attributeName)) {
+  element.setAttribute(attributeName, userInput);
+}
+```
+
+### Rule #4: CSS Context
+
+```javascript
+// UNSAFE - expression injection
+element.style.cssText = userInput;
+element.setAttribute('style', userInput);
+
+// SAFE - set specific properties
+element.style.backgroundColor = sanitizeColor(userInput);
+
+function sanitizeColor(input) {
+  // Only allow safe color values
+  const colorRegex = /^#[0-9A-Fa-f]{6}$|^#[0-9A-Fa-f]{3}$|^rgb\(\d{1,3},\s*\d{1,3},\s*\d{1,3}\)$/;
+  return colorRegex.test(input) ? input : 'inherit';
+}
+```
+
+### Rule #5: URL Context
+
+```javascript
+// UNSAFE - unvalidated URLs
+location.href = userInput;
+window.open(userInput);
+element.setAttribute('href', userInput);
+
+// SAFE - validate URL protocol
+function validateUrl(input) {
+  try {
+    const url = new URL(input, window.location.origin);
+    const allowedProtocols = ['http:', 'https:', 'mailto:'];
+    if (!allowedProtocols.includes(url.protocol)) {
+      return null;
+    }
+    return url.href;
+  } catch {
+    return null;
+  }
+}
+
+const safeUrl = validateUrl(userInput);
+if (safeUrl) {
+  location.href = safeUrl;
+}
+```
+
+## DOM Clobbering Prevention
+
+### What is DOM Clobbering?
+
+Named elements (id, name attributes) create global variables:
+
+```html
+<!-- This creates window.config -->
+<img id="config" src="x">
+
+<!-- JavaScript that assumes config is an object will break -->
+<script>
+  console.log(config.apiKey); // Error: HTMLImageElement has no apiKey
+</script>
+```
+
+### Prevention Strategies
+
+```javascript
+// 1. Use Object.hasOwn() or hasOwnProperty()
+if (Object.hasOwn(window, 'config') && typeof config === 'object') {
+  // Safe to use config
+}
+
+// 2. Access through document methods
+const element = document.getElementById('config');
+
+// 3. Use Map instead of objects for user-controlled keys
+const userConfig = new Map();
+userConfig.set(userKey, userValue);
+
+// 4. Freeze global objects
+Object.freeze(window.config);
+
+// 5. Use nullish coalescing with type checking
+const config = window.config ?? {};
+if (typeof config.apiKey === 'string') {
+  // Safe to use
+}
+```
+
+### HTML Sanitization Against Clobbering
+
+```javascript
+// DOMPurify with clobbering protection
+const clean = DOMPurify.sanitize(dirty, {
+  SANITIZE_DOM: true,  // Remove clobbering vectors
+  SANITIZE_NAMED_PROPS: true
+});
+```
+
+## Secure DOM APIs
+
+### Safe Methods
+
+```javascript
+// Text content (no HTML parsing)
+element.textContent = userInput;
+document.createTextNode(userInput);
+
+// Attribute manipulation (for safe attributes)
+element.setAttribute('data-value', userInput);
+element.classList.add(sanitizedClass);
+
+// Query selectors (read-only)
+document.querySelector(selector);
+document.querySelectorAll(selector);
+```
+
+### Dangerous Methods (Require Sanitization)
+
+```javascript
+// HTML parsing methods
+element.innerHTML = sanitized;
+element.outerHTML = sanitized;
+element.insertAdjacentHTML(position, sanitized);
+document.write(sanitized);  // Avoid entirely
+
+// Script execution
+eval();           // Never use with user input
+new Function();   // Never use with user input
+setTimeout(string); // Never pass strings
+setInterval(string); // Never pass strings
+```
+
+## postMessage Security
+
+```javascript
+// Sender - specify exact origin
+targetWindow.postMessage(data, 'https://trusted-domain.com');
+
+// Receiver - always validate origin
+window.addEventListener('message', (event) => {
+  // Validate origin
+  if (event.origin !== 'https://trusted-domain.com') {
+    return;
+  }
+
+  // Validate data structure
+  if (typeof event.data !== 'object' || !event.data.type) {
+    return;
+  }
+
+  // Process trusted message
+  handleMessage(event.data);
+});
+```
+
+## Trusted Types (Modern Browsers)
+
+```javascript
+// Enable Trusted Types via CSP
+// Content-Security-Policy: require-trusted-types-for 'script'
+
+// Create a policy
+const policy = trustedTypes.createPolicy('default', {
+  createHTML: (input) => DOMPurify.sanitize(input),
+  createScript: () => { throw new Error('Scripts not allowed'); },
+  createScriptURL: (input) => {
+    const url = new URL(input, location.origin);
+    if (url.origin === location.origin) return input;
+    throw new Error('Invalid script URL');
+  }
+});
+
+// Usage
+element.innerHTML = policy.createHTML(userInput);
+```
+
+OWASP Reference: https://cheatsheetseries.owasp.org/cheatsheets/DOM_based_XSS_Prevention_Cheat_Sheet.html

package/skills/frontend-security/references/file-upload-security.md

@@ -0,0 +1,310 @@
+# File Upload Security Reference
+
+## Core Protection Checklist
+
+- [ ] Validate file extension (allowlist only)
+- [ ] Validate Content-Type header
+- [ ] Validate file signature (magic bytes)
+- [ ] Generate new random filename
+- [ ] Enforce file size limits
+- [ ] Store outside webroot
+- [ ] Scan for malware
+- [ ] Require authentication
+- [ ] Implement CSRF protection
+
+## Extension Validation
+
+### Allowlist Approach
+
+```javascript
+const ALLOWED_EXTENSIONS = {
+  images: ['.jpg', '.jpeg', '.png', '.gif', '.webp'],
+  documents: ['.pdf', '.docx', '.xlsx'],
+  data: ['.csv', '.json']
+};
+
+function validateExtension(filename, category) {
+  const ext = path.extname(filename).toLowerCase();
+  return ALLOWED_EXTENSIONS[category]?.includes(ext) ?? false;
+}
+```
+
+### Dangerous Extensions to Block
+
+```javascript
+const DANGEROUS_EXTENSIONS = [
+  // Server-side execution
+  '.php', '.php3', '.php4', '.php5', '.phtml',
+  '.asp', '.aspx', '.ascx', '.ashx',
+  '.jsp', '.jspx', '.jspa',
+  '.cgi', '.pl', '.py', '.rb',
+
+  // Windows executable
+  '.exe', '.dll', '.bat', '.cmd', '.com', '.msi', '.ps1',
+
+  // Script files
+  '.js', '.vbs', '.wsf', '.hta',
+
+  // Config files
+  '.htaccess', '.htpasswd', '.config', '.ini',
+
+  // Archive (can contain malicious files)
+  '.zip', '.tar', '.gz', '.rar', '.7z'
+];
+```
+
+### Double Extension Prevention
+
+```javascript
+function sanitizeFilename(filename) {
+  // Remove all extensions except the last
+  const parts = filename.split('.');
+  if (parts.length > 2) {
+    return `${parts[0]}.${parts[parts.length - 1]}`;
+  }
+
+  // Or generate completely new filename
+  const ext = path.extname(filename).toLowerCase();
+  const uuid = crypto.randomUUID();
+  return `${uuid}${ext}`;
+}
+```
+
+## Content-Type Validation
+
+```javascript
+const ALLOWED_MIME_TYPES = {
+  '.jpg': ['image/jpeg'],
+  '.jpeg': ['image/jpeg'],
+  '.png': ['image/png'],
+  '.gif': ['image/gif'],
+  '.webp': ['image/webp'],
+  '.pdf': ['application/pdf'],
+  '.docx': ['application/vnd.openxmlformats-officedocument.wordprocessingml.document']
+};
+
+function validateMimeType(file) {
+  const ext = path.extname(file.originalname).toLowerCase();
+  const allowedMimes = ALLOWED_MIME_TYPES[ext];
+
+  if (!allowedMimes) return false;
+  return allowedMimes.includes(file.mimetype);
+}
+```
+
+## File Signature (Magic Bytes) Validation
+
+```javascript
+const FILE_SIGNATURES = {
+  jpg: Buffer.from([0xFF, 0xD8, 0xFF]),
+  png: Buffer.from([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A]),
+  gif: Buffer.from([0x47, 0x49, 0x46, 0x38]),
+  pdf: Buffer.from([0x25, 0x50, 0x44, 0x46]),
+  zip: Buffer.from([0x50, 0x4B, 0x03, 0x04])
+};
+
+async function validateFileSignature(filePath, expectedType) {
+  const buffer = Buffer.alloc(8);
+  const fd = await fs.open(filePath, 'r');
+  await fd.read(buffer, 0, 8, 0);
+  await fd.close();
+
+  const signature = FILE_SIGNATURES[expectedType];
+  if (!signature) return false;
+
+  return buffer.slice(0, signature.length).equals(signature);
+}
+```
+
+## Safe Storage
+
+```javascript
+const multer = require('multer');
+const path = require('path');
+const crypto = require('crypto');
+
+// Store OUTSIDE webroot
+const UPLOAD_DIR = '/var/app/uploads';  // Not in /public/
+
+const storage = multer.diskStorage({
+  destination: (req, file, cb) => {
+    // Organize by date
+    const date = new Date().toISOString().split('T')[0];
+    const dir = path.join(UPLOAD_DIR, date);
+    fs.mkdirSync(dir, { recursive: true });
+    cb(null, dir);
+  },
+  filename: (req, file, cb) => {
+    // Generate random filename
+    const ext = path.extname(file.originalname).toLowerCase();
+    const name = crypto.randomBytes(16).toString('hex');
+    cb(null, `${name}${ext}`);
+  }
+});
+
+const upload = multer({
+  storage,
+  limits: {
+    fileSize: 5 * 1024 * 1024,  // 5MB
+    files: 1
+  },
+  fileFilter: (req, file, cb) => {
+    if (!validateMimeType(file)) {
+      cb(new Error('Invalid file type'));
+      return;
+    }
+    cb(null, true);
+  }
+});
+```
+
+## Secure File Serving
+
+```javascript
+// Serve files through application, not directly
+app.get('/files/:id', async (req, res) => {
+  // Verify user authorization
+  if (!req.user || !canAccessFile(req.user, req.params.id)) {
+    return res.status(403).send('Forbidden');
+  }
+
+  // Get file from database (not from user input)
+  const fileRecord = await db.getFile(req.params.id);
+  if (!fileRecord) return res.status(404).send('Not found');
+
+  // Set safe headers
+  res.setHeader('Content-Type', fileRecord.mimeType);
+  res.setHeader('Content-Disposition', `attachment; filename="${fileRecord.safeName}"`);
+  res.setHeader('X-Content-Type-Options', 'nosniff');
+
+  // Stream file
+  const stream = fs.createReadStream(fileRecord.path);
+  stream.pipe(res);
+});
+```
+
+## Image Rewriting
+
+Destroy potential malicious content by re-encoding images:
+
+```javascript
+const sharp = require('sharp');
+
+async function sanitizeImage(inputPath, outputPath) {
+  await sharp(inputPath)
+    .rotate()  // Apply EXIF orientation
+    .toFormat('jpeg', { quality: 90 })  // Re-encode
+    .toFile(outputPath);
+}
+```
+
+## ZIP File Handling
+
+```javascript
+const AdmZip = require('adm-zip');
+const path = require('path');
+
+function safeExtractZip(zipPath, destDir, maxSize = 100 * 1024 * 1024) {
+  const zip = new AdmZip(zipPath);
+  const entries = zip.getEntries();
+
+  let totalSize = 0;
+
+  for (const entry of entries) {
+    // Check for path traversal
+    const resolvedDest = path.resolve(destDir);
+    const resolvedEntry = path.resolve(destDir, entry.entryName);
+    const relativeEntry = path.relative(resolvedDest, resolvedEntry);
+
+    if (relativeEntry.startsWith('..') || path.isAbsolute(relativeEntry)) {
+      throw new Error('Path traversal detected');
+    }
+
+    // Check for zip bomb
+    totalSize += entry.header.size;
+    if (totalSize > maxSize) {
+      throw new Error('Extracted size exceeds limit');
+    }
+
+    // Check compression ratio (zip bomb indicator)
+    const ratio = entry.header.size / entry.header.compressedSize;
+    if (ratio > 100) {
+      throw new Error('Suspicious compression ratio');
+    }
+  }
+
+  zip.extractAllTo(destDir, true);
+}
+```
+
+## Express.js Complete Example
+
+```javascript
+const express = require('express');
+const multer = require('multer');
+const path = require('path');
+const crypto = require('crypto');
+const fs = require('fs').promises;
+
+const app = express();
+
+// Configuration
+const UPLOAD_DIR = '/var/app/uploads';
+const MAX_FILE_SIZE = 5 * 1024 * 1024;
+const ALLOWED_TYPES = ['image/jpeg', 'image/png', 'image/gif'];
+
+// Multer setup
+const upload = multer({
+  storage: multer.memoryStorage(),
+  limits: { fileSize: MAX_FILE_SIZE },
+  fileFilter: (req, file, cb) => {
+    if (!ALLOWED_TYPES.includes(file.mimetype)) {
+      cb(new multer.MulterError('LIMIT_UNEXPECTED_FILE'));
+      return;
+    }
+    cb(null, true);
+  }
+});
+
+// Upload endpoint
+app.post('/upload',
+  requireAuth,           // Authentication
+  verifyToken,           // CSRF token
+  upload.single('file'), // File handling
+  async (req, res) => {
+    try {
+      const file = req.file;
+      if (!file) return res.status(400).json({ error: 'No file' });
+
+      // Validate magic bytes
+      if (!validateMagicBytes(file.buffer, file.mimetype)) {
+        return res.status(400).json({ error: 'Invalid file' });
+      }
+
+      // Generate safe filename
+      const ext = path.extname(file.originalname).toLowerCase();
+      const filename = `${crypto.randomUUID()}${ext}`;
+      const filepath = path.join(UPLOAD_DIR, filename);
+
+      // Save file
+      await fs.writeFile(filepath, file.buffer);
+
+      // Store metadata in database
+      const fileRecord = await db.createFile({
+        userId: req.user.id,
+        filename,
+        originalName: file.originalname,
+        mimeType: file.mimetype,
+        size: file.size
+      });
+
+      res.json({ id: fileRecord.id });
+    } catch (error) {
+      console.error(error);
+      res.status(500).json({ error: 'Upload failed' });
+    }
+  }
+);
+```
+
+OWASP Reference: https://cheatsheetseries.owasp.org/cheatsheets/File_Upload_Cheat_Sheet.html