@schalkneethling/toolkit 0.2.0 → 0.4.0

package/skills/frontend-security/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: frontend-security
+description: Audit frontend codebases for security vulnerabilities and bad practices. Use when performing security reviews, auditing code for XSS/CSRF/DOM vulnerabilities, checking Content Security Policy configurations, validating input handling, reviewing file upload security, or examining Node.js/NPM dependencies. Target frameworks include web platform (vanilla HTML/CSS/JS), React, Astro, Twig templates, Node.js, and Bun. Based on OWASP security guidelines.
+---
+
+# Frontend Security Audit Skill
+
+Perform comprehensive security audits of frontend codebases to identify vulnerabilities, bad practices, and missing protections.
+
+## Audit Process
+
+1. **Scan for dangerous patterns** - Search codebase for known vulnerability indicators
+2. **Review framework-specific risks** - Check for framework security bypass patterns
+3. **Validate defensive measures** - Verify CSP, CSRF tokens, input validation
+4. **Check dependencies** - Review npm/node dependencies for vulnerabilities
+5. **Report findings** - Categorize by severity with remediation guidance
+
+## Critical Vulnerability Patterns to Search
+
+### XSS Indicators (Search Priority: HIGH)
+
+```bash
+# React dangerous patterns
+grep -rn "dangerouslySetInnerHTML" --include="*.jsx" --include="*.tsx" --include="*.js"
+
+# Direct DOM manipulation
+grep -rn "\.innerHTML\s*=" --include="*.js" --include="*.ts" --include="*.jsx" --include="*.tsx"
+grep -rn "\.outerHTML\s*=" --include="*.js" --include="*.ts"
+grep -rn "document\.write" --include="*.js" --include="*.ts"
+
+# URL-based injection
+grep -rn "location\.href\s*=" --include="*.js" --include="*.ts"
+grep -rn "location\.replace" --include="*.js" --include="*.ts"
+grep -rn "window\.open" --include="*.js" --include="*.ts"
+
+# Eval and code execution
+grep -rn "eval\s*(" --include="*.js" --include="*.ts"
+grep -rn "new Function\s*(" --include="*.js" --include="*.ts"
+grep -rn "setTimeout\s*(\s*['\"]" --include="*.js" --include="*.ts"
+grep -rn "setInterval\s*(\s*['\"]" --include="*.js" --include="*.ts"
+
+# Twig unescaped output
+grep -rn "|raw" --include="*.twig" --include="*.html.twig"
+grep -rn "{% autoescape false %}" --include="*.twig"
+```
+
+### CSRF Indicators
+
+```bash
+# Forms without CSRF tokens
+grep -rn "<form" --include="*.html" --include="*.jsx" --include="*.tsx" --include="*.twig"
+
+# State-changing requests without protection
+grep -rn "fetch\s*(" --include="*.js" --include="*.ts" | grep -E "(POST|PUT|DELETE|PATCH)"
+grep -rn "axios\.(post|put|delete|patch)" --include="*.js" --include="*.ts"
+```
+
+### Sensitive Data Exposure
+
+```bash
+# localStorage/sessionStorage with sensitive data
+grep -rn "localStorage\." --include="*.js" --include="*.ts"
+grep -rn "sessionStorage\." --include="*.js" --include="*.ts"
+
+# Hardcoded secrets
+grep -rn "api[_-]?key\s*[:=]" --include="*.js" --include="*.ts" --include="*.env"
+grep -rn "secret\s*[:=]" --include="*.js" --include="*.ts"
+grep -rn "password\s*[:=]" --include="*.js" --include="*.ts"
+```
+
+## Reference Documentation
+
+Load these references based on findings:
+
+- **XSS vulnerabilities found**: See `references/xss-prevention.md`
+- **CSRF concerns**: See `references/csrf-protection.md`
+- **DOM manipulation issues**: See `references/dom-security.md`
+- **CSP review needed**: See `references/csp-configuration.md`
+- **Input handling issues**: See `references/input-validation.md`
+- **Node.js/NPM audit**: See `references/nodejs-npm-security.md`
+- **Framework-specific patterns**: See `references/framework-patterns.md`
+- **File upload handling**: See `references/file-upload-security.md`
+- **JWT implementation**: See `references/jwt-security.md`
+
+## Severity Classification
+
+**CRITICAL** - Exploitable XSS, authentication bypass, secrets exposure
+**HIGH** - Missing CSRF protection, unsafe DOM manipulation, SQL injection vectors
+**MEDIUM** - Weak CSP, missing security headers, improper input validation
+**LOW** - Informational disclosure, deprecated functions, suboptimal practices
+
+## Report Format
+
+```markdown
+## Security Audit Report
+
+### Summary
+- Critical: X findings
+- High: X findings
+- Medium: X findings
+- Low: X findings
+
+### Critical Findings
+
+#### [CRITICAL-001] Title
+- **Location**: file:line
+- **Pattern**: Code snippet
+- **Risk**: Description of the vulnerability
+- **Remediation**: How to fix
+- **Reference**: OWASP link
+
+### High Findings
+[...]
+```
+
+## OWASP Reference Links
+
+For comprehensive guidance, consult these OWASP cheatsheets directly:
+
+- XSS Prevention: https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html
+- DOM XSS Prevention: https://cheatsheetseries.owasp.org/cheatsheets/DOM_based_XSS_Prevention_Cheat_Sheet.html
+- CSRF Prevention: https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html
+- CSP: https://cheatsheetseries.owasp.org/cheatsheets/Content_Security_Policy_Cheat_Sheet.html
+- Input Validation: https://cheatsheetseries.owasp.org/cheatsheets/Input_Validation_Cheat_Sheet.html
+- HTML5 Security: https://cheatsheetseries.owasp.org/cheatsheets/HTML5_Security_Cheat_Sheet.html
+- DOM Clobbering: https://cheatsheetseries.owasp.org/cheatsheets/DOM_Clobbering_Prevention_Cheat_Sheet.html
+- Node.js Security: https://cheatsheetseries.owasp.org/cheatsheets/Nodejs_Security_Cheat_Sheet.html
+- NPM Security: https://cheatsheetseries.owasp.org/cheatsheets/NPM_Security_Cheat_Sheet.html
+- AJAX Security: https://cheatsheetseries.owasp.org/cheatsheets/AJAX_Security_Cheat_Sheet.html
+- File Upload: https://cheatsheetseries.owasp.org/cheatsheets/File_Upload_Cheat_Sheet.html
+- Error Handling: https://cheatsheetseries.owasp.org/cheatsheets/Error_Handling_Cheat_Sheet.html
+- JWT Security: https://cheatsheetseries.owasp.org/cheatsheets/JSON_Web_Token_for_Java_Cheat_Sheet.html
+- User Privacy: https://cheatsheetseries.owasp.org/cheatsheets/User_Privacy_Protection_Cheat_Sheet.html
+- gRPC Security: https://cheatsheetseries.owasp.org/cheatsheets/gRPC_Security_Cheat_Sheet.html

package/skills/frontend-security/references/csp-configuration.md

@@ -0,0 +1,191 @@
+# Content Security Policy Reference
+
+## Strict CSP Configuration
+
+### Nonce-Based (Recommended)
+
+```http
+Content-Security-Policy:
+  script-src 'nonce-{random}' 'strict-dynamic';
+  object-src 'none';
+  base-uri 'none';
+```
+
+Implementation:
+
+```javascript
+// Generate unique nonce per request
+const crypto = require('crypto');
+const nonce = crypto.randomBytes(16).toString('base64');
+
+// Set header
+res.setHeader('Content-Security-Policy',
+  `script-src 'nonce-${nonce}' 'strict-dynamic'; object-src 'none'; base-uri 'none';`
+);
+
+// Include nonce in script tags
+res.send(`<script nonce="${nonce}">/* safe code */</script>`);
+```
+
+### Hash-Based (For Static Scripts)
+
+```http
+Content-Security-Policy:
+  script-src 'sha256-{hash}' 'strict-dynamic';
+  object-src 'none';
+  base-uri 'none';
+```
+
+Generate hash:
+
+```bash
+echo -n 'console.log("hello");' | openssl sha256 -binary | openssl base64
+```
+
+## Essential Directives
+
+| Directive | Purpose | Recommended Value |
+|-----------|---------|-------------------|
+| `default-src` | Fallback for other directives | `'self'` |
+| `script-src` | JavaScript sources | `'nonce-{random}' 'strict-dynamic'` |
+| `style-src` | CSS sources | `'self' 'unsafe-inline'` (or nonces) |
+| `img-src` | Image sources | `'self' data: https:` |
+| `font-src` | Font sources | `'self'` |
+| `connect-src` | AJAX/WebSocket/Fetch | `'self' https://api.example.com` |
+| `frame-src` | iframe sources | `'none'` or specific origins |
+| `object-src` | Plugin content | `'none'` |
+| `base-uri` | Base URL restrictions | `'none'` |
+| `form-action` | Form submission targets | `'self'` |
+| `frame-ancestors` | Who can embed page | `'self'` or `'none'` |
+
+## Framework Integration
+
+### Express.js
+
+```javascript
+const helmet = require('helmet');
+
+// Nonce middleware
+app.use((req, res, next) => {
+  res.locals.nonce = crypto.randomBytes(16).toString('base64');
+  next();
+});
+
+app.use(helmet.contentSecurityPolicy({
+  directives: {
+    defaultSrc: ["'self'"],
+    scriptSrc: [(req, res) => `'nonce-${res.locals.nonce}'`, "'strict-dynamic'"],
+    styleSrc: ["'self'", "'unsafe-inline'"],
+    imgSrc: ["'self'", "data:", "https:"],
+    objectSrc: ["'none'"],
+    baseUri: ["'none'"],
+    formAction: ["'self'"],
+    frameAncestors: ["'self'"]
+  }
+}));
+```
+
+### Astro
+
+```javascript
+// astro.config.mjs
+export default defineConfig({
+  vite: {
+    plugins: [{
+      name: 'csp-plugin',
+      configureServer(server) {
+        server.middlewares.use((req, res, next) => {
+          res.setHeader('Content-Security-Policy',
+            "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline';"
+          );
+          next();
+        });
+      }
+    }]
+  }
+});
+```
+
+### Meta Tag (Fallback)
+
+```html
+<meta http-equiv="Content-Security-Policy"
+      content="default-src 'self'; script-src 'self' 'nonce-abc123';">
+```
+
+**Note**: Meta tag CSP cannot set `frame-ancestors`, `report-uri`, or `sandbox`.
+
+## Report-Only Mode
+
+Test policies without enforcement:
+
+```http
+Content-Security-Policy-Report-Only:
+  default-src 'self';
+  script-src 'self';
+  report-uri /csp-report;
+```
+
+Report endpoint:
+
+```javascript
+app.post('/csp-report', express.json({ type: 'application/csp-report' }), (req, res) => {
+  console.log('CSP Violation:', req.body);
+  res.status(204).end();
+});
+```
+
+## Common Violations and Fixes
+
+### Inline Scripts
+
+```html
+<!-- Violation: inline script -->
+<script>alert('hello');</script>
+
+<!-- Fix: add nonce -->
+<script nonce="abc123">alert('hello');</script>
+
+<!-- Or: move to external file -->
+<script src="/js/app.js"></script>
+```
+
+### Inline Event Handlers
+
+```html
+<!-- Violation: inline event handler -->
+<button onclick="handleClick()">Click</button>
+
+<!-- Fix: use addEventListener -->
+<button id="myBtn">Click</button>
+<script nonce="abc123">
+  document.getElementById('myBtn').addEventListener('click', handleClick);
+</script>
+```
+
+### Inline Styles
+
+```html
+<!-- Violation: style attribute -->
+<div style="color: red;">Text</div>
+
+<!-- Fix: use classes -->
+<div class="text-red">Text</div>
+
+<!-- Or: add nonce to style tags -->
+<style nonce="abc123">.text-red { color: red; }</style>
+```
+
+## Security Headers Companion
+
+Deploy CSP with these additional headers:
+
+```http
+X-Content-Type-Options: nosniff
+X-Frame-Options: DENY
+X-XSS-Protection: 0
+Referrer-Policy: strict-origin-when-cross-origin
+Permissions-Policy: geolocation=(), microphone=(), camera=()
+```
+
+OWASP Reference: https://cheatsheetseries.owasp.org/cheatsheets/Content_Security_Policy_Cheat_Sheet.html

package/skills/frontend-security/references/csrf-protection.md

@@ -0,0 +1,327 @@
+# CSRF Protection Reference
+
+## Token-Based Protection
+
+### Synchronizer Token Pattern
+
+Generate unique per-session tokens and validate on state-changing requests:
+
+```javascript
+// Server-side token generation (Node.js)
+const crypto = require('crypto');
+
+function generateCSRFToken(session) {
+  const token = crypto.randomBytes(32).toString('hex');
+  session.csrfToken = token;
+  return token;
+}
+
+// Middleware validation
+function validateCSRF(req, res, next) {
+  const token = req.headers['x-csrf-token'] || req.body._csrf;
+  const sessionToken = req.session.csrfToken;
+
+  if (typeof token !== 'string' || typeof sessionToken !== 'string') {
+    return res.status(403).json({ error: 'Invalid CSRF token' });
+  }
+
+  const tokenBuffer = Buffer.from(token);
+  const sessionTokenBuffer = Buffer.from(sessionToken);
+
+  if (
+    tokenBuffer.length !== sessionTokenBuffer.length ||
+    !crypto.timingSafeEqual(tokenBuffer, sessionTokenBuffer)
+  ) {
+    return res.status(403).json({ error: 'Invalid CSRF token' });
+  }
+  next();
+}
+```
+
+### Double Submit Cookie Pattern
+
+```javascript
+// Set CSRF cookie
+res.cookie('csrf_token', token, {
+  httpOnly: false,  // Must be readable by JavaScript
+  secure: true,
+  sameSite: 'Strict'
+});
+
+// Client sends token in header
+fetch('/api/action', {
+  method: 'POST',
+  headers: {
+    'X-CSRF-Token': getCookie('csrf_token')
+  }
+});
+
+// Server validates cookie matches header
+function validateDoubleSubmit(req) {
+  const cookieToken = req.cookies.csrf_token;
+  const headerToken = req.headers['x-csrf-token'];
+  return cookieToken && cookieToken === headerToken;
+}
+```
+
+## SameSite Cookie Attribute
+
+```javascript
+// Strict - never sent cross-site
+res.cookie('session', value, { sameSite: 'Strict', secure: true, httpOnly: true });
+
+// Lax - sent for top-level GET navigations (default in modern browsers)
+res.cookie('session', value, { sameSite: 'Lax', secure: true, httpOnly: true });
+
+// None - requires Secure flag, sent cross-site
+res.cookie('session', value, { sameSite: 'None', secure: true, httpOnly: true });
+```
+
+**Recommendation**: Use `SameSite=Strict` for session cookies when possible, `Lax` as minimum.
+
+## Fetch Metadata Headers
+
+Validate request origin using Sec-Fetch-* headers:
+
+```javascript
+function validateFetchMetadata(req, res, next) {
+  const site = req.headers['sec-fetch-site'];
+  const mode = req.headers['sec-fetch-mode'];
+  const dest = req.headers['sec-fetch-dest'];
+  const method = req.method;
+
+  // Allow same-origin requests
+  if (site === 'same-origin') return next();
+
+  // Allow user-initiated browser navigations
+  if (site === 'none') return next();
+
+  // Allow same-site top-level navigations and safe methods
+  if (
+    site === 'same-site' &&
+    (mode === 'navigate' || ['GET', 'HEAD', 'OPTIONS'].includes(method))
+  ) {
+    return next();
+  }
+
+  return res.status(403).json({ error: 'Fetch metadata validation failed' });
+}
+```
+
+## Framework Integration
+
+### Express.js with Signed Double-Submit Tokens
+
+```javascript
+const crypto = require('crypto');
+
+const CSRF_COOKIE_NAME = 'csrf_token';
+const CSRF_SECRET = Buffer.from(process.env.CSRF_SECRET, 'hex');
+
+function signToken(sessionId, nonce) {
+  return crypto
+    .createHmac('sha256', CSRF_SECRET)
+    .update(`${sessionId}:${nonce}`)
+    .digest('base64url');
+}
+
+function constantTimeEqual(value, expected) {
+  if (typeof value !== 'string' || typeof expected !== 'string') return false;
+
+  const valueBuffer = Buffer.from(value);
+  const expectedBuffer = Buffer.from(expected);
+
+  return (
+    valueBuffer.length === expectedBuffer.length &&
+    crypto.timingSafeEqual(valueBuffer, expectedBuffer)
+  );
+}
+
+function generateToken(req) {
+  const nonce = crypto.randomBytes(32).toString('base64url');
+  const signature = signToken(req.session.id, nonce);
+  return `${nonce}.${signature}`;
+}
+
+function sendToken(req, res, next) {
+  const token = generateToken(req);
+
+  res.cookie(CSRF_COOKIE_NAME, token, {
+    httpOnly: true,
+    secure: true,
+    sameSite: 'Strict'
+  });
+
+  res.locals.csrfToken = token;
+  next();
+}
+
+function verifyToken(req, res, next) {
+  const token = req.headers['x-csrf-token'] || req.body._csrf;
+  const cookieToken = req.cookies[CSRF_COOKIE_NAME];
+
+  if (!constantTimeEqual(token, cookieToken)) {
+    return res.status(403).json({ error: 'Invalid CSRF token' });
+  }
+
+  const [nonce, signature, extra] = cookieToken.split('.');
+  if (extra || !nonce || !signature) {
+    return res.status(403).json({ error: 'Invalid CSRF token' });
+  }
+
+  if (!constantTimeEqual(signature, signToken(req.session.id, nonce))) {
+    return res.status(403).json({ error: 'Invalid CSRF token' });
+  }
+
+  next();
+}
+
+app.get('/form', sendToken, (req, res) => {
+  res.render('form', { csrfToken: res.locals.csrfToken });
+});
+
+app.post('/submit', verifyToken, (req, res) => {
+  res.json({ ok: true });
+});
+```
+
+Example tests for token issuance and verification:
+
+```javascript
+const assert = require('node:assert/strict');
+const test = require('node:test');
+
+test('sendToken issues a cookie and exposes a form token', () => {
+  const req = { session: { id: 'session-123' } };
+  const res = {
+    locals: {},
+    cookie(name, value, options) {
+      this.cookieArgs = { name, value, options };
+    }
+  };
+
+  sendToken(req, res, () => {});
+
+  assert.equal(res.cookieArgs.name, CSRF_COOKIE_NAME);
+  assert.equal(res.locals.csrfToken, res.cookieArgs.value);
+  assert.equal(res.cookieArgs.options.httpOnly, true);
+  assert.equal(res.cookieArgs.options.sameSite, 'Strict');
+});
+
+test('verifyToken accepts a matching signed token', () => {
+  const req = { session: { id: 'session-123' } };
+  const token = generateToken(req);
+  let called = false;
+
+  verifyToken(
+    {
+      ...req,
+      headers: { 'x-csrf-token': token },
+      body: {},
+      cookies: { [CSRF_COOKIE_NAME]: token }
+    },
+    {},
+    () => {
+      called = true;
+    }
+  );
+
+  assert.equal(called, true);
+});
+
+test('verifyToken rejects mismatched or tampered tokens', () => {
+  const req = {
+    session: { id: 'session-123' },
+    headers: { 'x-csrf-token': 'tampered.token' },
+    body: {},
+    cookies: { [CSRF_COOKIE_NAME]: generateToken({ session: { id: 'session-123' } }) }
+  };
+  const res = {
+    status(code) {
+      this.statusCode = code;
+      return this;
+    },
+    json(body) {
+      this.body = body;
+    }
+  };
+
+  verifyToken(req, res, () => {});
+
+  assert.equal(res.statusCode, 403);
+  assert.deepEqual(res.body, { error: 'Invalid CSRF token' });
+});
+```
+
+### React Forms
+
+```jsx
+function Form({ csrfToken }) {
+  const handleSubmit = async (e) => {
+    e.preventDefault();
+    await fetch('/api/submit', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-CSRF-Token': csrfToken
+      },
+      body: JSON.stringify(formData)
+    });
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input type="hidden" name="_csrf" value={csrfToken} />
+      {/* form fields */}
+    </form>
+  );
+}
+```
+
+### Twig Forms
+
+```twig
+<form method="post" action="/submit">
+  <input type="hidden" name="_csrf_token" value="{{ csrf_token('form_name') }}">
+  <!-- form fields -->
+</form>
+```
+
+## Client-Side CSRF (AJAX)
+
+Protect against CSRF in single-page applications:
+
+```javascript
+// Set up axios defaults
+import axios from 'axios';
+
+axios.defaults.xsrfCookieName = 'csrf_token';
+axios.defaults.xsrfHeaderName = 'X-CSRF-Token';
+axios.defaults.withCredentials = true;
+
+// Or with fetch
+async function secureFetch(url, options = {}) {
+  const csrfToken = document.querySelector('meta[name="csrf-token"]')?.content;
+
+  return fetch(url, {
+    ...options,
+    credentials: 'same-origin',
+    headers: {
+      ...options.headers,
+      'X-CSRF-Token': csrfToken
+    }
+  });
+}
+```
+
+## Verification Checklist
+
+- [ ] All state-changing endpoints require CSRF tokens
+- [ ] Tokens are cryptographically random (≥128 bits)
+- [ ] Tokens are tied to user session
+- [ ] Tokens validated server-side before processing
+- [ ] SameSite cookie attribute set appropriately
+- [ ] Fetch Metadata headers validated for sensitive endpoints
+- [ ] GET requests are idempotent (no state changes)
+
+OWASP Reference: https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html