AI-Assisted Security

The codebase includes security context files that help AI agents implement protection correctly. This guide explains how to work with AI on security features.

Context Files for AI

llms/SECURITY.md

Comprehensive security implementation guide covering:

• CSP configuration (static vs nonce-based)
• CSRF protection patterns
• Rate limiting with assertLimitAction()
• Cache control strategies
• Security helper usage (secureUserJson, securePublicJson)

When working with AI on security features:

"Read llms/SECURITY.md and add rate limiting to the support ticket creation action"

Security Templates

Working examples in llms/templates/:

• auth-api-route-template.ts - API routes with session validation + CSRF
• Protected page patterns with cache-disabling exports
• Convex action rate limiting examples

Effective AI Prompts

Clear and Specific

Reference Context

Point AI to security context for complex features:

"Read llms/SECURITY.md and implement CSP violation reporting with
proper error handling and rate limiting on the /api/csp-report endpoint"

Common AI Workflows

Adding Rate Limiting

1. "Read llms/SECURITY.md"
2. "Add rate limiting to the sendMessage action - 20 messages per minute"
3. "Test rate limiting by calling the action repeatedly"

AI will generate:

import { assertLimitAction } from "./rateLimits";

export const sendMessage = userAction({
  handler: async (ctx, { body }) => {
    await assertLimitAction(ctx, {
      scope: "messages:send",
      viewerId: ctx.viewerId,
      max: 20,
      windowMs: 60_000,
    });
    // Business logic
  },
});

Securing API Routes

"Read llms/SECURITY.md and add authentication + rate limiting to /api/export.
Use secureUserJson for responses and secureErrorJson for errors."

AI will generate proper auth checks and security helpers.

Updating CSP

"Add https://cdn.example.com to the CSP whitelist for image sources.
Update both buildStaticCsp and buildDynamicCsp in packages/app-shell/src/security/csp.ts"

Validation After AI Changes

# Should find secureUserJson/securePublicJson, not Response.json()
grep -r "Response.json" apps/dashboard/app/api/

// Call action repeatedly in tests
for (let i = 0; i < 15; i++) {
  await mutation(api.action, {});
}
// Should throw RATE_LIMITED error

# Load page in browser
# Open DevTools → Console
# Look for CSP violation warnings

pnpm test

Common AI Mistakes

Best Practices with AI

1. Always Reference Security Context

"Read llms/SECURITY.md and implement..."

This ensures AI understands security requirements.

2. Request Tests

"Add rate limiting with tests that verify RATE_LIMITED error is thrown"

3. Validate Generated Code

Check that AI code:

• Uses security helpers from @workspace/security
• Has proper cache-disabling exports on protected pages
• Includes rate limiting on expensive operations
• Uses userAction for operations needing rate limits
• Has proper error handling with AppError

4. Test Security Features

After AI generates code:

# Test rate limiting
# Test authentication
# Check CSP in browser console
# Verify headers with curl
pnpm test

Security Checklist for AI Code

When AI generates new endpoints or pages, verify:

• API routes use secureUserJson() or securePublicJson()
• Error responses use secureErrorJson()
• Protected pages have cache-disabling exports
• Expensive operations have rate limiting
• Authentication checks happen server-side
• CSRF protection on mutating endpoints (handled by middleware/Convex)
• No user data in public cached responses
• Proper Vary headers on auth-bearing requests

Templates for AI

Point AI to these patterns:

Related Documentation

• Security Headers - CSP, HSTS, cache controls
• CORS & CSRF - Cross-origin protection
• Rate Limiting - Endpoint throttling
• Overview - Security architecture