@schalkneethling/calavera-skill-frontend-security 0.2.0-next.2

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

@@ -0,0 +1,383 @@
+# 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();
+}
+```
+
+### Naive Double Submit Cookie Pattern (Insufficient Alone)
+
+Do not rely on a plain "cookie equals header" comparison as the main CSRF
+defense. Use signed, session-bound double-submit tokens when the synchronizer
+token pattern is not practical.
+
+```javascript
+// Recognition-only pseudocode for audits. Do not paste into production.
+// If all the server checks is:
+//
+//   cookie.csrf_token === header["x-csrf-token"]
+//
+// then an attacker who can set or inject the cookie value may be able to satisfy
+// both sides. Replace this pattern with a signed, session-bound token flow such
+// as the Express.js example below.
+```
+
+## 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 as a layered control. Fetch
+Metadata does not replace CSRF tokens for cookie-authenticated state-changing
+requests. `Sec-Fetch-Site: none` usually represents user-initiated browser
+navigations and should be allowed only for safe top-level navigations.
+`same-site` can include sibling subdomains, so allow it only when every same-site
+origin shares the same trust boundary.
+
+```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;
+  const safeMethod = ["GET", "HEAD", "OPTIONS"].includes(method);
+  const trustSameSiteSubdomains = false;
+
+  // Absence is not proof of safety. Continue only to rely on CSRF tokens and
+  // Origin/Referer validation in later middleware.
+  if (!site) return next();
+
+  // Allow same-origin requests
+  if (site === "same-origin") return next();
+
+  // Same-site can include sibling subdomains. Only allow it where those
+  // subdomains share the same trust boundary, and do not use it to permit
+  // state-changing requests without CSRF token validation.
+  if (site === "same-site" && trustSameSiteSubdomains && safeMethod) {
+    return next();
+  }
+
+  // Allow browser-initiated top-level navigations only for safe methods.
+  if (site === "none" && mode === "navigate" && dest === "document" && safeMethod) {
+    return next();
+  }
+
+  return res.status(403).json({ error: "Fetch metadata validation failed" });
+}
+```
+
+## Origin and Referer Checks
+
+Check `Origin` for state-changing requests and fall back to `Referer` only when
+needed. Treat missing headers according to the endpoint risk and client support.
+
+```javascript
+function validateOrigin(req, res, next) {
+  const expectedOrigin = "https://app.example.com";
+  const origin = req.headers.origin;
+  const referer = req.headers.referer;
+
+  if (origin) {
+    if (origin !== expectedOrigin) {
+      return res.status(403).json({ error: "Invalid origin" });
+    }
+    return next();
+  }
+
+  if (referer) {
+    try {
+      if (new URL(referer).origin !== expectedOrigin) {
+        return res.status(403).json({ error: "Invalid referer" });
+      }
+      return next();
+    } catch {
+      return res.status(403).json({ error: "Invalid referer" });
+    }
+  }
+
+  return res.status(403).json({ error: "Missing origin" });
+}
+```
+
+## Framework Integration
+
+### Express.js with Signed Double-Submit Tokens
+
+This server-rendered variant stores the signed token in an `httpOnly` cookie and
+also injects the same token into the form response. Do not combine this exact
+cookie setting with client libraries that expect JavaScript to read the CSRF
+cookie automatically. For AJAX-only clients, inject the token into the page or
+use a readable signed CSRF cookie only when that exposure is an accepted tradeoff;
+the server must still verify the signature and session binding.
+
+Install body parsing, session, and cookie parsing middleware before these handlers. Missing
+session or cookie state must fail closed rather than throw or bypass validation.
+
+```javascript
+const crypto = require("crypto");
+
+const CSRF_COOKIE_NAME = "csrf_token";
+if (!/^[a-f0-9]{64,}$/i.test(process.env.CSRF_SECRET || "")) {
+  throw new Error("CSRF_SECRET must be a hex-encoded secret with at least 32 bytes of entropy");
+}
+
+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) {
+  if (typeof req.session?.id !== "string") return null;
+  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);
+  if (!token) return res.status(403).json({ error: "Invalid CSRF state" });
+
+  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];
+  const sessionId = req.session?.id;
+
+  if (typeof sessionId !== "string" || !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(sessionId, 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 AJAX requests by sending a server-provided CSRF token in a header. Avoid
+using a plain cookie-to-header mirror as the only defense; the token must still
+be signed and session-bound or backed by a server-side synchronizer token.
+
+```javascript
+// If the server intentionally exposes a signed CSRF cookie to JavaScript:
+import axios from "axios";
+
+axios.defaults.xsrfCookieName = "csrf_token";
+axios.defaults.xsrfHeaderName = "X-CSRF-Token";
+axios.defaults.withCredentials = true;
+
+// Prefer server-rendered meta tags or a bootstrap response when using 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
+- [ ] Origin or Referer validated for state-changing requests
+- [ ] GET requests are idempotent (no state changes)
+
+OWASP Reference: https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html

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

@@ -0,0 +1,263 @@
+# 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
+
+// SAFER - only allow attributes whose semantics are plain text in this element.
+// Avoid user-controlled id/name because they can contribute to DOM clobbering.
+const safeAttributes = ["title", "alt", "aria-label", "data-value"];
+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);
+
+// SAFER - parse, normalize, and enforce destination policy.
+function normalizeAllowedUrl(input) {
+  try {
+    const url = new URL(input, window.location.origin);
+    if (!["https:", "mailto:"].includes(url.protocol)) return null;
+    if (
+      url.protocol === "https:" &&
+      !["https://example.com", "https://docs.example.com"].includes(url.origin)
+    ) {
+      return null;
+    }
+    return url.href;
+  } catch {
+    return null;
+  }
+}
+
+const safeUrl = normalizeAllowedUrl(userInput);
+if (safeUrl) {
+  location.assign(safeUrl);
+}
+
+// If opening a separate browsing context, also prevent tabnabbing.
+if (safeUrl) {
+  window.open(safeUrl, "_blank", "noopener,noreferrer");
+}
+```
+
+## 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 window.config === "object" &&
+  window.config !== null &&
+  !(window.config instanceof Element)
+) {
+  // Safe to use window.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 only owned objects after validating shape
+if (
+  Object.hasOwn(window, "config") &&
+  typeof window.config === "object" &&
+  window.config !== null &&
+  !(window.config instanceof Element)
+) {
+  Object.freeze(window.config);
+}
+
+// 5. Read only from an owned, validated configuration object
+const config =
+  Object.hasOwn(window, "config") &&
+  typeof window.config === "object" &&
+  window.config !== null &&
+  !(window.config instanceof Element)
+    ? window.config
+    : null;
+if (config && 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 plain-text 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");
+
+const trustedWindow = targetWindow;
+const messageValidators = {
+  resize: (data) => Number.isInteger(data.height) && data.height >= 0 && data.height <= 10_000,
+  navigate: (data) => typeof data.path === "string" && data.path.startsWith("/account/"),
+};
+
+// Receiver - validate origin, sender, message type, and type-specific fields.
+window.addEventListener("message", (event) => {
+  if (event.origin !== "https://trusted-domain.com" || event.source !== trustedWindow) return;
+
+  const data = event.data;
+  if (data === null || typeof data !== "object" || typeof data.type !== "string") return;
+  if (!Object.hasOwn(messageValidators, data.type)) return;
+  const validate = messageValidators[data.type];
+  if (!validate(data)) return;
+
+  handleMessage(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 && url.pathname.startsWith("/assets/")) {
+      return url.href;
+    }
+    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