Security

The boilerplate implements comprehensive security measures following OWASP guidelines, including rate limiting, input sanitization, CSRF protection, and security headers.

File Structure

lib/security/
├── api-security.ts    # API route security wrapper
├── rate-limiter.ts    # Rate limiting (Upstash Redis / in-memory)
├── sanitize.ts        # Input sanitization utilities
├── csrf.ts            # CSRF protection
├── verify-admin.ts    # Shared admin verification utility
└── index.ts           # Re-exports

lib/env.ts             # Zod-based environment validation
next.config.ts         # Security headers configuration

API Security Wrapper

The withSecurity wrapper provides comprehensive protection for API routes with a single function call.

Rate limiting is preconfigured with different tiers: strict (5 requests per minute for sensitive operations), standard (30 per minute for general API calls), relaxed (100 per minute for public endpoints), and specialized limiters for AI and contact form endpoints. The system uses Upstash Redis in production and falls back to in-memory limiting in development.

Shorthand Helpers

Wrap your API route handlers with the appropriate security level from apiSecurity: use public() for unauthenticated endpoints with standard rate limiting, authenticated() for endpoints requiring a logged-in user, admin() for platform admin endpoints, ai() for AI endpoints with stricter limits, or webhook() for external webhook receivers.

Rate Limiting

Rate limiting uses Upstash Redis when configured, with automatic fallback to in-memory limiting for development or single-instance deployments.

Client IP identity is deliberately conservative. The rate limiter trusts Cloudflare's CF-Connecting-IP header only when TRUST_CLOUDFLARE_IP=true; enable that only when direct origin access is blocked or your proxy strips spoofed client headers. Otherwise the app ignores spoofable Cloudflare-looking headers and falls back to the last X-Forwarded-For entry, then X-Real-IP.

Input Sanitization

Always sanitize user input using the built-in sanitization utilities. The library provides methods for HTML content (strips tags and scripts), email validation, URL validation, slug generation (alphanumeric and hyphens only), and filename sanitization. These are located in lib/security/sanitize.ts.

DOMPurify HTML Sanitization

For rendering CMS content or user-generated HTML, the boilerplate uses isomorphic-dompurify with a strict allowlist of safe tags and attributes.

Form Validation

All form inputs are validated on the server side using Zod schemas before processing. Define a schema for each form's expected data, then use safeParse() to validate the request body. Invalid inputs return a 400 response with descriptive error messages. Client-side validation is also applied for immediate user feedback, but never relied upon as the sole validation layer.

CSRF Protection

CSRF protection uses the Double Submit Cookie pattern combined with Origin/Referer header validation.

CSRF is enforced automatically inside every apiSecurity.* / withSecurity() wrapper for POST/PUT/PATCH/DELETE — there is no separate wrapper to add. The standalone withCsrfProtection helper was removed (it was unwired). Client code uses csrfFetch() to attach the Double-Submit token header on client-initiated state changes; the server validates the token + Origin/Referer (against appConfig.url, never the request Host) before the route handler runs.

Security Headers

Security headers are configured in next.config.ts and applied to all routes.

Content Security Policy

The CSP is built per-request in lib/security/csp.ts using a cryptographically random nonce + 'strict-dynamic' in production. The static next.config.ts headers no longer carry the Content-Security-Policy entry — the middleware (proxy.ts) injects the dynamic policy. The policy allows resources from trusted domains (Supabase, Stripe, Google Analytics, Google Ads, GTM, Meta Pixel, your active email provider, Crisp, Cloudflare Turnstile, Twemoji flag SVGs from cdnjs) while blocking everything else. If you add a new third-party service, update the appropriate allowlist constant in lib/security/csp.ts rather than the legacy next.config.ts.

The CSP is assembled from six allowlist constants in lib/security/csp.ts — one per directive. The table below summarizes each allowlist; treat lib/security/csp.ts as the authoritative source and edit there when adding a new third party.

The middleware adds NEXT_PUBLIC_SUPABASE_URL to connect-src at runtime via the extraConnectOrigins argument so per-project URLs don't need to be hardcoded.

Bot Protection (Cloudflare Turnstile)

Cloudflare Turnstile protects forms from automated abuse. Set NEXT_PUBLIC_TURNSTILE_SITE_KEY and TURNSTILE_SECRET_KEY from your Cloudflare dashboard. The Turnstile component renders the invisible challenge widget on protected forms (contact, newsletter, login). Server-side validation in the API routes verifies the token with Cloudflare before processing the form submission. In development mode, Turnstile validation is bypassed automatically.

Environment Variable Validation

All environment variables are validated at runtime using Zod schemas in lib/env.ts. This ensures type safety and clear error messages when required variables are missing.

AI Credit Accounting

1 credit = 1 LLM token. The credit balance literally represents the number of LLM tokens the account can consume. Both chat (/api/ai/stream) and RAG (embeddings + similarity search) deduct the exact usage.total_tokens reported by the provider — no abstract per-chunk or per-search flat rates.

Credit operations must always use the atomic SQL RPC functions to prevent race conditions. Use decrement_credits to deduct credits (with a reason for the audit trail) and add_credits to add credits (with a source identifier). Never update the credits balance column directly.

Admin Verification Utility

A shared utility for verifying admin access in API routes, with auto-fix logic for the admin email setting.

Additional Security Hardening

The boilerplate includes several layers of defense-in-depth beyond the core security middleware: