Security

On This Page

Defense In DepthFive layers, what each blocks, and which need env vars.Edge: Headers, CSP, CORSNosecone headers, CSP allow-list, and CORS on API routes.Authentication: Sessions And CaptchaCookie sessions, CSRF posture, and optional Turnstile.Built-in Auth Rate LimitsPer-route Better Auth ceilings that work without Upstash.API: The Middleware ChainAuth, org, permission, and admin gates on oRPC procedures.Abuse Protection (Upstash)Per-surface limits. Required in production. Fails closed.Billing Caps: Atomic Reservation, Not Check-Then-ActAI usage reserved under a per-org advisory lock.Webhooks: Signature VerificationStripe signature check, event dedupe, and OutboundEffect keys.Uploads: The Validation Boundarysharp re-encode, MIME and size limits, temp key cleanup.Operational SecretsSession, server-action, and webhook secrets plus proxy headers.Pre-Launch Security ChecklistSecrets and flags to set before real traffic.

Defense In Depth

Edge: Headers, CSP, CORS

The proxy at apps/web/proxy.ts runs before every route handler. It applies a Nosecone header bundle (CSP, HSTS, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Cross-Origin-Opener-Policy, Permissions-Policy) and adds CORS to API routes. The CSP allow-list extends Nosecone's defaults with only the origins the kit talks to:

CORS is scoped to NEXT_PUBLIC_APP_URL and applies only to /api/*, /rpc/*, and /trpc/*. Other paths get no Access-Control-Allow-Origin. Credentials are allowed so authenticated cross-origin clients can reach the API.

Authentication: Sessions And Captcha

Better Auth issues opaque session cookies signed and encrypted by BETTER_AUTH_SECRET. httpOnly + sameSite=lax, plus a session check at every request boundary, mitigate CSRF without a separate token. Captcha is opt-in: Cloudflare Turnstile attaches only when both TURNSTILE_SECRET_KEY and NEXT_PUBLIC_TURNSTILE_SITE_KEY are set.

See Authentication for the full session model, OAuth wiring, 2FA, and passkeys.

Built-in Auth Rate Limits

Better Auth's own rate limiter applies route-specific rules on top of a default ceiling in packages/auth/src/server.ts. These limits work without Upstash (in-memory). When Upstash is configured, the same rules use Redis customStorage so they hold across instances and cold starts. They apply per IP at the auth layer and sit next to the per-surface Upstash policy below (which keys on email, userId, or organizationId).

API: The Middleware Chain

Every oRPC procedure picks a base from the middleware chain in packages/api/src/middleware/. Five gates cover the common patterns:

Every procedure also chains .input(zodSchema) and .output(zodSchema). Inputs are validated before the handler runs, so malformed or oversized payloads never reach domain code. See API for the chain in context.

Abuse Protection (Upstash)

packages/shared/src/abuse.ts implements per-surface sliding-window rate limits on Upstash Redis. Each policy has one or two rules keyed by ip, email, userId, or organizationId, in a pre_verification or post_verification phase. Callers route the result through resolveAbuseDecision, which returns allow, rate_limited, or unavailable.

Posture: Required In Production, Fail Closed Everywhere

One posture covers every surface so a misconfigured surface cannot silently disable the others.

Billing Caps: Atomic Reservation, Not Check-Then-Act

Upstash windows smooth bursts. They do not enforce per-plan billing caps (monthlyAiResponses). For those, reserveAiUsageEvent in packages/core/src/usage/quota.ts counts the active billing window and inserts an AiUsageEvent inside one prisma.$transaction, opened with pg_advisory_xact_lock(hashtextextended('ai-usage:<organizationId>', 0)). Concurrent reservations for the same org serialize, so the count + insert pair is race-free.

Chat send and regenerate call this before the stream starts. Soft UI banners should read billing entitlements and usage, not replace the reservation for enforcement.

Webhooks: Signature Verification

The Stripe route at apps/web/app/api/webhooks/stripe/route.ts rejects a missing stripe-signature with 400, then delegates to processWebhookEvent in packages/payments/src/stripe/webhook.ts. That helper verifies the payload with stripe.webhooks.constructEvent against STRIPE_WEBHOOK_SECRET. A bad signature becomes StripeWebhookSignatureError and maps back to 400 before any handler runs:

const signature = req.headers.get("stripe-signature");

if (!signature) {
  log.warn("Stripe webhook missing signature header", {
    attributes: { endpoint: "/api/webhooks/stripe" },
  });
  return new Response("Missing stripe-signature header", { status: 400 });
}

After verification, the handler claims a StripeWebhookEvent row (event-level dedupe) and dedupes side effects with OutboundEffect semantic keys. A delivered-twice Stripe webhook does not double-charge, double-email, or double-grant entitlements. See Webhooks And Async Workflows for the full idempotency story.

Uploads: The Validation Boundary

Client-side checks reject the wrong size or MIME before the presign request. They are courtesy. The real boundary is the server-side sharp re-encode during finalize: a file that decodes cleanly is an image; anything else throws and the temp object is removed.

Final outputs are always re-encoded. Original bytes never become the served file. Temp keys live under tmp/ and are deleted on every server-observable failure path. A bucket lifecycle rule that expires tmp/ after 1 day covers abandoned uploads between presign and finalize. See Storage for the full pipeline.

Operational Secrets

Three secrets every production deploy must set, plus one header pair for proxied deployments.

For deployments behind a load balancer or reverse proxy, set TRUST_PROXY_HEADERS=true and TRUSTED_PROXY_IP_HEADERS=x-forwarded-for so Better Auth sees the real client IP for rate limits and audit. Render's blueprint sets these by default. Fly's edge-only setup does not need them.

Pre-Launch Security Checklist

pnpm setup:doctor

Where To Go Next

Also useful: API for the oRPC middleware chain, Webhooks And Async Workflows for Stripe idempotency, and Deployment for where secrets and proxy headers are set per host.