@mmerterden/multi-agent-pipeline 20.1.0 → 20.2.0

package/pipeline/skills/shared/external/api-security-best-practices/references/auth.md

@@ -0,0 +1,299 @@
+# Authentication & Authorization Patterns
+
+Full implementations for JWT-based authentication, token refresh, route protection, and the authorization pitfalls that most often ship broken.
+
+## JWT Authentication Flow
+
+1. User logs in with credentials
+2. Server validates credentials
+3. Server generates JWT token
+4. Client stores token securely
+5. Client sends token with each request
+6. Server validates token
+
+## 1. Generate Secure JWT Tokens
+
+```javascript
+// auth.js
+const jwt = require('jsonwebtoken');
+const bcrypt = require('bcrypt');
+
+// Login endpoint
+app.post('/api/auth/login', async (req, res) => {
+  try {
+    const { email, password } = req.body;
+
+    // Validate input
+    if (!email || !password) {
+      return res.status(400).json({
+        error: 'Email and password are required'
+      });
+    }
+
+    // Find user
+    const user = await db.user.findUnique({
+      where: { email }
+    });
+
+    if (!user) {
+      // Don't reveal if user exists
+      return res.status(401).json({
+        error: 'Invalid credentials'
+      });
+    }
+
+    // Verify password
+    const validPassword = await bcrypt.compare(
+      password,
+      user.passwordHash
+    );
+
+    if (!validPassword) {
+      return res.status(401).json({
+        error: 'Invalid credentials'
+      });
+    }
+
+    // Generate JWT token
+    const token = jwt.sign(
+      {
+        userId: user.id,
+        email: user.email,
+        role: user.role
+      },
+      process.env.JWT_SECRET,
+      {
+        expiresIn: '1h',
+        issuer: 'your-app',
+        audience: 'your-app-users'
+      }
+    );
+
+    // Generate refresh token
+    const refreshToken = jwt.sign(
+      { userId: user.id },
+      process.env.JWT_REFRESH_SECRET,
+      { expiresIn: '7d' }
+    );
+
+    // Store refresh token in database
+    await db.refreshToken.create({
+      data: {
+        token: refreshToken,
+        userId: user.id,
+        expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000)
+      }
+    });
+
+    res.json({
+      token,
+      refreshToken,
+      expiresIn: 3600
+    });
+
+  } catch (error) {
+    console.error('Login error:', error);
+    res.status(500).json({
+      error: 'An error occurred during login'
+    });
+  }
+});
+```
+
+## 2. Verify JWT Tokens (Middleware)
+
+```javascript
+// middleware/auth.js
+const jwt = require('jsonwebtoken');
+
+function authenticateToken(req, res, next) {
+  // Get token from header
+  const authHeader = req.headers['authorization'];
+  const token = authHeader && authHeader.split(' ')[1]; // Bearer TOKEN
+
+  if (!token) {
+    return res.status(401).json({
+      error: 'Access token required'
+    });
+  }
+
+  // Verify token
+  jwt.verify(
+    token,
+    process.env.JWT_SECRET,
+    {
+      issuer: 'your-app',
+      audience: 'your-app-users'
+    },
+    (err, user) => {
+      if (err) {
+        if (err.name === 'TokenExpiredError') {
+          return res.status(401).json({
+            error: 'Token expired'
+          });
+        }
+        return res.status(403).json({
+          error: 'Invalid token'
+        });
+      }
+
+      // Attach user to request
+      req.user = user;
+      next();
+    }
+  );
+}
+
+module.exports = { authenticateToken };
+```
+
+## 3. Protect Routes
+
+```javascript
+const { authenticateToken } = require('./middleware/auth');
+
+// Protected route
+app.get('/api/user/profile', authenticateToken, async (req, res) => {
+  try {
+    const user = await db.user.findUnique({
+      where: { id: req.user.userId },
+      select: {
+        id: true,
+        email: true,
+        name: true,
+        // Don't return passwordHash
+      }
+    });
+
+    res.json(user);
+  } catch (error) {
+    res.status(500).json({ error: 'Server error' });
+  }
+});
+```
+
+## 4. Implement Token Refresh
+
+```javascript
+app.post('/api/auth/refresh', async (req, res) => {
+  const { refreshToken } = req.body;
+
+  if (!refreshToken) {
+    return res.status(401).json({
+      error: 'Refresh token required'
+    });
+  }
+
+  try {
+    // Verify refresh token
+    const decoded = jwt.verify(
+      refreshToken,
+      process.env.JWT_REFRESH_SECRET
+    );
+
+    // Check if refresh token exists in database
+    const storedToken = await db.refreshToken.findFirst({
+      where: {
+        token: refreshToken,
+        userId: decoded.userId,
+        expiresAt: { gt: new Date() }
+      }
+    });
+
+    if (!storedToken) {
+      return res.status(403).json({
+        error: 'Invalid refresh token'
+      });
+    }
+
+    // Generate new access token
+    const user = await db.user.findUnique({
+      where: { id: decoded.userId }
+    });
+
+    const newToken = jwt.sign(
+      {
+        userId: user.id,
+        email: user.email,
+        role: user.role
+      },
+      process.env.JWT_SECRET,
+      { expiresIn: '1h' }
+    );
+
+    res.json({
+      token: newToken,
+      expiresIn: 3600
+    });
+
+  } catch (error) {
+    res.status(403).json({
+      error: 'Invalid refresh token'
+    });
+  }
+});
+```
+
+## JWT Security Best Practices
+
+- Use strong JWT secrets (256-bit minimum)
+- Set short expiration times (1 hour for access tokens)
+- Implement refresh tokens for long-lived sessions
+- Store refresh tokens in database (can be revoked)
+- Use HTTPS only
+- Don't store sensitive data in JWT payload
+- Validate token issuer and audience
+- Implement token blacklisting for logout
+
+## Common Pitfalls
+
+### JWT Secret Exposed in Code
+
+Symptoms: JWT secret hardcoded or committed to Git.
+
+```javascript
+// Bad
+const JWT_SECRET = 'my-secret-key';
+
+// Good
+const JWT_SECRET = process.env.JWT_SECRET;
+if (!JWT_SECRET) {
+  throw new Error('JWT_SECRET environment variable is required');
+}
+
+// Generate strong secret
+// node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"
+```
+
+### Missing Authorization Checks
+
+Symptoms: Users can access resources they shouldn't. Authentication proves who the caller is; authorization proves they may act on this resource.
+
+```javascript
+// Bad: Only checks authentication
+app.delete('/api/posts/:id', authenticateToken, async (req, res) => {
+  await prisma.post.delete({ where: { id: req.params.id } });
+  res.json({ success: true });
+});
+
+// Good: Checks both authentication and authorization
+app.delete('/api/posts/:id', authenticateToken, async (req, res) => {
+  const post = await prisma.post.findUnique({
+    where: { id: req.params.id }
+  });
+
+  if (!post) {
+    return res.status(404).json({ error: 'Post not found' });
+  }
+
+  // Check if user owns the post or is admin
+  if (post.userId !== req.user.userId && req.user.role !== 'admin') {
+    return res.status(403).json({
+      error: 'Not authorized to delete this post'
+    });
+  }
+
+  await prisma.post.delete({ where: { id: req.params.id } });
+  res.json({ success: true });
+});
+```

package/pipeline/skills/shared/external/api-security-best-practices/references/input-validation.md

@@ -0,0 +1,255 @@
+# Input Validation & Injection Prevention
+
+Full implementations for SQL injection prevention, schema validation, output sanitization, plus the password-strength and error-message pitfalls.
+
+## The Problem: SQL Injection
+
+```javascript
+// NEVER DO THIS - SQL Injection vulnerability
+app.get('/api/users/:id', async (req, res) => {
+  const userId = req.params.id;
+
+  // Dangerous: User input directly in query
+  const query = `SELECT * FROM users WHERE id = '${userId}'`;
+  const user = await db.query(query);
+
+  res.json(user);
+});
+
+// Attack example:
+// GET /api/users/1' OR '1'='1
+// Returns all users!
+```
+
+## 1. Use Parameterized Queries
+
+```javascript
+// Safe: Parameterized query
+app.get('/api/users/:id', async (req, res) => {
+  const userId = req.params.id;
+
+  // Validate input first
+  if (!userId || !/^\d+$/.test(userId)) {
+    return res.status(400).json({
+      error: 'Invalid user ID'
+    });
+  }
+
+  // Use parameterized query
+  const user = await db.query(
+    'SELECT id, email, name FROM users WHERE id = $1',
+    [userId]
+  );
+
+  if (!user) {
+    return res.status(404).json({
+      error: 'User not found'
+    });
+  }
+
+  res.json(user);
+});
+```
+
+## 2. Use ORM with Proper Escaping
+
+```javascript
+// Safe: Using Prisma ORM
+app.get('/api/users/:id', async (req, res) => {
+  const userId = parseInt(req.params.id);
+
+  if (isNaN(userId)) {
+    return res.status(400).json({
+      error: 'Invalid user ID'
+    });
+  }
+
+  const user = await prisma.user.findUnique({
+    where: { id: userId },
+    select: {
+      id: true,
+      email: true,
+      name: true,
+      // Don't select sensitive fields
+    }
+  });
+
+  if (!user) {
+    return res.status(404).json({
+      error: 'User not found'
+    });
+  }
+
+  res.json(user);
+});
+```
+
+## 3. Implement Request Validation with Zod
+
+```javascript
+const { z } = require('zod');
+
+// Define validation schema
+const createUserSchema = z.object({
+  email: z.string().email('Invalid email format'),
+  password: z.string()
+    .min(8, 'Password must be at least 8 characters')
+    .regex(/[A-Z]/, 'Password must contain uppercase letter')
+    .regex(/[a-z]/, 'Password must contain lowercase letter')
+    .regex(/[0-9]/, 'Password must contain number'),
+  name: z.string()
+    .min(2, 'Name must be at least 2 characters')
+    .max(100, 'Name too long'),
+  age: z.number()
+    .int('Age must be an integer')
+    .min(18, 'Must be 18 or older')
+    .max(120, 'Invalid age')
+    .optional()
+});
+
+// Validation middleware
+function validateRequest(schema) {
+  return (req, res, next) => {
+    try {
+      schema.parse(req.body);
+      next();
+    } catch (error) {
+      res.status(400).json({
+        error: 'Validation failed',
+        details: error.errors
+      });
+    }
+  };
+}
+
+// Use validation
+app.post('/api/users',
+  validateRequest(createUserSchema),
+  async (req, res) => {
+    // Input is validated at this point
+    const { email, password, name, age } = req.body;
+
+    // Hash password
+    const passwordHash = await bcrypt.hash(password, 10);
+
+    // Create user
+    const user = await prisma.user.create({
+      data: {
+        email,
+        passwordHash,
+        name,
+        age
+      }
+    });
+
+    // Don't return password hash
+    const { passwordHash: _, ...userWithoutPassword } = user;
+    res.status(201).json(userWithoutPassword);
+  }
+);
+```
+
+## 4. Sanitize Output to Prevent XSS
+
+```javascript
+const DOMPurify = require('isomorphic-dompurify');
+
+app.post('/api/comments', authenticateToken, async (req, res) => {
+  const { content } = req.body;
+
+  // Validate
+  if (!content || content.length > 1000) {
+    return res.status(400).json({
+      error: 'Invalid comment content'
+    });
+  }
+
+  // Sanitize HTML to prevent XSS
+  const sanitizedContent = DOMPurify.sanitize(content, {
+    ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'a'],
+    ALLOWED_ATTR: ['href']
+  });
+
+  const comment = await prisma.comment.create({
+    data: {
+      content: sanitizedContent,
+      userId: req.user.userId
+    }
+  });
+
+  res.status(201).json(comment);
+});
+```
+
+## Validation Checklist
+
+- [ ] Validate all user inputs
+- [ ] Use parameterized queries or ORM
+- [ ] Validate data types (string, number, email, etc.)
+- [ ] Validate data ranges (min/max length, value ranges)
+- [ ] Sanitize HTML content
+- [ ] Escape special characters
+- [ ] Validate file uploads (type, size, content)
+- [ ] Use allowlists, not blocklists
+
+## Common Pitfalls
+
+### Weak Password Requirements
+
+Symptoms: Users can set weak passwords like "password123".
+
+```javascript
+const passwordSchema = z.string()
+  .min(12, 'Password must be at least 12 characters')
+  .regex(/[A-Z]/, 'Must contain uppercase letter')
+  .regex(/[a-z]/, 'Must contain lowercase letter')
+  .regex(/[0-9]/, 'Must contain number')
+  .regex(/[^A-Za-z0-9]/, 'Must contain special character');
+
+// Or use a password strength library
+const zxcvbn = require('zxcvbn');
+const result = zxcvbn(password);
+if (result.score < 3) {
+  return res.status(400).json({
+    error: 'Password too weak',
+    suggestions: result.feedback.suggestions
+  });
+}
+```
+
+### Verbose Error Messages
+
+Symptoms: Error messages reveal system details. Log the full error server-side, return a generic message to the client.
+
+```javascript
+// Bad: Exposes database details
+app.post('/api/users', async (req, res) => {
+  try {
+    const user = await prisma.user.create({ data: req.body });
+    res.json(user);
+  } catch (error) {
+    res.status(500).json({ error: error.message });
+    // Error: "Unique constraint failed on the fields: (`email`)"
+  }
+});
+
+// Good: Generic error message
+app.post('/api/users', async (req, res) => {
+  try {
+    const user = await prisma.user.create({ data: req.body });
+    res.json(user);
+  } catch (error) {
+    console.error('User creation error:', error); // Log full error
+
+    if (error.code === 'P2002') {
+      return res.status(400).json({
+        error: 'Email already exists'
+      });
+    }
+
+    res.status(500).json({
+      error: 'An error occurred while creating user'
+    });
+  }
+});
+```

package/pipeline/skills/shared/external/api-security-best-practices/references/rate-limiting.md

@@ -0,0 +1,167 @@
+# Rate Limiting & DDoS Protection
+
+Full implementations for fixed-window and tiered rate limiting, security headers, and rate-limit response headers.
+
+## Why Rate Limiting?
+
+- Prevent brute force attacks
+- Protect against DDoS
+- Prevent API abuse
+- Ensure fair usage
+- Reduce server costs
+
+## Implementation with Express Rate Limit
+
+```javascript
+const rateLimit = require('express-rate-limit');
+const RedisStore = require('rate-limit-redis');
+const Redis = require('ioredis');
+
+// Create Redis client
+const redis = new Redis({
+  host: process.env.REDIS_HOST,
+  port: process.env.REDIS_PORT
+});
+
+// General API rate limit
+const apiLimiter = rateLimit({
+  store: new RedisStore({
+    client: redis,
+    prefix: 'rl:api:'
+  }),
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 100, // 100 requests per window
+  message: {
+    error: 'Too many requests, please try again later',
+    retryAfter: 900 // seconds
+  },
+  standardHeaders: true, // Return rate limit info in headers
+  legacyHeaders: false,
+  // Custom key generator (by user ID or IP)
+  keyGenerator: (req) => {
+    return req.user?.userId || req.ip;
+  }
+});
+
+// Strict rate limit for authentication endpoints
+const authLimiter = rateLimit({
+  store: new RedisStore({
+    client: redis,
+    prefix: 'rl:auth:'
+  }),
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 5, // Only 5 login attempts per 15 minutes
+  skipSuccessfulRequests: true, // Don't count successful logins
+  message: {
+    error: 'Too many login attempts, please try again later',
+    retryAfter: 900
+  }
+});
+
+// Apply rate limiters
+app.use('/api/', apiLimiter);
+app.use('/api/auth/login', authLimiter);
+app.use('/api/auth/register', authLimiter);
+
+// Custom rate limiter for expensive operations
+const expensiveLimiter = rateLimit({
+  windowMs: 60 * 60 * 1000, // 1 hour
+  max: 10, // 10 requests per hour
+  message: {
+    error: 'Rate limit exceeded for this operation'
+  }
+});
+
+app.post('/api/reports/generate',
+  authenticateToken,
+  expensiveLimiter,
+  async (req, res) => {
+    // Expensive operation
+  }
+);
+```
+
+## Advanced: Per-User Rate Limiting
+
+```javascript
+// Different limits based on user tier
+function createTieredRateLimiter() {
+  const limits = {
+    free: { windowMs: 60 * 60 * 1000, max: 100 },
+    pro: { windowMs: 60 * 60 * 1000, max: 1000 },
+    enterprise: { windowMs: 60 * 60 * 1000, max: 10000 }
+  };
+
+  return async (req, res, next) => {
+    const user = req.user;
+    const tier = user?.tier || 'free';
+    const limit = limits[tier];
+
+    const key = `rl:user:${user.userId}`;
+    const current = await redis.incr(key);
+
+    if (current === 1) {
+      await redis.expire(key, limit.windowMs / 1000);
+    }
+
+    if (current > limit.max) {
+      return res.status(429).json({
+        error: 'Rate limit exceeded',
+        limit: limit.max,
+        remaining: 0,
+        reset: await redis.ttl(key)
+      });
+    }
+
+    // Set rate limit headers
+    res.set({
+      'X-RateLimit-Limit': limit.max,
+      'X-RateLimit-Remaining': limit.max - current,
+      'X-RateLimit-Reset': await redis.ttl(key)
+    });
+
+    next();
+  };
+}
+
+app.use('/api/', authenticateToken, createTieredRateLimiter());
+```
+
+## DDoS Protection with Helmet
+
+```javascript
+const helmet = require('helmet');
+
+app.use(helmet({
+  // Content Security Policy
+  contentSecurityPolicy: {
+    directives: {
+      defaultSrc: ["'self'"],
+      styleSrc: ["'self'", "'unsafe-inline'"],
+      scriptSrc: ["'self'"],
+      imgSrc: ["'self'", 'data:', 'https:']
+    }
+  },
+  // Prevent clickjacking
+  frameguard: { action: 'deny' },
+  // Hide X-Powered-By header
+  hidePoweredBy: true,
+  // Prevent MIME type sniffing
+  noSniff: true,
+  // Enable HSTS
+  hsts: {
+    maxAge: 31536000,
+    includeSubDomains: true,
+    preload: true
+  }
+}));
+```
+
+## Rate Limit Response Headers
+
+```
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 87
+X-RateLimit-Reset: 1640000000
+Retry-After: 900
+```