@schalkneethling/toolkit 0.1.5 → 0.3.0

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