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

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

@@ -0,0 +1,352 @@
+# JWT Security Reference
+
+## Common Vulnerabilities
+
+### None Algorithm Attack
+
+Attack: Attacker changes algorithm to "none" to bypass signature verification.
+
+```javascript
+// VULNERABLE - explicitly accepts unsigned tokens
+const decoded = jwt.verify(token, null, { algorithms: ["none"] });
+
+// 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 - disables the asymmetric key-type safety check for compatibility
+const decoded = jwt.verify(token, publicKey, {
+  allowInvalidAsymmetricKeyTypes: true,
+});
+
+// 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 - stable secret provisioned by a secret manager (256+ bits)
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+if (typeof process.env.JWT_SECRET_BASE64 !== "string") throw new Error("Missing JWT secret");
+const secret = Buffer.from(process.env.JWT_SECRET_BASE64, "base64");
+if (secret.length < 32) throw new Error("JWT secret must contain at least 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
+
+For browser-held bearer tokens, a hardened fingerprint cookie can reduce reuse
+of a stolen token. Treat it as defense in depth, not a substitute for short
+lifetimes, XSS prevention, revocation, or keeping tokens out of browser storage
+when the architecture allows it.
+
+```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, { requireFingerprint = false } = {}) {
+  const decoded = jwt.verify(token, secret, { algorithms: ["HS256"] });
+
+  if (!requireFingerprint) return decoded;
+  if (typeof fingerprintCookie !== "string") throw new Error("Missing fingerprint cookie");
+
+  const fingerprintHash = crypto.createHash("sha256").update(fingerprintCookie).digest("hex");
+
+  if (decoded.fph !== fingerprintHash) {
+    throw new Error("Invalid fingerprint");
+  }
+
+  return decoded;
+}
+```
+
+## Token Storage and Browser Architecture
+
+Choose token handling from the application architecture. Do not present
+Web Storage as a universal default.
+
+### Traditional Web App or BFF: httpOnly Cookie
+
+Prefer server-owned sessions or a backend-for-frontend (BFF) that stores tokens
+server-side and sends only `httpOnly`, `Secure`, SameSite cookies to the
+browser. Cookie-based auth needs CSRF protection on state-changing requests;
+SameSite is useful defense in depth but does not replace tokens plus
+Origin/Referer checks for sensitive operations.
+
+```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
+```
+
+### SPA: In-Memory Access Token
+
+For browser-only SPAs, prefer short-lived access tokens kept in memory, refresh
+token rotation where appropriate, and a clear re-authentication path. Avoid
+long-lived bearer tokens in Web Storage. If refresh tokens are issued to browser
+clients, rotate them, expire them, detect reuse, and avoid storing them in
+`localStorage` or other long-lived JavaScript-readable storage.
+
+```javascript
+let accessToken = null;
+const trustedApiOrigin = "https://api.example.com";
+
+export function setAccessToken(token) {
+  accessToken = token;
+}
+
+export async function apiFetch(url, options = {}) {
+  const target = new URL(url, trustedApiOrigin);
+  if (target.origin !== trustedApiOrigin) {
+    throw new Error("Refusing to send bearer token to an untrusted origin");
+  }
+
+  return fetch(target.href, {
+    ...options,
+    headers: {
+      ...options.headers,
+      ...(accessToken ? { Authorization: `Bearer ${accessToken}` } : {}),
+    },
+  });
+}
+```
+
+### Constrained Fallback: sessionStorage + Fingerprint Cookie
+
+`sessionStorage` is a last-resort compromise for browser-held bearer tokens, not
+a security improvement over in-memory storage. It is readable by XSS. Use it
+only when the architecture requires browser-held tokens and the risk is
+explicitly accepted. Keep token lifetimes short, bind tokens to an `httpOnly`
+fingerprint cookie when possible, and clear tokens on logout.
+
+```javascript
+sessionStorage.setItem("token", jwt);
+sessionStorage.removeItem("token");
+```
+
+### Avoid: localStorage
+
+```javascript
+// VULNERABLE - persists after browser close, accessible to XSS
+localStorage.setItem("token", jwt); // Not recommended
+```
+
+## Token Expiration
+
+The refresh-token example is a server-side sketch. For browser clients, do not
+pair it with long-lived refresh tokens stored in Web Storage; prefer a BFF,
+server-side session, or refresh-token rotation with storage and replay controls
+chosen for the client architecture.
+
+```javascript
+// Short-lived access tokens (15-60 minutes)
+const accessToken = jwt.sign(payload, secret, { expiresIn: "15m" });
+
+// Use Redis or another shared durable store in production. Atomic consume is
+// required so two requests cannot rotate the same refresh token.
+const activeRefreshTokens = new Map();
+
+function issueRefreshToken(userId) {
+  const jti = crypto.randomUUID();
+  const token = jwt.sign({ sub: userId, type: "refresh", jti }, refreshSecret, {
+    expiresIn: "7d",
+  });
+  activeRefreshTokens.set(jti, userId);
+  return token;
+}
+
+const refreshToken = issueRefreshToken(userId);
+
+// 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");
+    }
+
+    if (!decoded.jti || activeRefreshTokens.get(decoded.jti) !== decoded.sub) {
+      throw new Error("Token revoked");
+    }
+
+    // In production, replace this Map operation with an atomic get-and-delete.
+    activeRefreshTokens.delete(decoded.jti);
+
+    // Issue new access token
+    const newAccessToken = jwt.sign({ sub: decoded.sub, jti: crypto.randomUUID() }, secret, {
+      expiresIn: "15m",
+    });
+    const newRefreshToken = issueRefreshToken(decoded.sub);
+
+    res.json({ accessToken: newAccessToken, refreshToken: newRefreshToken });
+  } 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 claims are unavoidable, use JWE or keep the data server-side.
+const encryptedToken = encrypt(token, encryptionKey);
+```
+
+## Validation Middleware
+
+This middleware validates bearer tokens after they reach an API. It does not
+recommend where the browser should store those tokens; use the storage guidance
+above before deciding whether a browser should send an `Authorization` header at
+all.
+
+```javascript
+function authenticateToken(req, res, next) {
+  // Get token from header
+  const authHeader = req.headers.authorization;
+  const token = authHeader?.startsWith("Bearer ") ? authHeader.slice(7) : undefined;
+
+  if (!token) {
+    return res.status(401).json({ error: "Token required" });
+  }
+
+  try {
+    // Validate token and fingerprint when using sidejacking protection
+    const fingerprint = req.cookies["__Secure-Fgp"];
+    const decoded = validateToken(token, 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)
+- [ ] Fingerprint cookie considered for browser-held bearer tokens where appropriate
+- [ ] Validate issuer (iss) and audience (aud) claims
+- [ ] Implement token revocation mechanism
+- [ ] No sensitive data in payload
+- [ ] Choose storage based on architecture: server-side session/BFF, in-memory SPA token, or constrained sessionStorage fallback
+- [ ] Refresh tokens are rotated, replay-detected, and not kept in long-lived Web Storage
+- [ ] Avoid long-lived bearer tokens in Web Storage
+- [ ] Protect cookie-based auth with CSRF defenses
+- [ ] Use HTTPS only
+
+OWASP Reference: https://cheatsheetseries.owasp.org/cheatsheets/JSON_Web_Token_for_Java_Cheat_Sheet.html

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

@@ -0,0 +1,325 @@
+# Node.js and NPM Security Reference
+
+## NPM Dependency Security
+
+### Audit Commands
+
+```bash
+# Check for vulnerabilities
+npm audit
+
+# Preview the proposed changes and lockfile diff first, then run `npm audit fix`
+npm audit fix
+
+# Force fix can apply breaking direct or transitive upgrades. Use only after
+# reviewing release notes, dependency graphs, lockfile diffs, and test results.
+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
+```
+
+### Dependency Update Review
+
+Treat automated dependency updates as reviewable changes, not background
+maintenance. Dependabot or Renovate PRs are useful because they isolate the
+package, lockfile, release notes, provenance or publisher signals where
+available, and CI result for each update. Review dependency diffs carefully for
+new install scripts, ownership changes, unexpected transitive churn, native
+build steps, and broad permission or runtime changes.
+
+Run audits in CI and scheduled automation so ordinary installs are predictable.
+Use `npm audit fix --force` only when the breaking-change and transitive-update
+effects are understood.
+
+### Package.json Security
+
+Avoid package lifecycle scripts that fetch or audit during ordinary installs.
+Install-time `npx` expands supply-chain trust, and `postinstall` audits make
+local installs depend on network and registry behavior. Prefer pinned
+devDependencies, package-manager-native overrides, CI checks, and scheduled
+dependency automation.
+
+```json
+{
+  "overrides": {
+    "vulnerable-package": "^2.0.0"
+  },
+  "scripts": {
+    "audit:ci": "npm audit --audit-level=high"
+  }
+}
+```
+
+## Dangerous Functions
+
+### Code Execution
+
+```javascript
+// DANGEROUS - never use with user input
+eval(userInput);
+new Function(userInput);
+vm.runInThisContext(userInput);
+require(userInput);
+
+// DANGEROUS - dynamic module loading with user-controlled specifiers
+await import(userInput);
+
+// SAFER - map user choices to fixed module specifiers
+const allowedModules = new Map([["csv", "./parsers/csv.js"]]);
+const modulePath = allowedModules.get(userInput);
+if (!modulePath) throw new Error("Invalid module");
+await import(modulePath);
+```
+
+### Child Process Injection
+
+```javascript
+// DANGEROUS - command injection
+const { exec } = require("child_process");
+exec(`ls ${userInput}`); // Shell injection
+
+// SAFER - use execFile with arguments array and no shell
+const { execFile } = require("child_process");
+execFile("ls", ["--", userInput], { shell: false }, callback);
+
+// SAFEST - avoid shelling out when a library API can do the work.
+// If a command is necessary, allowlist the command and argument shapes.
+const { spawn } = require("child_process");
+const allowedFormats = new Set(["json", "text"]);
+if (!allowedFormats.has(userSelectedFormat)) {
+  throw new Error("Invalid format");
+}
+spawn("tool", ["--format", userSelectedFormat, "--", userPath], {
+  shell: false,
+  cwd: "/srv/app",
+  env: { PATH: "/usr/bin:/bin" },
+});
+```
+
+Argument arrays prevent shell metacharacter expansion, but they do not make
+user-controlled arguments safe automatically. Some programs treat values as
+options, paths, patterns, or expressions. Use `--` before user-controlled path
+arguments when supported, validate option values, set `cwd` and `env`
+explicitly, run with least privilege, and treat command output as untrusted.
+
+### File System
+
+```javascript
+const path = require("node:path");
+const fs = require("node:fs");
+
+// DANGEROUS - path traversal
+const filePath = `/uploads/${userInput}`;
+
+// Keep baseDir and its parent directories trusted and non-writable by users.
+function safeReadFile(userInput, baseDir) {
+  const basePath = fs.realpathSync(baseDir);
+  const requestedPath = path.resolve(basePath, userInput);
+  const safePath = fs.realpathSync(requestedPath);
+  const relativePath = path.relative(basePath, safePath);
+
+  // Verify path is within allowed directory
+  if (relativePath.startsWith("..") || path.isAbsolute(relativePath)) {
+    throw new Error("Invalid file path");
+  }
+
+  // O_NOFOLLOW prevents a final-component symlink swap between validation and open.
+  // The trusted-directory requirement prevents intermediate path replacement.
+  const fd = fs.openSync(safePath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+  try {
+    return fs.readFileSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+```
+
+## Request Handling
+
+### Rate Limiting
+
+The default memory store below is suitable only for a single-process development example. In
+multi-process or multi-instance deployments, configure a shared store such as Redis and set
+Express `trust proxy` only to the exact proxy topology so client IP keys cannot be spoofed.
+
+```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'"],
+        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) => {
+  // Use a structured logger configured to redact credentials, request data,
+  // SQL, tokens, and PII. Emit only reviewed fields.
+  logger.error({
+    message: typeof err?.message === "string" ? err.message.slice(0, 256) : "Unhandled error",
+    stack: process.env.NODE_ENV === "development" ? err?.stack : undefined,
+  });
+
+  // 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 such as Dependabot or Renovate
+- [ ] Review dependency and lockfile diffs for risky scripts, publisher changes, and unexpected transitive churn
+- [ ] Keep dependencies updated
+- [ ] Avoid typosquatting by double-checking package names
+- [ ] Use `npm-shrinkwrap.json` only when publishing a deployable app or CLI that must lock transitive dependencies; avoid it for libraries unless you intentionally want to constrain consumers
+
+OWASP References:
+
+- https://cheatsheetseries.owasp.org/cheatsheets/Nodejs_Security_Cheat_Sheet.html
+- https://cheatsheetseries.owasp.org/cheatsheets/NPM_Security_Cheat_Sheet.html
+- https://cheatsheetseries.owasp.org/cheatsheets/OS_Command_Injection_Defense_Cheat_Sheet.html
+- https://docs.npmjs.com/cli/commands/npm-audit
+- https://docs.github.com/en/code-security/dependabot
+- https://nodejs.org/api/child_process.html