Security Operations & Deployment

When to Apply Each Middleware - Decision Guide

withRateLimit() - Apply to:

✅ Always apply to:

• •Any route that could be abused (spam, brute force)
• •Login-like operations (even if Clerk handles auth)
• •Data creation/modification endpoints
• •Contact/support form endpoints
• •Webhooks (to prevent DoS)
• •File upload endpoints
• •Search endpoints
• •Data export endpoints
• •Any expensive AI/API operations
• •Report generation
• •Bulk operations

❌ Usually not needed for:

• •Static asset requests (handled by CDN)
• •Simple GET endpoints that only read public data
• •Health check endpoints
• •Endpoints already protected by authentication rate limits

withCsrf() - Apply to:

✅ Always apply to:

• •All POST/PUT/DELETE operations
• •Any state-changing operation
• •Form submissions
• •Account modifications
• •Payment operations
• •Data deletion operations

❌ Skip for:

• •GET requests (read-only operations)
• •Public read-only endpoints
• •Webhooks (use signature verification instead)

Combining Both Middlewares

For maximum protection:

// Order matters: rate limit first, then CSRF
export const POST = withRateLimit(withCsrf(handler));

Why order matters:

1. •Rate limiting runs first to block excessive requests early
2. •CSRF verification runs on requests that pass rate limiting
3. •More efficient: don't waste CSRF verification on rate-limited requests

Decision Matrix:

Environment Variables & Secrets

Required Environment Variables for This Project

Development (.env.local - NEVER commit):

# CSRF Protection
# Generate with: node -p "require('crypto').randomBytes(32).toString('base64url')"
CSRF_SECRET=<32-byte-base64url-string>
SESSION_SECRET=<32-byte-base64url-string>

# Clerk Authentication (from Clerk dashboard)
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...
NEXT_PUBLIC_CLERK_FRONTEND_API_URL=https://your-app.clerk.accounts.dev

# Convex Database (from Convex dashboard)
CONVEX_DEPLOYMENT=dev:...
NEXT_PUBLIC_CONVEX_URL=https://...convex.cloud

# Optional: Stripe (if using direct Stripe, not Clerk Billing)
STRIPE_SECRET_KEY=sk_test_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...

# Optional: Clerk Webhook Secret
CLERK_WEBHOOK_SECRET=whsec_...

Production (Vercel/hosting platform):

# CSRF Protection (different from dev!)
CSRF_SECRET=<different-32-byte-string>
SESSION_SECRET=<different-32-byte-string>

# Clerk Production Keys
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_live_...
CLERK_SECRET_KEY=sk_live_...
NEXT_PUBLIC_CLERK_FRONTEND_API_URL=https://your-app.clerk.accounts.com

# Convex Production
CONVEX_DEPLOYMENT=prod:...
NEXT_PUBLIC_CONVEX_URL=https://...convex.cloud

# Optional: Stripe Production
STRIPE_SECRET_KEY=sk_live_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_...

# Optional: Clerk Webhook Secret (production)
CLERK_WEBHOOK_SECRET=whsec_...

Generating Secrets

# Generate CSRF_SECRET (32 bytes)
node -p "require('crypto').randomBytes(32).toString('base64url')"

# Generate SESSION_SECRET (32 bytes)
node -p "require('crypto').randomBytes(32).toString('base64url')"

Environment Variable Best Practices

✅ DO:

• •Use different secrets for dev/staging/production
• •Generate strong random secrets (32+ bytes)
• •Add .env.local to .gitignore
• •Store production secrets in hosting platform's secret manager
• •Rotate secrets quarterly
• •Validate required environment variables on startup

❌ NEVER:

• •Hardcode API keys, tokens, or secrets in code
• •Commit .env.local to version control
• •Log environment variables
• •Expose secrets in client-side code
• •Use .env.local values in NEXT_PUBLIC_* variables (they're exposed to browser!)
• •Share secrets via email, Slack, or insecure channels

Validating Configuration on Startup

// lib/config.ts
const requiredEnvVars = [
  'CSRF_SECRET',
  'SESSION_SECRET',
  'NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY',
  'CLERK_SECRET_KEY',
  'NEXT_PUBLIC_CONVEX_URL'
];

export function validateConfig() {
  const missing = requiredEnvVars.filter(v => !process.env[v]);

  if (missing.length > 0) {
    throw new Error(`Missing required environment variables: ${missing.join(', ')}`);
  }

  // Validate secret lengths
  if (process.env.CSRF_SECRET && process.env.CSRF_SECRET.length < 32) {
    throw new Error('CSRF_SECRET must be at least 32 characters');
  }

  if (process.env.SESSION_SECRET && process.env.SESSION_SECRET.length < 32) {
    throw new Error('SESSION_SECRET must be at least 32 characters');
  }
}

// In your app startup (e.g., middleware.ts or layout.tsx)
validateConfig();

Pre-Deployment Security Checklist

Run through this checklist before every production deployment:

Environment & Configuration

• • All environment variables set in production environment
• • CSRF_SECRET generated and configured (32+ bytes)
• • SESSION_SECRET generated and configured (32+ bytes)
• • Clerk production keys configured (pk_live_..., sk_live_...)
• • Convex production deployment configured
• • Stripe live mode keys configured (if using direct Stripe)
• • .env.local NOT committed to git (check with git status)
• • Different secrets used for dev vs production

Dependencies

• • Run npm audit --production - 0 vulnerabilities
• • Run npm outdated - Check for critical security updates
• • package-lock.json committed to git
• • Next.js on latest stable version (currently 15.5.4+)
• • All critical packages updated

Security Features

• • CSRF protection tested (see security-testing skill)
• • Rate limiting tested (node scripts/test-rate-limit.js)
• • Input validation tested with malicious input
• • Security headers verified (curl -I https://yourapp.com)
• • HSTS enabled in production (automatic in middleware)
• • Error messages are generic in production (no stack traces)

Authentication & Authorization

• • Protected routes require authentication
• • Resource ownership checked before access
• • Subscription status verified for premium features
• • Webhook signatures verified (Clerk, Stripe)
• • Session expiration handled gracefully
• • No hardcoded credentials in code

API Security

• • All POST/PUT/DELETE routes have CSRF protection
• • All public endpoints have rate limiting
• • All user input validated with Zod schemas
• • All errors handled with error handler utilities
• • No sensitive data in logs (passwords, tokens, cards, PII)
• • No hardcoded secrets in code (grep check below)

Payment Security (if applicable)

• • Using Clerk Billing + Stripe (not handling cards directly)
• • Webhooks verified with Svix signatures
• • Subscription status checked on server
• • Test mode disabled in production
• • No card data logged anywhere

Testing

• • Rate limit test passes: node scripts/test-rate-limit.js
• • CSRF protection tested manually
• • Input validation tested with XSS payloads
• • Security headers checked: curl -I https://yourapp.com
• • Authentication flows tested
• • Error handling tested in production mode

Final Checks

# Check for hardcoded secrets
grep -r "sk_live" . --exclude-dir=node_modules
grep -r "AKIA" . --exclude-dir=node_modules
grep -r "api_key.*=" . --exclude-dir=node_modules

# Verify .env.local not in git
git status | grep .env.local  # Should return nothing

# Run full security audit
npm audit --production
bash scripts/security-check.sh

# Test production build
npm run build
NODE_ENV=production npm start

Security Monitoring Post-Deployment

What to Monitor

Server Logs (Daily)

Monitor for these patterns that indicate potential attacks:

Rate Limit Violations (HTTP 429):

- Repeated 429 errors from same IP → potential abuse/brute force
- High volume of 429s → possible distributed attack
- 429s on login endpoints → credential stuffing attempt

CSRF Failures (HTTP 403):

- Repeated 403 with "CSRF token invalid" → potential CSRF attack
- Sudden spike in CSRF failures → possible automated attack
- 403s without prior token fetch → attack bypass attempt

Authentication Failures (HTTP 401/403):

- 401 spikes → potential brute force on protected endpoints
- 403 spikes → unauthorized access attempts
- Pattern of 401 followed by 403 → enumeration attack

Unusual Error Patterns:

- Sudden increase in 500 errors → potential attack or system issue
- 400 errors with validation failures → input attack attempts
- Errors from unusual geographic locations

Metrics to Track (Weekly)

Authentication Metrics:

• •Failed authentication attempts per hour
• •Account lockouts (if implemented)
• •Geographic distribution of login attempts
• •Unusual login times (3am mass logins = bot)

Rate Limiting Metrics:

• •Rate limit violations per IP
• •Top IPs hitting rate limits
• •Endpoints most frequently rate-limited
• •Rate limit violation trends over time

CSRF Protection Metrics:

• •CSRF validation failures
• •CSRF token generation rate
• •Token reuse attempts
• •Missing token attempts

Input Validation Metrics:

• •Validation failures by field
• •XSS attempt patterns (script tags in input)
• •SQL injection attempt patterns
• •Excessive input length attempts

Error Rate Metrics:

• •Error rates by endpoint
• •Error rates by HTTP status code
• •Error rate trends over time
• •Geographic distribution of errors

Setting Up Monitoring

Vercel Logs (Built-in)

# View logs in Vercel dashboard
https://vercel.com/your-project/logs

# Filter by status code
Status: 429  # Rate limited
Status: 403  # CSRF/Forbidden
Status: 401  # Unauthorized

Clerk Dashboard (Authentication)

Monitor in Clerk dashboard:

• •Failed sign-in attempts
• •Account creation rate
• •Session activity
• •Suspicious IP addresses

Custom Logging

// lib/security-logger.ts
export function logSecurityEvent(event: {
  type: 'RATE_LIMIT' | 'CSRF_FAILURE' | 'AUTH_FAILURE' | 'VALIDATION_FAILURE';
  ip?: string;
  userId?: string;
  endpoint?: string;
  details?: Record<string, any>;
}) {
  const log = {
    timestamp: new Date().toISOString(),
    environment: process.env.NODE_ENV,
    ...event
  };

  // In production, send to logging service
  if (process.env.NODE_ENV === 'production') {
    console.log(JSON.stringify(log));
    // Optional: Send to external service (Datadog, LogRocket, etc.)
  } else {
    console.log('Security Event:', log);
  }
}

// Usage in middleware/routes
if (rateLimitExceeded) {
  logSecurityEvent({
    type: 'RATE_LIMIT',
    ip: clientIp,
    endpoint: request.nextUrl.pathname
  });
}

Response Procedures

High-Priority Alerts (Immediate Response):

• •Massive spike in failed authentication (>100/min)
• •CSRF failures from many IPs (coordinated attack)
• •Sudden 500 error rate increase (>10x normal)
• •Known vulnerability being exploited

Medium-Priority (24-hour Response):

• •Gradual increase in rate limit violations
• •Single IP with persistent failed auth attempts
• •New error patterns in logs
• •Unusual traffic from new geographic regions

Low-Priority (Weekly Review):

• •Normal background failed auth attempts
• •Occasional rate limit hits
• •Standard input validation failures
• •Routine error patterns

Automated Alerting

Set up alerts in your hosting platform:

Vercel:

Alerts → New Alert Rule
- Error rate > 10% for 5 minutes → Email/Slack
- 429 responses > 100/min → Email/Slack
- 500 responses > 50/min → Email/Slack

Custom Alerts:

// Monitor and alert on patterns
if (rateLimitViolations > THRESHOLD) {
  await sendAlert({
    severity: 'HIGH',
    message: `Rate limit violations: ${rateLimitViolations}/min`,
    ip: attackerIp
  });
}

Resources & Documentation

Project Security Documentation

Implementation Guides:

• •.claude/skills/security/security-overview/SKILL.md - Overall architecture
• •.claude/skills/security/*/SKILL.md - Individual security features
• •docs/security/SECURITY_IMPLEMENTATION.md - Complete implementation guide
• •README.md - Security Configuration section

Awareness & Learning:

• •.claude/skills/security/security-awareness/ - AI code vulnerability analysis
• •.claude/skills/security/security-awareness/awareness-overview/ - Complete security overview

Testing & Verification Scripts

Security Testing:

• •scripts/test-rate-limit.js - Rate limiting verification
• •scripts/security-check.sh - Dependency audit
• •scripts/security-test.sh - Comprehensive security test suite (if created)

Example Implementations:

• •app/api/example-protected/route.ts - Complete security stack example
• •app/api/test-rate-limit/route.ts - Rate limiting test endpoint
• •app/api/csrf/route.ts - CSRF token generation

External Security Resources

OWASP (Security Standards):

• •OWASP Top 10 2021: https://owasp.org/www-project-top-ten/
• •OWASP Cheat Sheet Series: https://cheatsheetseries.owasp.org
• •OWASP API Security Top 10: https://owasp.org/www-project-api-security/

Framework & Service Docs:

• •Next.js Security: https://nextjs.org/docs/app/guides/security
• •Clerk Security: https://clerk.com/docs/security
• •Convex Security: https://docs.convex.dev/production/hosting/authentication
• •Stripe Security: https://stripe.com/docs/security

Testing Tools:

• •Security Headers Scanner: https://securityheaders.com/
• •Mozilla Observatory: https://observatory.mozilla.org/
• •SSL Labs Test: https://www.ssllabs.com/ssltest/

Maintenance Schedule

Daily

• •Check error logs in Vercel dashboard
• •Monitor Clerk dashboard for failed auth attempts
• •Review any security alerts

Weekly

• •Run npm audit --production
• •Check GitHub Dependabot alerts
• •Review error logs for patterns
• •Check rate limit violation trends

Monthly

• •Full security audit: bash scripts/security-check.sh
• •Update dependencies: npm update + test
• •Review and rotate any compromised secrets
• •Re-run security testing suite
• •Check security headers: https://securityheaders.com/

Quarterly

• •Rotate CSRF_SECRET and SESSION_SECRET
• •Major framework updates (Next.js, React)
• •Full penetration test (manual XSS, CSRF, auth bypass attempts)
• •Review and update security policies
• •Security awareness training (review skills)

Quick Reference Commands

# Generate secrets
node -p "require('crypto').randomBytes(32).toString('base64url')"

# Check for vulnerabilities
npm audit --production

# Check for outdated packages
npm outdated

# Run security test suite
node scripts/test-rate-limit.js
bash scripts/security-check.sh

# Check for hardcoded secrets
grep -r "sk_live" . --exclude-dir=node_modules
grep -r "AKIA" . --exclude-dir=node_modules

# Test security headers
curl -I https://yourapp.com

# Verify .env.local not committed
git status | grep .env.local

# Production build test
npm run build
NODE_ENV=production npm start

Summary: Security Operations Principles

🔒 Before Deployment:

• •Checklist must be 100% complete
• •0 npm audit vulnerabilities
• •All tests passing
• •All environment variables configured

🔒 After Deployment:

• •Monitor logs daily
• •Respond to alerts immediately
• •Review metrics weekly
• •Update dependencies monthly

🔒 Continuous:

• •Security is never "done"
• •Stay updated on new vulnerabilities
• •Keep dependencies current
• •Test security features regularly

For implementation details, refer to individual security skills. For vulnerability awareness, refer to security-awareness skills.