@schalkneethling/toolkit 0.5.0 → 0.5.3

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

@@ -8,21 +8,21 @@ Generate unique per-session tokens and validate on state-changing requests:
 
 ```javascript
 // Server-side token generation (Node.js)
-const crypto = require('crypto');
+const crypto = require("crypto");
 
 function generateCSRFToken(session) {
-  const token = crypto.randomBytes(32).toString('hex');
+  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 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' });
+  if (typeof token !== "string" || typeof sessionToken !== "string") {
+    return res.status(403).json({ error: "Invalid CSRF token" });
   }
 
   const tokenBuffer = Buffer.from(token);
@@ -32,7 +32,7 @@ function validateCSRF(req, res, next) {
     tokenBuffer.length !== sessionTokenBuffer.length ||
     !crypto.timingSafeEqual(tokenBuffer, sessionTokenBuffer)
   ) {
-    return res.status(403).json({ error: 'Invalid CSRF token' });
+    return res.status(403).json({ error: "Invalid CSRF token" });
   }
   next();
 }
@@ -42,24 +42,24 @@ function validateCSRF(req, res, next) {
 
 ```javascript
 // Set CSRF cookie
-res.cookie('csrf_token', token, {
-  httpOnly: false,  // Must be readable by JavaScript
+res.cookie("csrf_token", token, {
+  httpOnly: false, // Must be readable by JavaScript
   secure: true,
-  sameSite: 'Strict'
+  sameSite: "Strict",
 });
 
 // Client sends token in header
-fetch('/api/action', {
-  method: 'POST',
+fetch("/api/action", {
+  method: "POST",
   headers: {
-    'X-CSRF-Token': getCookie('csrf_token')
-  }
+    "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'];
+  const headerToken = req.headers["x-csrf-token"];
   return cookieToken && cookieToken === headerToken;
 }
 ```
@@ -68,43 +68,43 @@ function validateDoubleSubmit(req) {
 
 ```javascript
 // Strict - never sent cross-site
-res.cookie('session', value, { sameSite: 'Strict', secure: true, httpOnly: true });
+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 });
+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 });
+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:
+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 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();
+  if (site === "same-origin") return next();
 
   // Allow user-initiated browser navigations
-  if (site === 'none') return next();
+  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))
+    site === "same-site" &&
+    (mode === "navigate" || ["GET", "HEAD", "OPTIONS"].includes(method))
   ) {
     return next();
   }
 
-  return res.status(403).json({ error: 'Fetch metadata validation failed' });
+  return res.status(403).json({ error: "Fetch metadata validation failed" });
 }
 ```
 
@@ -113,20 +113,24 @@ function validateFetchMetadata(req, res, next) {
 ### Express.js with Signed Double-Submit Tokens
 
 ```javascript
-const crypto = require('crypto');
+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_COOKIE_NAME = 'csrf_token';
-const CSRF_SECRET = Buffer.from(process.env.CSRF_SECRET, 'hex');
+const CSRF_SECRET = Buffer.from(process.env.CSRF_SECRET, "hex");
 
 function signToken(sessionId, nonce) {
   return crypto
-    .createHmac('sha256', CSRF_SECRET)
+    .createHmac("sha256", CSRF_SECRET)
     .update(`${sessionId}:${nonce}`)
-    .digest('base64url');
+    .digest("base64url");
 }
 
 function constantTimeEqual(value, expected) {
-  if (typeof value !== 'string' || typeof expected !== 'string') return false;
+  if (typeof value !== "string" || typeof expected !== "string") return false;
 
   const valueBuffer = Buffer.from(value);
   const expectedBuffer = Buffer.from(expected);
@@ -138,7 +142,7 @@ function constantTimeEqual(value, expected) {
 }
 
 function generateToken(req) {
-  const nonce = crypto.randomBytes(32).toString('base64url');
+  const nonce = crypto.randomBytes(32).toString("base64url");
   const signature = signToken(req.session.id, nonce);
   return `${nonce}.${signature}`;
 }
@@ -149,7 +153,7 @@ function sendToken(req, res, next) {
   res.cookie(CSRF_COOKIE_NAME, token, {
     httpOnly: true,
     secure: true,
-    sameSite: 'Strict'
+    sameSite: "Strict",
   });
 
   res.locals.csrfToken = token;
@@ -157,30 +161,30 @@ function sendToken(req, res, next) {
 }
 
 function verifyToken(req, res, next) {
-  const token = req.headers['x-csrf-token'] || req.body._csrf;
+  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' });
+    return res.status(403).json({ error: "Invalid CSRF token" });
   }
 
-  const [nonce, signature, extra] = cookieToken.split('.');
+  const [nonce, signature, extra] = cookieToken.split(".");
   if (extra || !nonce || !signature) {
-    return res.status(403).json({ error: 'Invalid CSRF token' });
+    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' });
+    return res.status(403).json({ error: "Invalid CSRF token" });
   }
 
   next();
 }
 
-app.get('/form', sendToken, (req, res) => {
-  res.render('form', { csrfToken: res.locals.csrfToken });
+app.get("/form", sendToken, (req, res) => {
+  res.render("form", { csrfToken: res.locals.csrfToken });
 });
 
-app.post('/submit', verifyToken, (req, res) => {
+app.post("/submit", verifyToken, (req, res) => {
   res.json({ ok: true });
 });
 ```
@@ -188,16 +192,16 @@ app.post('/submit', verifyToken, (req, res) => {
 Example tests for token issuance and verification:
 
 ```javascript
-const assert = require('node:assert/strict');
-const test = require('node:test');
+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' } };
+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, () => {});
@@ -205,36 +209,36 @@ test('sendToken issues a cookie and exposes a form token', () => {
   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');
+  assert.equal(res.cookieArgs.options.sameSite, "Strict");
 });
 
-test('verifyToken accepts a matching signed token', () => {
-  const req = { session: { id: 'session-123' } };
+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 },
+      headers: { "x-csrf-token": token },
       body: {},
-      cookies: { [CSRF_COOKIE_NAME]: token }
+      cookies: { [CSRF_COOKIE_NAME]: token },
     },
     {},
     () => {
       called = true;
-    }
+    },
   );
 
   assert.equal(called, true);
 });
 
-test('verifyToken rejects mismatched or tampered tokens', () => {
+test("verifyToken rejects mismatched or tampered tokens", () => {
   const req = {
-    session: { id: 'session-123' },
-    headers: { 'x-csrf-token': 'tampered.token' },
+    session: { id: "session-123" },
+    headers: { "x-csrf-token": "tampered.token" },
     body: {},
-    cookies: { [CSRF_COOKIE_NAME]: generateToken({ session: { id: 'session-123' } }) }
+    cookies: { [CSRF_COOKIE_NAME]: generateToken({ session: { id: "session-123" } }) },
   };
   const res = {
     status(code) {
@@ -243,13 +247,13 @@ test('verifyToken rejects mismatched or tampered tokens', () => {
     },
     json(body) {
       this.body = body;
-    }
+    },
   };
 
   verifyToken(req, res, () => {});
 
   assert.equal(res.statusCode, 403);
-  assert.deepEqual(res.body, { error: 'Invalid CSRF token' });
+  assert.deepEqual(res.body, { error: "Invalid CSRF token" });
 });
 ```
 
@@ -259,13 +263,13 @@ test('verifyToken rejects mismatched or tampered tokens', () => {
 function Form({ csrfToken }) {
   const handleSubmit = async (e) => {
     e.preventDefault();
-    await fetch('/api/submit', {
-      method: 'POST',
+    await fetch("/api/submit", {
+      method: "POST",
       headers: {
-        'Content-Type': 'application/json',
-        'X-CSRF-Token': csrfToken
+        "Content-Type": "application/json",
+        "X-CSRF-Token": csrfToken,
       },
-      body: JSON.stringify(formData)
+      body: JSON.stringify(formData),
     });
   };
 
@@ -293,10 +297,10 @@ Protect against CSRF in single-page applications:
 
 ```javascript
 // Set up axios defaults
-import axios from 'axios';
+import axios from "axios";
 
-axios.defaults.xsrfCookieName = 'csrf_token';
-axios.defaults.xsrfHeaderName = 'X-CSRF-Token';
+axios.defaults.xsrfCookieName = "csrf_token";
+axios.defaults.xsrfHeaderName = "X-CSRF-Token";
 axios.defaults.withCredentials = true;
 
 // Or with fetch
@@ -305,11 +309,11 @@ async function secureFetch(url, options = {}) {
 
   return fetch(url, {
     ...options,
-    credentials: 'same-origin',
+    credentials: "same-origin",
     headers: {
       ...options.headers,
-      'X-CSRF-Token': csrfToken
-    }
+      "X-CSRF-Token": csrfToken,
+    },
   });
 }
 ```

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

@@ -8,13 +8,13 @@ Untrusted data in HTML element content:
 
 ```javascript
 // UNSAFE
-element.innerHTML = '<div>' + userInput + '</div>';
+element.innerHTML = "<div>" + userInput + "</div>";
 
 // SAFE - use textContent
 element.textContent = userInput;
 
 // SAFE - create elements programmatically
-const div = document.createElement('div');
+const div = document.createElement("div");
 div.textContent = userInput;
 parent.appendChild(div);
 ```
@@ -39,14 +39,14 @@ const value = element.dataset.value;
 
 ```javascript
 // UNSAFE - event handlers
-element.setAttribute('onclick', userInput);
+element.setAttribute("onclick", userInput);
 
 // UNSAFE - dangerous attributes
-element.setAttribute('href', userInput);  // javascript: URLs
-element.setAttribute('src', userInput);   // script injection
+element.setAttribute("href", userInput); // javascript: URLs
+element.setAttribute("src", userInput); // script injection
 
 // SAFE - safe attributes only
-const safeAttributes = ['title', 'alt', 'class', 'id', 'name'];
+const safeAttributes = ["title", "alt", "class", "id", "name"];
 if (safeAttributes.includes(attributeName)) {
   element.setAttribute(attributeName, userInput);
 }
@@ -57,7 +57,7 @@ if (safeAttributes.includes(attributeName)) {
 ```javascript
 // UNSAFE - expression injection
 element.style.cssText = userInput;
-element.setAttribute('style', userInput);
+element.setAttribute("style", userInput);
 
 // SAFE - set specific properties
 element.style.backgroundColor = sanitizeColor(userInput);
@@ -65,7 +65,7 @@ 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';
+  return colorRegex.test(input) ? input : "inherit";
 }
 ```
 
@@ -75,13 +75,13 @@ function sanitizeColor(input) {
 // UNSAFE - unvalidated URLs
 location.href = userInput;
 window.open(userInput);
-element.setAttribute('href', 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:'];
+    const allowedProtocols = ["http:", "https:", "mailto:"];
     if (!allowedProtocols.includes(url.protocol)) {
       return null;
     }
@@ -105,7 +105,7 @@ Named elements (id, name attributes) create global variables:
 
 ```html
 <!-- This creates window.config -->
-<img id="config" src="x">
+<img id="config" src="x" />
 
 <!-- JavaScript that assumes config is an object will break -->
 <script>
@@ -117,12 +117,17 @@ Named elements (id, name attributes) create global variables:
 
 ```javascript
 // 1. Use Object.hasOwn() or hasOwnProperty()
-if (Object.hasOwn(window, 'config') && typeof config === 'object') {
-  // Safe to use config
+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');
+const element = document.getElementById("config");
 
 // 3. Use Map instead of objects for user-controlled keys
 const userConfig = new Map();
@@ -133,7 +138,7 @@ Object.freeze(window.config);
 
 // 5. Use nullish coalescing with type checking
 const config = window.config ?? {};
-if (typeof config.apiKey === 'string') {
+if (typeof config.apiKey === "string") {
   // Safe to use
 }
 ```
@@ -143,8 +148,8 @@ if (typeof config.apiKey === 'string') {
 ```javascript
 // DOMPurify with clobbering protection
 const clean = DOMPurify.sanitize(dirty, {
-  SANITIZE_DOM: true,  // Remove clobbering vectors
-  SANITIZE_NAMED_PROPS: true
+  SANITIZE_DOM: true, // Remove clobbering vectors
+  SANITIZE_NAMED_PROPS: true,
 });
 ```
 
@@ -158,7 +163,7 @@ element.textContent = userInput;
 document.createTextNode(userInput);
 
 // Attribute manipulation (for safe attributes)
-element.setAttribute('data-value', userInput);
+element.setAttribute("data-value", userInput);
 element.classList.add(sanitizedClass);
 
 // Query selectors (read-only)
@@ -173,11 +178,11 @@ document.querySelectorAll(selector);
 element.innerHTML = sanitized;
 element.outerHTML = sanitized;
 element.insertAdjacentHTML(position, sanitized);
-document.write(sanitized);  // Avoid entirely
+document.write(sanitized); // Avoid entirely
 
 // Script execution
-eval();           // Never use with user input
-new Function();   // Never use with user input
+eval(); // Never use with user input
+new Function(); // Never use with user input
 setTimeout(string); // Never pass strings
 setInterval(string); // Never pass strings
 ```
@@ -186,17 +191,17 @@ setInterval(string); // Never pass strings
 
 ```javascript
 // Sender - specify exact origin
-targetWindow.postMessage(data, 'https://trusted-domain.com');
+targetWindow.postMessage(data, "https://trusted-domain.com");
 
 // Receiver - always validate origin
-window.addEventListener('message', (event) => {
+window.addEventListener("message", (event) => {
   // Validate origin
-  if (event.origin !== 'https://trusted-domain.com') {
+  if (event.origin !== "https://trusted-domain.com") {
     return;
   }
 
   // Validate data structure
-  if (typeof event.data !== 'object' || !event.data.type) {
+  if (event.data === null || typeof event.data !== "object" || !event.data.type) {
     return;
   }
 
@@ -212,14 +217,16 @@ window.addEventListener('message', (event) => {
 // Content-Security-Policy: require-trusted-types-for 'script'
 
 // Create a policy
-const policy = trustedTypes.createPolicy('default', {
+const policy = trustedTypes.createPolicy("default", {
   createHTML: (input) => DOMPurify.sanitize(input),
-  createScript: () => { throw new Error('Scripts not allowed'); },
+  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');
-  }
+    throw new Error("Invalid script URL");
+  },
 });
 
 // Usage