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 — which is mandatory there, see below — and 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. Keys are isolated by HTTP method and canonical route; dynamic handlers must declare a stable rateLimitScope such as /api/admin/jobs/[jobId] so concrete IDs cannot create unbounded buckets.

Every route.ts needs a wrapper — not just the ones under app/api/. A Next.js route handler is defined by its filename, so page-adjacent handlers such as app/[locale]/(auth)/callback/route.ts and the referral/affiliate tracking redirects are HTTP entry points exactly like an API route. pnpm run audit:api-patterns scans all of app/ and fails the build on any unwrapped handler; the separate 250-LoC ceiling stays scoped to app/api/**, which is where that thinness convention applies.

Rate Limiting

Rate limiting uses Upstash Redis, with in-memory limiting in development. Upstash is required in production and the app refuses to boot without it — the in-memory store is per-instance, so behind a load balancer a caller is spread across every replica's separate counter. That does not loosen the limits, it removes them, and it looks identical to a working configuration from outside. On a deliberately single-instance deployment, where per-instance counting is correct, set ALLOW_INMEMORY_RATE_LIMIT=true to say so explicitly.

Public endpoints are limited before the request body is read. The body-size guard streams up to maxBodySize (10 MB on /api/documents) to enforce the limit on the real payload rather than trusting Content-Length, so running it first would let a throttled caller still make the server ingest the whole body and only pay the 429 afterwards. Authenticated endpoints are limited after getUser() instead — that ordering is what stops IP rotation from multiplying one user's quota. The two orderings are deliberate and should not be unified.

Endpoints that send mail carry a per-recipient budget on top of the IP tier. An IP limit bounds nothing when the target of the abuse is somebody else's inbox, so /api/auth/magic-link and /api/auth/verify-otp each additionally limit on the normalised email address. This matters twice over for the magic link: Supabase's generateLink creates the auth.users row for an address that has never signed up, so an unbudgeted send endpoint is also a mass account-registration endpoint.

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.

Dependency & Supply-Chain Security

This repository accepts pnpm 11.20.0 only. npm, npx, pnpx, pnpm dlx, Bun, Yarn, and their lockfiles are forbidden. Add a reviewed CLI as an exact devDependency and invoke it with pnpm exec; never fetch and execute a package ephemerally.

Before every release, run pnpm install --frozen-lockfile, pnpm run audit:signatures, and pnpm run audit:security. The moderate-or-higher vulnerability baseline is zero.

The workspace also applies a 7-day release quarantine, strict publication-time lookup, registry trust checks that reject integrity downgrades, fresh registry integrity verification instead of trusting the lockfile alone, and a block on exotic transitive dependency sources. Exceptions are exact reviewed package versions: either their integrity matched the previous lockfile, or they are urgent signed security fixes. Do not broaden them.

Never use a forced or automatic audit-fix command. Upgrade the direct dependency first; if no acceptable upgrade exists, add the narrowest possible override in pnpm-workspace.yaml, inspect the resulting pnpm-lock.yaml diff, then rerun signature, vulnerability, and behavior tests.

isomorphic-dompurify is held at 2.x on purpose: although Node 24.18.1 satisfies the v3 engine requirement (^22.22.2 || ^24.15.0 || >=26), a sanitizer major upgrade requires a separate review and targeted rendering tests. The 2.x line still resolves the fully patched dompurify in range. The repository pins Node 24.18.1 LTS in version files, package engines, CI, and Docker.

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 production CSP has two deliberate modes. Dynamic and private routes receive a cryptographically random nonce plus 'strict-dynamic'. Statically generated public routes receive a deterministic policy so ISR and CDN caching remain possible; Next.js currently emits inline RSC bootstrap scripts on those pages, so that mode includes 'unsafe-inline' even when external build assets carry SRI. React escaping and the DOMPurify boundary in components/html-renderer.tsx are therefore mandatory defenses for CMS content, and unsanitized dangerouslySetInnerHTML must never be introduced on a static route. The middleware (proxy.ts) selects the mode and injects the policy.

The policy allows resources from trusted domains (Supabase, Stripe, Google Analytics, Google Ads, GTM, Meta Pixel, your active email provider, Crisp, Cloudflare Turnstile, and Twemoji flag SVGs from cdnjs — the last of these in img-src only) 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: