secure-coding-rules 2.0.0

package/src/templates/core/authentication.md

@@ -0,0 +1,138 @@
+# Authentication Security Rules
+
+> OWASP Top 10 2025 - A07: Authentication Failures
+
+## Rules
+
+### 1. Implement Multi-Factor Authentication
+- **DO**: Require MFA for all privileged accounts and offer it for all users. Use TOTP, WebAuthn, or push-based verification.
+- **DON'T**: Rely solely on passwords for authentication, especially for admin and financial operations.
+- **WHY**: Passwords alone are frequently compromised through phishing, credential stuffing, or data breaches.
+
+### 2. Enforce Strong Password Policies
+- **DO**: Require a minimum of 8 characters. Check against breached password databases (e.g., Have I Been Pwned API). Allow long passphrases.
+- **DON'T**: Impose arbitrary complexity rules (uppercase + number + symbol) that lead to predictable patterns, or cap password length below 64 characters.
+- **WHY**: NIST guidelines (SP 800-63B) recommend length over complexity. Breached password checks are more effective than complexity rules.
+
+### 3. Protect Against Credential Stuffing and Brute Force
+- **DO**: Implement rate limiting, account lockout with exponential backoff, and CAPTCHA after failed attempts.
+- **DON'T**: Allow unlimited login attempts or reveal whether the username or password was incorrect.
+- **WHY**: Credential stuffing uses leaked credentials from other breaches. Rate limiting and generic error messages slow automated attacks.
+
+### 4. Secure Session Management
+- **DO**: Generate random session IDs with high entropy. Set cookies with `HttpOnly`, `Secure`, `SameSite=Strict`, and appropriate expiry.
+- **DON'T**: Store session tokens in `localStorage` or expose them in URLs. Never accept session IDs from query parameters.
+- **WHY**: Predictable or exposed session tokens allow session hijacking. Secure cookie attributes prevent XSS and CSRF-based theft.
+
+### 5. Implement Secure Password Reset
+- **DO**: Use time-limited, single-use tokens for password reset. Send reset links only to verified email addresses. Invalidate all sessions on password change.
+- **DON'T**: Use knowledge-based questions, send plaintext passwords, or allow token reuse.
+- **WHY**: Weak password reset flows are as dangerous as weak passwords. They are a common target for account takeover.
+
+### 6. Validate JWTs Properly
+- **DO**: Verify signature, issuer (`iss`), audience (`aud`), and expiration (`exp`). Use asymmetric algorithms (RS256, ES256) for distributed systems.
+- **DON'T**: Use `alg: "none"`, accept tokens without signature verification, or store sensitive data in JWT payloads.
+- **WHY**: JWT misuse (algorithm confusion, missing validation) leads to authentication bypass and privilege escalation.
+
+### 7. Implement Secure OAuth/OIDC Flows
+- **DO**: Use Authorization Code flow with PKCE. Validate the `state` parameter and token claims. Store tokens securely.
+- **DON'T**: Use Implicit flow for SPAs. Skip `state` validation or accept tokens from untrusted sources.
+- **WHY**: OAuth misconfiguration enables token theft, CSRF, and account takeover through redirect manipulation.
+
+## Code Examples
+
+### Bad Practice
+```javascript
+// Revealing whether user exists
+app.post("/api/login", async (req, res) => {
+  const user = await db.findUser(req.body.email);
+  if (!user) return res.status(401).json({ error: "User not found" }); // Info leak
+  if (!checkPassword(req.body.password, user.password)) {
+    return res.status(401).json({ error: "Wrong password" }); // Info leak
+  }
+  res.json({ token: jwt.sign({ id: user.id }, SECRET) });
+});
+
+// Insecure JWT validation
+const payload = jwt.decode(token); // decode without verify!
+if (payload.role === "admin") grantAdminAccess();
+
+// Session token in localStorage
+localStorage.setItem("token", response.data.token); // Accessible via XSS
+```
+
+### Good Practice
+```javascript
+import jwt from "jsonwebtoken";
+import { rateLimit } from "express-rate-limit";
+
+// Rate-limited login with generic error messages
+const loginLimiter = rateLimit({
+  windowMs: 15 * 60 * 1000,
+  max: 10,
+  skipSuccessfulRequests: true,
+});
+
+app.post("/api/login", loginLimiter, async (req, res) => {
+  const { email, password } = req.body;
+  const user = await db.findUser(email);
+
+  // Constant-time check - same response whether user exists or not
+  const isValid = user ? await verifyPassword(password, user.passwordHash) : false;
+  if (!isValid) {
+    return res.status(401).json({ error: "Invalid credentials" }); // Generic message
+  }
+
+  // Check for MFA
+  if (user.mfaEnabled) {
+    const mfaToken = crypto.randomBytes(32).toString("hex");
+    await storeMfaChallenge(user.id, mfaToken, Date.now() + 300_000);
+    return res.json({ requiresMFA: true, mfaToken });
+  }
+
+  setSessionCookie(res, user);
+  res.json({ success: true });
+});
+
+// Secure session cookie
+function setSessionCookie(res, user) {
+  const sessionId = crypto.randomUUID();
+  res.cookie("session", sessionId, {
+    httpOnly: true,
+    secure: true,
+    sameSite: "strict",
+    maxAge: 3600_000, // 1 hour
+    path: "/",
+  });
+}
+
+// Proper JWT verification
+function verifyToken(token) {
+  return jwt.verify(token, PUBLIC_KEY, {
+    algorithms: ["ES256"],     // Explicit algorithm
+    issuer: "https://auth.example.com",
+    audience: "https://api.example.com",
+    clockTolerance: 30,
+  });
+}
+
+// Secure password reset
+app.post("/api/password-reset", async (req, res) => {
+  const token = crypto.randomBytes(32).toString("hex");
+  const hashedToken = crypto.createHash("sha256").update(token).digest("hex");
+  await db.storeResetToken(req.body.email, hashedToken, Date.now() + 3600_000);
+  await sendResetEmail(req.body.email, token); // Send unhashed token
+  res.json({ message: "If the email exists, a reset link has been sent" }); // Generic
+});
+```
+
+## Quick Checklist
+- [ ] MFA available and enforced for privileged accounts
+- [ ] Passwords checked against breached password databases
+- [ ] Login rate limiting and account lockout implemented
+- [ ] Generic error messages for authentication failures (no user enumeration)
+- [ ] Session cookies use `HttpOnly`, `Secure`, `SameSite=Strict`
+- [ ] JWTs verified with explicit algorithm, issuer, and audience
+- [ ] Password reset uses time-limited, single-use tokens
+- [ ] All sessions invalidated on password change
+- [ ] OAuth flows use PKCE and validate `state` parameter

package/src/templates/core/cryptographic.md

@@ -0,0 +1,114 @@
+# Cryptographic Failures Security Rules
+
+> OWASP Top 10 2025 - A04: Cryptographic Failures
+
+## Rules
+
+### 1. Use Strong, Modern Encryption Algorithms
+- **DO**: Use AES-256-GCM for symmetric encryption and RSA-OAEP or ECDH for asymmetric encryption. Use the Web Crypto API or `node:crypto` module.
+- **DON'T**: Use deprecated algorithms like DES, 3DES, RC4, MD5, or SHA-1 for security purposes.
+- **WHY**: Weak algorithms are vulnerable to known attacks and can be broken with modern hardware.
+
+### 2. Never Hardcode Secrets or Keys
+- **DO**: Store keys in environment variables, secret managers (AWS Secrets Manager, HashiCorp Vault), or hardware security modules.
+- **DON'T**: Embed encryption keys, API keys, or passwords directly in source code or config files.
+- **WHY**: Hardcoded secrets in source code are easily extracted from repositories and compiled artifacts.
+
+### 3. Hash Passwords with Adaptive Algorithms
+- **DO**: Use bcrypt, scrypt, or Argon2id for password hashing with appropriate work factors.
+- **DON'T**: Use plain hashing (SHA-256, MD5) or unsalted hashes for passwords.
+- **WHY**: Adaptive hashing algorithms are designed to resist GPU-based brute force and rainbow table attacks.
+
+### 4. Generate Cryptographically Secure Random Values
+- **DO**: Use `crypto.randomBytes()`, `crypto.randomUUID()`, or `crypto.getRandomValues()` for tokens, IDs, and nonces.
+- **DON'T**: Use `Math.random()` for any security-sensitive value (tokens, session IDs, OTPs).
+- **WHY**: `Math.random()` is predictable and not cryptographically secure. Attackers can predict its output.
+
+### 5. Encrypt Sensitive Data at Rest and in Transit
+- **DO**: Use TLS 1.2+ for data in transit. Encrypt PII, financial data, and health records at rest with field-level encryption where appropriate.
+- **DON'T**: Store sensitive data in plaintext in databases, logs, or local storage.
+- **WHY**: Data breaches expose plaintext data. Encryption limits the impact of unauthorized access.
+
+### 6. Use Authenticated Encryption
+- **DO**: Use AEAD modes like AES-GCM that provide both confidentiality and integrity.
+- **DON'T**: Use ECB mode or CBC without HMAC. Never implement custom encryption schemes.
+- **WHY**: Unauthenticated encryption is vulnerable to padding oracle and ciphertext manipulation attacks.
+
+### 7. Manage Key Rotation and Lifecycle
+- **DO**: Implement key rotation policies. Support decryption with old keys while encrypting with current keys.
+- **DON'T**: Use the same encryption key indefinitely without rotation.
+- **WHY**: Key rotation limits the impact of key compromise and meets compliance requirements.
+
+## Code Examples
+
+### Bad Practice
+```javascript
+import crypto from "node:crypto";
+
+// Using Math.random for tokens
+const resetToken = Math.random().toString(36).substring(2);
+
+// MD5 for password hashing (no salt, fast hash)
+const hashedPassword = crypto.createHash("md5").update(password).digest("hex");
+
+// Hardcoded encryption key
+const ENCRYPTION_KEY = "my-super-secret-key-12345678";
+
+// ECB mode (insecure - identical blocks produce identical ciphertext)
+const cipher = crypto.createCipheriv("aes-256-ecb", key, null);
+```
+
+### Good Practice
+```javascript
+import crypto from "node:crypto";
+import { hash, verify } from "@node-rs/argon2"; // or bcrypt
+
+// Cryptographically secure random token
+const resetToken = crypto.randomBytes(32).toString("hex");
+const sessionId = crypto.randomUUID();
+
+// Argon2id password hashing
+async function hashPassword(password) {
+  return hash(password, {
+    memoryCost: 65536,  // 64 MB
+    timeCost: 3,
+    parallelism: 4,
+  });
+}
+
+async function verifyPassword(password, hashedPassword) {
+  return verify(hashedPassword, password);
+}
+
+// AES-256-GCM authenticated encryption
+function encrypt(plaintext, key) {
+  const iv = crypto.randomBytes(12); // 96-bit IV for GCM
+  const cipher = crypto.createCipheriv("aes-256-gcm", key, iv);
+  const encrypted = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+  const authTag = cipher.getAuthTag();
+  return Buffer.concat([iv, authTag, encrypted]).toString("base64");
+}
+
+function decrypt(ciphertext, key) {
+  const data = Buffer.from(ciphertext, "base64");
+  const iv = data.subarray(0, 12);
+  const authTag = data.subarray(12, 28);
+  const encrypted = data.subarray(28);
+  const decipher = crypto.createDecipheriv("aes-256-gcm", key, iv);
+  decipher.setAuthTag(authTag);
+  return Buffer.concat([decipher.update(encrypted), decipher.final()]).toString("utf8");
+}
+
+// Key from environment / secret manager
+const encryptionKey = Buffer.from(process.env.ENCRYPTION_KEY, "base64");
+```
+
+## Quick Checklist
+- [ ] Only modern algorithms used (AES-256-GCM, SHA-256+, Argon2id/bcrypt)
+- [ ] No hardcoded keys or secrets in source code
+- [ ] Passwords hashed with Argon2id, bcrypt, or scrypt
+- [ ] All random values use `crypto.randomBytes()` or `crypto.getRandomValues()`
+- [ ] Sensitive data encrypted at rest and in transit (TLS 1.2+)
+- [ ] Authenticated encryption mode (GCM) used for symmetric encryption
+- [ ] Key rotation policy defined and implemented
+- [ ] No sensitive data in logs, URLs, or client-side storage

package/src/templates/core/data-integrity.md

@@ -0,0 +1,144 @@
+# Software and Data Integrity Security Rules
+
+> OWASP Top 10 2025 - A08: Software or Data Integrity Failures
+
+## Rules
+
+### 1. Verify CI/CD Pipeline Integrity
+- **DO**: Sign commits and artifacts. Use protected branches, required reviews, and immutable build environments.
+- **DON'T**: Allow unapproved changes to CI/CD configuration or build scripts without review.
+- **WHY**: Compromised pipelines can inject malicious code into production builds, affecting all users.
+
+### 2. Validate Data Integrity on Deserialization
+- **DO**: Validate and sanitize all deserialized data against strict schemas. Use safe serialization formats (JSON with schema validation).
+- **DON'T**: Deserialize untrusted data without validation, especially with `eval()`, `Function()`, or `node:vm`.
+- **WHY**: Insecure deserialization can lead to Remote Code Execution (RCE) or data tampering.
+
+### 3. Implement Integrity Checks for Critical Data
+- **DO**: Use HMAC or digital signatures to verify integrity of sensitive data (tokens, cookies, inter-service messages).
+- **DON'T**: Trust data from cookies, hidden form fields, or client-side storage without integrity verification.
+- **WHY**: Client-side data can be tampered with. Signed data ensures it hasn't been modified.
+
+### 4. Secure Auto-Update Mechanisms
+- **DO**: Verify digital signatures on all updates before applying them. Use TLS for update channels.
+- **DON'T**: Download and execute updates without cryptographic verification.
+- **WHY**: Unsigned updates can be replaced with malicious payloads through MITM attacks or compromised update servers.
+
+### 5. Protect Database Migrations and Seeds
+- **DO**: Review and version-control all database migrations. Use checksums to verify migration integrity.
+- **DON'T**: Run auto-generated migrations in production without review or allow dynamic schema changes from user input.
+- **WHY**: Malicious migrations can alter database structure, delete data, or create backdoor accounts.
+
+### 6. Validate Webhook and API Payloads
+- **DO**: Verify webhook signatures using HMAC. Validate the payload schema and source IP where possible.
+- **DON'T**: Process webhook payloads without signature verification or trust arbitrary callback URLs.
+- **WHY**: Unverified webhooks allow attackers to inject fake events (payment confirmations, deploy triggers).
+
+## Code Examples
+
+### Bad Practice
+```javascript
+// Deserializing untrusted data unsafely
+const userData = eval(`(${req.body.data})`); // RCE vulnerability
+
+// Trusting client-side data without integrity check
+app.post("/api/checkout", (req, res) => {
+  const { price } = req.body; // Client can modify price
+  processPayment(price);
+});
+
+// Processing webhook without signature verification
+app.post("/webhook/payment", (req, res) => {
+  const event = req.body;
+  if (event.type === "payment_success") {
+    fulfillOrder(event.orderId); // Could be forged
+  }
+});
+```
+
+### Good Practice
+```javascript
+import crypto from "node:crypto";
+import { z } from "zod";
+
+// Safe deserialization with schema validation
+const UserDataSchema = z.object({
+  name: z.string().max(100),
+  email: z.string().email(),
+  role: z.enum(["user", "editor"]),
+});
+
+app.post("/api/profile", authenticate, (req, res) => {
+  const userData = UserDataSchema.parse(JSON.parse(req.body.data));
+  updateProfile(req.user.id, userData);
+});
+
+// Signed data for client-side integrity
+function signData(data, secret) {
+  const payload = JSON.stringify(data);
+  const signature = crypto
+    .createHmac("sha256", secret)
+    .update(payload)
+    .digest("hex");
+  return { payload, signature };
+}
+
+function verifyData(payload, signature, secret) {
+  const expected = crypto
+    .createHmac("sha256", secret)
+    .update(payload)
+    .digest("hex");
+  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
+    throw new Error("Data integrity verification failed");
+  }
+  return JSON.parse(payload);
+}
+
+// Server-side price validation (never trust client price)
+app.post("/api/checkout", authenticate, async (req, res) => {
+  const { itemId, quantity } = req.body;
+  const item = await db.getItem(itemId);        // Get real price from DB
+  const totalPrice = item.price * quantity;      // Calculate server-side
+  await processPayment(req.user.id, totalPrice);
+});
+
+// Webhook signature verification (Stripe example pattern)
+function verifyWebhookSignature(payload, signature, secret) {
+  const [timestamp, hash] = parseSignatureHeader(signature);
+
+  // Prevent replay attacks
+  if (Date.now() / 1000 - Number(timestamp) > 300) {
+    throw new Error("Webhook timestamp too old");
+  }
+
+  const expected = crypto
+    .createHmac("sha256", secret)
+    .update(`${timestamp}.${payload}`)
+    .digest("hex");
+
+  if (!crypto.timingSafeEqual(Buffer.from(hash), Buffer.from(expected))) {
+    throw new Error("Invalid webhook signature");
+  }
+  return JSON.parse(payload);
+}
+
+app.post("/webhook/payment", express.raw({ type: "application/json" }), (req, res) => {
+  const event = verifyWebhookSignature(
+    req.body.toString(),
+    req.headers["x-signature"],
+    process.env.WEBHOOK_SECRET,
+  );
+  processVerifiedEvent(event);
+  res.sendStatus(200);
+});
+```
+
+## Quick Checklist
+- [ ] CI/CD pipeline changes require review and approval
+- [ ] All deserialization uses schema validation, never `eval()`
+- [ ] Critical client-facing data is signed with HMAC or digital signatures
+- [ ] Server-side calculation for prices, totals, and business-critical values
+- [ ] Webhook payloads verified with signature before processing
+- [ ] Auto-updates verify digital signatures before applying
+- [ ] Database migrations are version-controlled and reviewed
+- [ ] `timingSafeEqual` used for all signature comparisons

package/src/templates/core/error-handling.md

@@ -0,0 +1,180 @@
+# Error Handling Security Rules
+
+> OWASP Top 10 2025 - A10: Mishandling of Exceptional Conditions (NEW)
+
+## Rules
+
+### 1. Implement Fail-Safe Defaults
+- **DO**: Default to the most secure state when errors occur. Deny access, reject transactions, and close connections on failure.
+- **DON'T**: Fail open by granting access or skipping validation when an error occurs.
+- **WHY**: Attackers intentionally trigger errors to bypass security controls. Fail-safe defaults ensure errors never weaken security posture.
+
+### 2. Use Structured Error Handling Patterns
+- **DO**: Use try-catch blocks, Result/Either patterns, or error boundary components. Handle every possible error state explicitly.
+- **DON'T**: Ignore promise rejections, leave catch blocks empty, or rely on uncaught exception handlers for control flow.
+- **WHY**: Unhandled errors crash services, leak information, and create unpredictable system states that attackers exploit.
+
+### 3. Separate Internal and External Error Messages
+- **DO**: Log detailed errors internally with full context. Return generic, safe error messages to users with a reference ID.
+- **DON'T**: Expose internal error details, stack traces, or database messages to clients.
+- **WHY**: Detailed errors reveal technology stack, file paths, and database structure that aid targeted attacks.
+
+### 4. Implement Graceful Degradation
+- **DO**: Design fallback behavior for external service failures. Use circuit breakers, timeouts, and retry with backoff.
+- **DON'T**: Let a single external dependency failure cascade into full application failure.
+- **WHY**: Cascading failures cause outages. Graceful degradation maintains core functionality and prevents denial of service.
+
+### 5. Handle All Promise Rejections and Async Errors
+- **DO**: Attach `.catch()` to all promises or use `try-catch` with `await`. Register global `unhandledRejection` handlers as a safety net.
+- **DON'T**: Fire and forget promises or assume async operations will always succeed.
+- **WHY**: Unhandled promise rejections cause silent failures, memory leaks, and in Node.js 15+, process crashes.
+
+### 6. Validate Error Objects Before Processing
+- **DO**: Verify error types and properties before accessing them. Use `instanceof` checks or error codes.
+- **DON'T**: Assume all caught errors are `Error` instances or have expected properties.
+- **WHY**: JavaScript can throw any value. Accessing `.message` or `.stack` on non-Error values causes secondary failures.
+
+### 7. Implement Request Timeouts and Resource Limits
+- **DO**: Set timeouts for all external requests, database queries, and file operations. Limit request body size and processing time.
+- **DON'T**: Allow requests or operations to run indefinitely without timeout boundaries.
+- **WHY**: Missing timeouts lead to resource exhaustion, blocked event loops, and denial of service.
+
+## Code Examples
+
+### Bad Practice
+```javascript
+// Failing open - granting access on error
+async function checkPermission(userId, resource) {
+  try {
+    const allowed = await authService.check(userId, resource);
+    return allowed;
+  } catch (error) {
+    return true; // DANGEROUS: fail-open grants access on auth service failure
+  }
+}
+
+// Empty catch block hiding errors
+try {
+  await processPayment(order);
+} catch (e) {
+  // silently swallowed - payment may have partially processed
+}
+
+// Leaking error details to client
+app.use((err, req, res, next) => {
+  res.status(500).json({
+    error: err.message,
+    stack: err.stack,
+    sql: err.query,
+  });
+});
+
+// No timeout on external request
+const response = await fetch("https://external-api.com/data"); // Hangs forever if API is down
+```
+
+### Good Practice
+```javascript
+// Fail-safe: deny access on error
+async function checkPermission(userId, resource) {
+  try {
+    return await authService.check(userId, resource);
+  } catch (error) {
+    logger.error({ userId, resource, error: error.message }, "Auth service failed");
+    return false; // Fail-safe: deny access on error
+  }
+}
+
+// Structured error handling with Result pattern
+class Result {
+  constructor(ok, value, error) {
+    this.ok = ok;
+    this.value = value;
+    this.error = error;
+  }
+  static success(value) { return new Result(true, value, null); }
+  static failure(error) { return new Result(false, null, error); }
+}
+
+async function processPayment(order) {
+  try {
+    const result = await paymentGateway.charge(order);
+    return Result.success(result);
+  } catch (error) {
+    logger.error({ orderId: order.id, error: error.message }, "Payment failed");
+    return Result.failure(new PaymentError("Payment processing failed", { cause: error }));
+  }
+}
+
+// Safe error handler separating internal/external messages
+app.use((err, req, res, next) => {
+  const errorId = crypto.randomUUID();
+  logger.error({ errorId, path: req.path, method: req.method, error: err.message, stack: err.stack });
+  const status = err.status ?? 500;
+  res.status(status).json({
+    error: status < 500 ? err.message : "An internal error occurred",
+    errorId,
+  });
+});
+
+// Circuit breaker for external services
+class CircuitBreaker {
+  #failures = 0;
+  #lastFailure = 0;
+  #state = "closed"; // closed, open, half-open
+
+  constructor(threshold = 5, resetTimeout = 30_000) {
+    this.threshold = threshold;
+    this.resetTimeout = resetTimeout;
+  }
+
+  async execute(fn) {
+    if (this.#state === "open") {
+      if (Date.now() - this.#lastFailure > this.resetTimeout) {
+        this.#state = "half-open";
+      } else {
+        throw new Error("Circuit breaker is open");
+      }
+    }
+    try {
+      const result = await fn();
+      this.#failures = 0;
+      this.#state = "closed";
+      return result;
+    } catch (error) {
+      this.#failures++;
+      this.#lastFailure = Date.now();
+      if (this.#failures >= this.threshold) this.#state = "open";
+      throw error;
+    }
+  }
+}
+
+// Request with timeout
+async function fetchWithTimeout(url, options = {}, timeoutMs = 5000) {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetch(url, { ...options, signal: controller.signal });
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+// Global safety net (not a substitute for proper error handling)
+process.on("unhandledRejection", (reason) => {
+  logger.fatal({ reason: String(reason) }, "Unhandled promise rejection");
+  process.exitCode = 1;
+});
+```
+
+## Quick Checklist
+- [ ] All error paths fail-safe (deny access, reject transactions)
+- [ ] No empty catch blocks in the codebase
+- [ ] Internal errors logged with full detail; external responses are generic
+- [ ] Circuit breakers implemented for external service calls
+- [ ] All promises have `.catch()` or are inside try-catch with await
+- [ ] Global `unhandledRejection` handler registered as safety net
+- [ ] Timeouts set for all HTTP requests, database queries, and I/O operations
+- [ ] Request body size limits enforced
+- [ ] Error objects validated before accessing properties