skillstore-cli 1.0.0

package/data/shared/framework/skills/security-audit/references/secure-coding-patterns.md

@@ -0,0 +1,433 @@
+# Secure Coding Patterns
+
+Reusable security patterns for common development scenarios. Each pattern includes rationale, implementation code, and common mistakes to avoid.
+
+---
+
+## Input Validation
+
+### Allowlist Approach
+Always validate against what is expected, not what is forbidden. Denylists are inherently incomplete.
+
+```javascript
+// GOOD: Allowlist — only accept known-valid values
+const VALID_SORT_FIELDS = ['name', 'created_at', 'price', 'rating'];
+const VALID_SORT_ORDERS = ['asc', 'desc'];
+
+function validateSortParams(field, order) {
+  if (!VALID_SORT_FIELDS.includes(field)) throw new Error('Invalid sort field');
+  if (!VALID_SORT_ORDERS.includes(order)) throw new Error('Invalid sort order');
+  return { field, order };
+}
+
+// BAD: Denylist — will always miss something
+function validateSortField(field) {
+  if (field.includes(';') || field.includes('--')) throw new Error('Invalid');
+  return field;  // Still injectable via many other vectors
+}
+```
+
+### Schema Validation (Zod)
+```typescript
+import { z } from 'zod';
+
+const CreateUserSchema = z.object({
+  email: z.string().email().max(254),
+  password: z.string().min(12).max(128),
+  name: z.string().min(1).max(100).regex(/^[\p{L}\p{N}\s'-]+$/u),
+  role: z.enum(['user', 'editor']),   // Never allow 'admin' via API
+  age: z.number().int().min(13).max(150).optional(),
+});
+
+// In route handler
+app.post('/api/users', async (req, res) => {
+  const result = CreateUserSchema.safeParse(req.body);
+  if (!result.success) {
+    return res.status(400).json({ errors: result.error.flatten().fieldErrors });
+  }
+  const validatedData = result.data;
+  // Proceed with validated data only
+});
+```
+
+### Sanitization vs. Validation
+- **Validation:** Reject invalid input entirely (preferred)
+- **Sanitization:** Transform input to a safe form (use only when you must accept rich content)
+- Rule: Validate first, sanitize only as a secondary measure for specific fields (e.g., HTML content)
+
+---
+
+## Output Encoding
+
+Context-specific encoding is critical. There is no universal "escape" function.
+
+### Encoding by Context
+
+| Context | Encoding | Example |
+|---|---|---|
+| HTML body | HTML entity encode | `<` → `&lt;` |
+| HTML attribute | HTML entity encode + quote | `"` → `&quot;` |
+| JavaScript string | JavaScript Unicode escape | `'` → `\u0027` |
+| URL parameter | Percent encode | ` ` → `%20` |
+| CSS value | CSS hex escape | `(` → `\28` |
+
+```javascript
+// React/JSX: Auto-escapes by default — safe
+const UserGreeting = ({ name }) => <h1>Hello, {name}</h1>;
+
+// Dangerous: Bypasses React's auto-escaping
+const UnsafeContent = ({ html }) => (
+  <div dangerouslySetInnerHTML={{ __html: html }} />  // XSS if html is untrusted
+);
+
+// Safe: Sanitize before rendering raw HTML
+import DOMPurify from 'dompurify';
+const SafeContent = ({ html }) => (
+  <div dangerouslySetInnerHTML={{ __html: DOMPurify.sanitize(html, {
+    ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'a', 'p', 'br', 'ul', 'ol', 'li'],
+    ALLOWED_ATTR: ['href', 'target', 'rel'],
+  }) }} />
+);
+```
+
+---
+
+## Parameterized Queries
+
+Never concatenate user input into SQL queries. Use parameterized statements in every language.
+
+### Node.js (pg — PostgreSQL)
+```javascript
+// Parameterized query — $1, $2 placeholders
+const result = await pool.query(
+  'SELECT * FROM users WHERE email = $1 AND status = $2',
+  [email, 'active']
+);
+```
+
+### Python (psycopg2 — PostgreSQL)
+```python
+# %s placeholders with tuple parameter
+cursor.execute(
+    "SELECT * FROM users WHERE email = %s AND status = %s",
+    (email, "active")
+)
+```
+
+### Java (JDBC — Prepared Statement)
+```java
+PreparedStatement stmt = connection.prepareStatement(
+    "SELECT * FROM users WHERE email = ? AND status = ?"
+);
+stmt.setString(1, email);
+stmt.setString(2, "active");
+ResultSet rs = stmt.executeQuery();
+```
+
+### ORM Safety Note
+ORMs generally produce parameterized queries, but raw query methods are still vulnerable:
+```javascript
+// Sequelize — SAFE
+await User.findAll({ where: { email: userInput } });
+
+// Sequelize — VULNERABLE (raw query with interpolation)
+await sequelize.query(`SELECT * FROM users WHERE email = '${userInput}'`);
+
+// Sequelize — SAFE (raw query with bind)
+await sequelize.query('SELECT * FROM users WHERE email = $1', {
+  bind: [userInput], type: QueryTypes.SELECT
+});
+```
+
+---
+
+## CSRF Protection
+
+### SameSite Cookies (Primary Defense)
+```javascript
+// SameSite=Lax: Cookie not sent on cross-origin POST (prevents CSRF for state-changing requests)
+res.cookie('session', token, {
+  httpOnly: true,
+  secure: true,
+  sameSite: 'lax',
+});
+```
+
+### CSRF Tokens (Defense in Depth)
+```javascript
+const csrf = require('csurf');
+const csrfProtection = csrf({ cookie: { httpOnly: true, sameSite: 'strict' } });
+
+// Include token in forms
+app.get('/form', csrfProtection, (req, res) => {
+  res.render('form', { csrfToken: req.csrfToken() });
+});
+
+// Validate token on submission
+app.post('/submit', csrfProtection, (req, res) => {
+  // csurf middleware automatically validates _csrf field
+});
+```
+
+### Double-Submit Cookie Pattern
+```javascript
+// For SPAs where server-rendered tokens are impractical
+// 1. Set a random CSRF token in a non-HttpOnly cookie
+// 2. JavaScript reads the cookie and sends it as a header
+// 3. Server validates cookie value matches header value
+
+app.use((req, res, next) => {
+  if (['POST', 'PUT', 'DELETE', 'PATCH'].includes(req.method)) {
+    const cookieToken = req.cookies['csrf-token'];
+    const headerToken = req.headers['x-csrf-token'];
+    if (!cookieToken || cookieToken !== headerToken) {
+      return res.status(403).json({ error: 'CSRF validation failed' });
+    }
+  }
+  next();
+});
+```
+
+---
+
+## Secure Session Management
+
+### Cookie Flags
+| Flag | Purpose | Setting |
+|---|---|---|
+| `HttpOnly` | Prevents JavaScript access | Always `true` |
+| `Secure` | HTTPS-only transmission | Always `true` in production |
+| `SameSite` | Cross-origin request control | `Lax` (default) or `Strict` |
+| `Path` | Cookie scope | `/` (or narrower) |
+| `Max-Age` | Expiration | 3600 (1h) for sessions |
+
+### Session Rotation on Authentication State Change
+```javascript
+// Regenerate session ID on: login, logout, privilege change
+function regenerateSession(req) {
+  return new Promise((resolve, reject) => {
+    const data = { ...req.session };
+    req.session.regenerate((err) => {
+      if (err) return reject(err);
+      Object.assign(req.session, data);
+      resolve();
+    });
+  });
+}
+
+// On login
+await regenerateSession(req);
+req.session.userId = user.id;
+
+// On logout
+req.session.destroy((err) => {
+  res.clearCookie('__Host-sid');
+  res.json({ success: true });
+});
+```
+
+---
+
+## Password Handling
+
+### Algorithm Hierarchy
+1. **Argon2id** (preferred) — memory-hard, resistant to GPU/ASIC attacks
+2. **bcrypt** (acceptable) — widely supported, cost factor >= 12
+3. **PBKDF2** (minimum) — only if Argon2/bcrypt unavailable, iterations >= 600,000
+
+### Password Policy Implementation
+```javascript
+const zxcvbn = require('zxcvbn');
+
+function validatePassword(password) {
+  const errors = [];
+
+  if (password.length < 12) errors.push('Minimum 12 characters');
+  if (password.length > 128) errors.push('Maximum 128 characters');
+
+  // Strength check (zxcvbn score 0-4, require >= 3)
+  const strength = zxcvbn(password);
+  if (strength.score < 3) {
+    errors.push(`Password is too weak: ${strength.feedback.warning || 'Try a longer or more complex password'}`);
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+```
+
+---
+
+## API Key Management
+
+### Environment Variables (Minimum)
+```javascript
+// Access via environment — never hardcode
+const apiKey = process.env.STRIPE_SECRET_KEY;
+if (!apiKey) throw new Error('STRIPE_SECRET_KEY is not configured');
+```
+
+### Secrets Manager Pattern
+```javascript
+const { SecretsManagerClient, GetSecretValueCommand } = require('@aws-sdk/client-secrets-manager');
+
+async function getSecret(secretName) {
+  const client = new SecretsManagerClient({ region: 'us-east-1' });
+  const response = await client.send(new GetSecretValueCommand({ SecretId: secretName }));
+  return JSON.parse(response.SecretString);
+}
+
+// Cache secrets to avoid repeated calls
+let cachedSecrets = null;
+async function getSecrets() {
+  if (!cachedSecrets) {
+    cachedSecrets = await getSecret('app/production/keys');
+    // Refresh cache every hour
+    setTimeout(() => { cachedSecrets = null; }, 3600000);
+  }
+  return cachedSecrets;
+}
+```
+
+### Key Rotation Pattern
+- Generate new key → deploy to consumers → mark old key deprecated → monitor for old key usage → revoke old key
+- Automate with a minimum 90-day rotation cycle
+- Never log API keys; mask in any output (`sk_live_...abc1`)
+
+---
+
+## Content Security Policy (CSP)
+
+### Directive Reference
+| Directive | Controls | Recommended |
+|---|---|---|
+| `default-src` | Fallback for all types | `'self'` |
+| `script-src` | JavaScript sources | `'self'` + nonce |
+| `style-src` | CSS sources | `'self'` + nonce or `'unsafe-inline'` |
+| `img-src` | Image sources | `'self' data: https:` |
+| `connect-src` | XHR, fetch, WebSocket | `'self'` + API domains |
+| `frame-src` | Iframes | `'none'` |
+| `object-src` | Plugins (Flash, Java) | `'none'` |
+| `base-uri` | `<base>` tag | `'self'` |
+
+### Nonce-Based CSP
+```javascript
+const crypto = require('crypto');
+
+app.use((req, res, next) => {
+  const nonce = crypto.randomBytes(16).toString('base64');
+  res.locals.cspNonce = nonce;
+  res.setHeader('Content-Security-Policy',
+    `default-src 'self'; script-src 'self' 'nonce-${nonce}'; style-src 'self' 'nonce-${nonce}'; object-src 'none'; base-uri 'self';`
+  );
+  next();
+});
+
+// In templates: <script nonce="<%= cspNonce %>">...</script>
+```
+
+---
+
+## CORS Configuration
+
+```javascript
+const cors = require('cors');
+
+app.use(cors({
+  origin: ['https://app.example.com', 'https://admin.example.com'],  // Explicit origins
+  methods: ['GET', 'POST', 'PUT', 'DELETE'],
+  allowedHeaders: ['Content-Type', 'Authorization', 'X-CSRF-Token'],
+  credentials: true,         // Allow cookies
+  maxAge: 86400,             // Cache preflight for 24h
+}));
+
+// NEVER do this in production:
+// origin: '*'           — allows any origin
+// origin: true          — reflects any origin (equivalent to *)
+// credentials: true with origin: '*' — browsers block this, but misconfig is dangerous
+```
+
+---
+
+## Rate Limiting
+
+### Sliding Window Implementation
+```javascript
+const rateLimit = require('express-rate-limit');
+const RedisStore = require('rate-limit-redis').default;
+const Redis = require('ioredis');
+
+const redisClient = new Redis(process.env.REDIS_URL);
+
+// Tiered rate limiting
+const apiLimiter = rateLimit({
+  store: new RedisStore({ sendCommand: (...args) => redisClient.call(...args) }),
+  windowMs: 60 * 1000,     // 1 minute
+  max: 100,                 // 100 requests per minute
+  standardHeaders: true,
+  legacyHeaders: false,
+  keyGenerator: (req) => req.user?.id || req.ip,
+  skip: (req) => req.user?.role === 'service-account',
+});
+
+// Stricter limits for sensitive endpoints
+const authLimiter = rateLimit({
+  store: new RedisStore({ sendCommand: (...args) => redisClient.call(...args) }),
+  windowMs: 15 * 60 * 1000,  // 15 minutes
+  max: 5,
+  keyGenerator: (req) => req.body.email || req.ip,
+});
+
+app.use('/api/', apiLimiter);
+app.post('/api/auth/login', authLimiter);
+app.post('/api/auth/reset-password', authLimiter);
+```
+
+---
+
+## JWT Security
+
+### Algorithm Validation
+```javascript
+const jwt = require('jsonwebtoken');
+
+// ALWAYS specify algorithm explicitly to prevent algorithm confusion attacks
+const JWT_SECRET = process.env.JWT_SECRET;
+const JWT_OPTIONS = {
+  algorithms: ['HS256'],     // Allowlist — prevents "none" and RS256 confusion
+  issuer: 'app.example.com',
+  audience: 'app.example.com',
+};
+
+function verifyToken(token) {
+  return jwt.verify(token, JWT_SECRET, JWT_OPTIONS);
+}
+
+// Short-lived access tokens + refresh token rotation
+function generateTokenPair(userId) {
+  const accessToken = jwt.sign({ sub: userId, type: 'access' }, JWT_SECRET, {
+    expiresIn: '15m',
+    issuer: 'app.example.com',
+  });
+  const refreshToken = jwt.sign({ sub: userId, type: 'refresh' }, JWT_SECRET, {
+    expiresIn: '7d',
+    issuer: 'app.example.com',
+    jwtid: crypto.randomUUID(),   // Unique ID for revocation tracking
+  });
+  return { accessToken, refreshToken };
+}
+```
+
+### Token Revocation
+```javascript
+// Maintain a denylist of revoked token IDs (jti) in Redis
+async function revokeToken(jti, expiresAt) {
+  const ttl = Math.ceil((expiresAt * 1000 - Date.now()) / 1000);
+  if (ttl > 0) {
+    await redisClient.setex(`revoked:${jti}`, ttl, '1');
+  }
+}
+
+async function isTokenRevoked(jti) {
+  return await redisClient.exists(`revoked:${jti}`);
+}
+```