@schalkneethling/toolkit 0.2.0 → 0.4.0

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

@@ -0,0 +1,300 @@
+# JWT Security Reference
+
+## Common Vulnerabilities
+
+### None Algorithm Attack
+
+Attack: Attacker changes algorithm to "none" to bypass signature verification.
+
+```javascript
+// VULNERABLE - accepts any algorithm
+const decoded = jwt.verify(token, secret);
+
+// SECURE - explicitly specify allowed algorithms
+const decoded = jwt.verify(token, secret, {
+  algorithms: ['HS256']  // Only accept HS256
+});
+```
+
+### Algorithm Confusion Attack
+
+Attack: Switching from RS256 to HS256 using public key as secret.
+
+```javascript
+// VULNERABLE - auto-detects algorithm
+const decoded = jwt.verify(token, publicKey);
+
+// SECURE - specify expected algorithm
+const decoded = jwt.verify(token, publicKey, {
+  algorithms: ['RS256']  // Only accept RS256
+});
+```
+
+### Weak Secret
+
+Attack: Brute-force weak HMAC secrets.
+
+```javascript
+// VULNERABLE - weak secret
+const token = jwt.sign(payload, 'password123');
+
+// SECURE - strong random secret (256+ bits)
+const crypto = require('crypto');
+const secret = crypto.randomBytes(32);  // 256 bits
+const token = jwt.sign(payload, secret);
+
+// Or use RSA keys
+const privateKey = fs.readFileSync('private.pem');
+const token = jwt.sign(payload, privateKey, { algorithm: 'RS256' });
+```
+
+## Token Sidejacking Prevention
+
+Add fingerprint to prevent stolen token reuse:
+
+```javascript
+const crypto = require('crypto');
+
+// Generate fingerprint on login
+function generateFingerprint() {
+  return crypto.randomBytes(32).toString('hex');
+}
+
+// Create token with fingerprint hash
+function createToken(userId, fingerprint) {
+  const fingerprintHash = crypto
+    .createHash('sha256')
+    .update(fingerprint)
+    .digest('hex');
+
+  return jwt.sign(
+    { sub: userId, fph: fingerprintHash },
+    secret,
+    { expiresIn: '15m' }
+  );
+}
+
+// Set fingerprint as httpOnly cookie
+res.cookie('__Secure-Fgp', fingerprint, {
+  httpOnly: true,
+  secure: true,
+  sameSite: 'Strict',
+  maxAge: 15 * 60 * 1000  // Match token expiry
+});
+
+// Validate both token and fingerprint
+function validateToken(token, fingerprintCookie) {
+  const decoded = jwt.verify(token, secret, { algorithms: ['HS256'] });
+
+  const fingerprintHash = crypto
+    .createHash('sha256')
+    .update(fingerprintCookie)
+    .digest('hex');
+
+  if (decoded.fph !== fingerprintHash) {
+    throw new Error('Invalid fingerprint');
+  }
+
+  return decoded;
+}
+```
+
+## Token Storage (Client-Side)
+
+### Recommended: sessionStorage + Fingerprint Cookie
+
+```javascript
+// Store token in sessionStorage
+sessionStorage.setItem('token', jwt);
+
+// Clear on logout
+sessionStorage.removeItem('token');
+
+// Send in Authorization header
+fetch('/api/data', {
+  headers: {
+    'Authorization': `Bearer ${sessionStorage.getItem('token')}`
+  }
+});
+```
+
+### Alternative: httpOnly Cookie
+
+```javascript
+// Server sets cookie
+res.cookie('token', jwt, {
+  httpOnly: true,     // Not accessible via JavaScript
+  secure: true,       // HTTPS only
+  sameSite: 'Strict', // CSRF protection
+  maxAge: 15 * 60 * 1000
+});
+
+// Need CSRF protection with cookie-based auth
+```
+
+### Avoid: localStorage
+
+```javascript
+// VULNERABLE - persists after browser close, accessible to XSS
+localStorage.setItem('token', jwt);  // Not recommended
+```
+
+## Token Expiration
+
+```javascript
+// Short-lived access tokens (15-60 minutes)
+const accessToken = jwt.sign(payload, secret, { expiresIn: '15m' });
+
+// Longer refresh tokens (days/weeks)
+const refreshToken = jwt.sign(
+  { sub: userId, type: 'refresh' },
+  refreshSecret,
+  { expiresIn: '7d' }
+);
+
+// Refresh endpoint
+app.post('/refresh', async (req, res) => {
+  const { refreshToken } = req.body;
+
+  try {
+    const decoded = jwt.verify(refreshToken, refreshSecret, {
+      algorithms: ['HS256']
+    });
+
+    if (decoded.type !== 'refresh') {
+      throw new Error('Invalid token type');
+    }
+
+    // Check if refresh token is revoked
+    if (await isTokenRevoked(decoded)) {
+      throw new Error('Token revoked');
+    }
+
+    // Issue new access token
+    const newAccessToken = jwt.sign(
+      { sub: decoded.sub },
+      secret,
+      { expiresIn: '15m' }
+    );
+
+    res.json({ accessToken: newAccessToken });
+  } catch (error) {
+    res.status(401).json({ error: 'Invalid refresh token' });
+  }
+});
+```
+
+## Token Revocation
+
+JWTs are stateless, so revocation requires additional mechanisms:
+
+```javascript
+// Denylist approach
+const revokedTokens = new Map();  // Use Redis in production
+
+function revokeToken(token) {
+  const decoded = jwt.verify(token, secret, { algorithms: ['HS256'] });
+  const tokenId = decoded.jti;
+  const expiry = decoded.exp * 1000;
+
+  if (!tokenId || !expiry) {
+    throw new Error('Token missing required revocation claims');
+  }
+
+  // Store until token expires
+  revokedTokens.set(tokenId, expiry);
+
+  // Clean up expired entries periodically
+  setTimeout(() => revokedTokens.delete(tokenId), Math.max(0, expiry - Date.now()));
+}
+
+function isTokenRevoked(decoded) {
+  return Boolean(decoded.jti) && revokedTokens.has(decoded.jti);
+}
+
+// Include jti (JWT ID) in tokens
+const token = jwt.sign(
+  { sub: userId, jti: crypto.randomUUID() },
+  secret,
+  { expiresIn: '15m' }
+);
+```
+
+## Token Information Disclosure
+
+JWTs are base64-encoded, not encrypted. Sensitive data is visible.
+
+```javascript
+// VULNERABLE - sensitive data in payload
+const token = jwt.sign({
+  sub: userId,
+  ssn: '123-45-6789',  // Visible to anyone!
+  salary: 100000
+}, secret);
+
+// SECURE - minimal claims
+const token = jwt.sign({
+  sub: userId,
+  role: 'user'
+}, secret);
+
+// If sensitive data required, encrypt the token
+const encryptedToken = encrypt(token, encryptionKey);
+```
+
+## Validation Middleware
+
+```javascript
+function authenticateToken(req, res, next) {
+  // Get token from header
+  const authHeader = req.headers.authorization;
+  const token = authHeader?.split(' ')[1];  // "Bearer TOKEN"
+
+  if (!token) {
+    return res.status(401).json({ error: 'Token required' });
+  }
+
+  try {
+    // Verify with explicit algorithm
+    const decoded = jwt.verify(token, secret, {
+      algorithms: ['HS256'],
+      issuer: 'myapp',
+      audience: 'myapp-users'
+    });
+
+    // Validate fingerprint if using sidejacking protection
+    const fingerprint = req.cookies['__Secure-Fgp'];
+    if (!validateFingerprint(decoded, fingerprint)) {
+      throw new Error('Invalid fingerprint');
+    }
+
+    // Check revocation
+    if (isTokenRevoked(decoded)) {
+      throw new Error('Token revoked');
+    }
+
+    req.user = decoded;
+    next();
+  } catch (error) {
+    if (error.name === 'TokenExpiredError') {
+      return res.status(401).json({ error: 'Token expired' });
+    }
+    return res.status(403).json({ error: 'Invalid token' });
+  }
+}
+```
+
+## Security Checklist
+
+- [ ] Explicit algorithm specification (never auto-detect)
+- [ ] Strong secret (256+ bits) or RSA keys
+- [ ] Short expiration times (15-60 minutes for access tokens)
+- [ ] Token fingerprint with httpOnly cookie
+- [ ] Validate issuer (iss) and audience (aud) claims
+- [ ] Implement token revocation mechanism
+- [ ] No sensitive data in payload
+- [ ] Store in sessionStorage (not localStorage)
+- [ ] Send via Authorization header
+- [ ] Use HTTPS only
+
+OWASP Reference: https://cheatsheetseries.owasp.org/cheatsheets/JSON_Web_Token_for_Java_Cheat_Sheet.html

package/skills/frontend-security/references/nodejs-npm-security.md

@@ -0,0 +1,261 @@
+# Node.js and NPM Security Reference
+
+## NPM Dependency Security
+
+### Audit Commands
+
+```bash
+# Check for vulnerabilities
+npm audit
+
+# Fix automatically where possible
+npm audit fix
+
+# Force fix (may have breaking changes)
+npm audit fix --force
+
+# Generate detailed report
+npm audit --json > audit-report.json
+```
+
+### Lockfile Enforcement
+
+```bash
+# Always use lockfile in CI/CD
+npm ci  # Instead of npm install
+
+# Verify lockfile integrity
+npm ci --ignore-scripts  # Safer for first run
+```
+
+### Package.json Security
+
+```json
+{
+  "scripts": {
+    "preinstall": "npx npm-force-resolutions",
+    "postinstall": "npm audit"
+  },
+  "overrides": {
+    "vulnerable-package": "^2.0.0"
+  }
+}
+```
+
+## Dangerous Functions
+
+### Code Execution
+
+```javascript
+// DANGEROUS - never use with user input
+eval(userInput);
+new Function(userInput);
+vm.runInThisContext(userInput);
+require(userInput);
+
+// DANGEROUS - setTimeout/setInterval with strings
+setTimeout(userInput, 1000);  // Executes as code
+
+// SAFE - pass functions instead
+setTimeout(() => { /* code */ }, 1000);
+```
+
+### Child Process Injection
+
+```javascript
+// DANGEROUS - command injection
+const { exec } = require('child_process');
+exec(`ls ${userInput}`);  // Shell injection
+
+// SAFER - use execFile with arguments array
+const { execFile } = require('child_process');
+execFile('ls', [userInput], callback);  // Arguments not interpreted by shell
+
+// SAFEST - use spawn with shell: false
+const { spawn } = require('child_process');
+spawn('ls', [userInput], { shell: false });
+```
+
+### File System
+
+```javascript
+const path = require('path');
+const fs = require('fs');
+
+// DANGEROUS - path traversal
+const filePath = `/uploads/${userInput}`;
+
+// SAFE - validate and resolve path
+function safeReadFile(userInput, baseDir) {
+  const basePath = path.resolve(baseDir);
+  const safePath = path.resolve(basePath, userInput);
+  const relativePath = path.relative(basePath, safePath);
+
+  // Verify path is within allowed directory
+  if (relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
+    throw new Error('Invalid file path');
+  }
+
+  return fs.readFileSync(safePath);
+}
+```
+
+## Request Handling
+
+### Rate Limiting
+
+```javascript
+const rateLimit = require('express-rate-limit');
+
+const limiter = rateLimit({
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 100, // Limit each IP to 100 requests per window
+  message: 'Too many requests',
+  standardHeaders: true,
+  legacyHeaders: false
+});
+
+app.use(limiter);
+
+// Stricter limits for auth endpoints
+const authLimiter = rateLimit({
+  windowMs: 60 * 60 * 1000, // 1 hour
+  max: 5, // 5 attempts per hour
+  message: 'Too many login attempts'
+});
+
+app.use('/api/login', authLimiter);
+```
+
+### Request Size Limits
+
+```javascript
+const express = require('express');
+const app = express();
+
+// Limit JSON body size
+app.use(express.json({ limit: '100kb' }));
+
+// Limit URL-encoded body
+app.use(express.urlencoded({ extended: true, limit: '100kb' }));
+
+// Limit file uploads
+const multer = require('multer');
+const upload = multer({
+  limits: { fileSize: 5 * 1024 * 1024 } // 5MB
+});
+```
+
+### Timeout Configuration
+
+```javascript
+const server = app.listen(3000);
+
+// Set timeouts
+server.setTimeout(30000); // 30 seconds
+server.keepAliveTimeout = 65000;
+server.headersTimeout = 66000;
+```
+
+## Secure Headers
+
+```javascript
+const helmet = require('helmet');
+
+app.use(helmet({
+  contentSecurityPolicy: {
+    directives: {
+      defaultSrc: ["'self'"],
+      scriptSrc: ["'self'"],
+      styleSrc: ["'self'", "'unsafe-inline'"],
+      imgSrc: ["'self'", "data:", "https:"],
+      objectSrc: ["'none'"],
+      upgradeInsecureRequests: []
+    }
+  },
+  hsts: {
+    maxAge: 31536000,
+    includeSubDomains: true,
+    preload: true
+  },
+  referrerPolicy: { policy: 'strict-origin-when-cross-origin' },
+  frameguard: { action: 'deny' }
+}));
+```
+
+## Error Handling
+
+```javascript
+// Global error handler - don't expose details
+app.use((err, req, res, next) => {
+  // Log full error internally
+  console.error(err);
+
+  // Send generic message to client
+  res.status(500).json({
+    error: 'An unexpected error occurred'
+  });
+});
+
+// Async error wrapper
+const asyncHandler = fn => (req, res, next) => {
+  Promise.resolve(fn(req, res, next)).catch(next);
+};
+
+app.get('/data', asyncHandler(async (req, res) => {
+  const data = await fetchData();
+  res.json(data);
+}));
+```
+
+## Environment Variables
+
+```javascript
+// NEVER commit secrets to code
+// Use environment variables
+const apiKey = process.env.API_KEY;
+
+// Validate required env vars at startup
+const required = ['API_KEY', 'DB_URL', 'SESSION_SECRET'];
+required.forEach(varName => {
+  if (!process.env[varName]) {
+    console.error(`Missing required env var: ${varName}`);
+    process.exit(1);
+  }
+});
+```
+
+## Regex DoS Prevention
+
+```javascript
+// DANGEROUS - evil regex (catastrophic backtracking)
+const evilRegex = /^(a+)+$/;
+evilRegex.test('aaaaaaaaaaaaaaaaaaaaaaaaaaa!'); // Hangs
+
+// Heuristic only: safe-regex can have false positives/negatives for ReDoS
+const safe = require('safe-regex');
+if (!safe(userProvidedRegex)) {
+  throw new Error('Unsafe regex pattern');
+}
+
+// Preferred for untrusted patterns: use RE2 for guaranteed linear time
+const RE2 = require('re2');
+const pattern = new RE2(userProvidedRegex);
+```
+
+## NPM Security Checklist
+
+- [ ] Run `npm audit` regularly and in CI/CD
+- [ ] Use `npm ci` instead of `npm install` in CI
+- [ ] Enable 2FA on npm account
+- [ ] Use lockfiles and commit them
+- [ ] Review new dependencies before installation
+- [ ] Use `--ignore-scripts` for untrusted packages
+- [ ] Set up automated vulnerability scanning (Snyk, Dependabot)
+- [ ] Keep dependencies updated
+- [ ] Avoid typosquatting by double-checking package names
+- [ ] Use `npm-shrinkwrap.json` for published packages
+
+OWASP References:
+- https://cheatsheetseries.owasp.org/cheatsheets/Nodejs_Security_Cheat_Sheet.html
+- https://cheatsheetseries.owasp.org/cheatsheets/NPM_Security_Cheat_Sheet.html

package/skills/frontend-security/references/xss-prevention.md

@@ -0,0 +1,163 @@
+# XSS Prevention Reference
+
+## Output Encoding Rules
+
+Apply context-appropriate encoding for all untrusted data:
+
+| Context | Encoding Method | Example |
+|---------|-----------------|---------|
+| HTML Body | HTML Entity Encoding | `<script>` |
+| HTML Attribute | Attribute Encoding | `"onclick"` |
+| JavaScript | JavaScript Encoding | `\x3cscript\x3e` |
+| CSS | CSS Encoding | `\3c script\3e` |
+| URL Parameter | URL Encoding | `%3Cscript%3E` |
+
+## Safe vs Unsafe Sinks
+
+### Unsafe Sinks (Never use with untrusted data)
+
+```javascript
+// Execution sinks - NEVER use with user input
+element.innerHTML = userInput;        // XSS
+element.outerHTML = userInput;        // XSS
+document.write(userInput);            // XSS
+document.writeln(userInput);          // XSS
+
+// JavaScript execution sinks
+eval(userInput);                      // XSS
+new Function(userInput);              // XSS
+setTimeout(userInput, time);          // XSS if string
+setInterval(userInput, time);         // XSS if string
+
+// URL sinks
+location.href = userInput;            // XSS
+location.assign(userInput);           // XSS
+location.replace(userInput);          // XSS
+window.open(userInput);               // XSS
+```
+
+### Safe Alternatives
+
+```javascript
+// Safe text insertion
+element.textContent = userInput;      // Safe
+element.innerText = userInput;        // Safe
+
+// Safe attribute setting (for safe attributes)
+element.setAttribute('title', userInput); // Safe for non-event attributes
+
+// Safe URL handling
+const url = new URL(userInput, window.location.origin);
+if (url.protocol === 'https:') {
+  location.href = url.href;
+}
+```
+
+## HTML Sanitization
+
+When HTML must be rendered, use sanitization:
+
+```javascript
+// Using DOMPurify (recommended)
+import DOMPurify from 'dompurify';
+element.innerHTML = DOMPurify.sanitize(userInput);
+
+// With configuration
+const clean = DOMPurify.sanitize(dirty, {
+  ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'a'],
+  ALLOWED_ATTR: ['href', 'title']
+});
+
+// Browser Sanitizer API (when available)
+const sanitizer = new Sanitizer({
+  allowElements: ['b', 'i', 'em', 'strong', 'a'],
+  allowAttributes: { 'href': ['a'] }
+});
+element.setHTML(userInput, { sanitizer });
+```
+
+## Framework-Specific XSS Risks
+
+### React
+
+```jsx
+// DANGEROUS - bypasses React's protection
+<div dangerouslySetInnerHTML={{ __html: userInput }} />
+
+// SAFE - React auto-escapes
+<div>{userInput}</div>
+
+// DANGEROUS - href with javascript:
+<a href={userInput}>Link</a> // If userInput = "javascript:alert(1)"
+
+// SAFE - validate URL protocol
+const safeUrl = userInput.startsWith('https://') ? userInput : '#';
+<a href={safeUrl}>Link</a>
+```
+
+### Twig
+
+```twig
+{# DANGEROUS - raw filter bypasses escaping #}
+{{ userInput|raw }}
+
+{# DANGEROUS - autoescape disabled #}
+{% autoescape false %}
+  {{ userInput }}
+{% endautoescape %}
+
+{# SAFE - auto-escaped by default #}
+{{ userInput }}
+
+{# SAFE - explicit escaping #}
+{{ userInput|e('html') }}
+{{ userInput|e('js') }}
+{{ userInput|e('url') }}
+```
+
+### Astro
+
+```astro
+<!-- DANGEROUS - set:html bypasses escaping -->
+<div set:html={userInput} />
+
+<!-- SAFE - auto-escaped -->
+<div>{userInput}</div>
+```
+
+## URL Validation
+
+```javascript
+function isValidUrl(input) {
+  try {
+    const url = new URL(input);
+    return ['http:', 'https:'].includes(url.protocol);
+  } catch {
+    return false;
+  }
+}
+
+// Prevent javascript: URLs
+function sanitizeHref(input) {
+  if (!input) return '#';
+  const trimmed = input.trim().toLowerCase();
+  if (trimmed.startsWith('javascript:') ||
+      trimmed.startsWith('data:') ||
+      trimmed.startsWith('vbscript:')) {
+    return '#';
+  }
+  return input;
+}
+```
+
+## Content-Type Headers
+
+Always set appropriate Content-Type headers:
+
+```javascript
+// Express.js
+res.setHeader('Content-Type', 'application/json');
+res.setHeader('X-Content-Type-Options', 'nosniff');
+```
+
+OWASP Reference: https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html