Security

SyntaxKit ships defense in depth: every request crosses five layers before it touches a database row: edge headers and CORS, Better Auth, the oRPC middleware chain, the Upstash abuse policy, then a Zod-validated handler. Most layers are auto-on; only Upstash (UPSTASH_REDIS_REST_URL, UPSTASH_REDIS_REST_TOKEN) and Cloudflare Turnstile (TURNSTILE_SECRET_KEY, NEXT_PUBLIC_TURNSTILE_SITE_KEY) need explicit config before they activate. The Pre-Launch Checklist lists every secret to set first.

Defense in depth

The five layers every request crosses, and which gate on env vars.

Auth & captcha

Session cookie hardening, CSRF posture, and Turnstile wiring.

Abuse protection

Per-surface rate limits, required in production, fail closed.

Pre-launch checklist

Every secret and flag to set before opening to real traffic.

Defense In Depth

The diagram source lives at apps/docs/diagrams/security-layers.mmd. Rerun pnpm --filter @syntaxkit/docs diagrams:build after editing it to refresh both SVG variants.

Edge: Headers, CSP, CORS

The proxy at apps/web/proxy.ts runs before every route handler. It applies a Nosecone-driven security 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 strict defaults with only the origins the kit actually talks to:

CORS is scoped to NEXT_PUBLIC_APP_URL and applied only to /api/*, /rpc/*, /trpc/*; other paths get no Access-Control-Allow-Origin. Credentials are allowed (Access-Control-Allow-Credentials: true) so authenticated cross-origin clients can still 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 only attaches 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, configured in packages/auth/src/server.ts. These are built-in (no Upstash needed) and apply per IP at the auth layer, complementing the per-surface Upstash policy below (which applies per email/userId/orgId at the application layer).

API: The Middleware Chain

Every oRPC procedure picks a base from the middleware chain in packages/api/src/middleware/. Five layers cover every common gating pattern:

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 the API page for the chain in context.

Abuse Protection (Upstash)

packages/shared/src/abuse.ts implements per-surface sliding-window rate limits backed by Upstash Redis. Each policy has 1-2 rules indexed by a characteristic (ip, email, userId, or organizationId) and runs in a pre_verification or post_verification phase. Every caller routes its AbuseDecision through resolveAbuseDecision, which converts the result into one of three outcomes: allow, rate_limited, or unavailable.

Posture: Required In Production, Fail Closed Everywhere

The policy converged on a single posture so misconfiguring one surface can never silently disable the others.

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

The Upstash windows above smooth bursts but don't enforce per-plan billing caps (monthlyAiResponses). For those, reserveAiUsageEvent in packages/api/src/lib/billing.ts counts the active billing window and inserts a new AiUsageEvent row inside one prisma.$transaction, opened with pg_advisory_xact_lock(hashtextextended('ai-usage:<organizationId>', 0)) so concurrent reservations for the same org serialise and the count + insert pair is race-free.

assertWithinAiResponseLimit and getAiUsage stay exported for read-only soft checks; the chat router never relies on them for enforcement.

Webhooks: Signature Verification

The Stripe webhook handler at apps/web/app/api/webhooks/stripe/route.ts verifies every event with stripe.webhooks.constructEvent against STRIPE_WEBHOOK_SECRET. Missing or invalid signatures return a 400 before any handler runs:

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

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

The handler then writes a StripeWebhookEvent row with status: "processing" (event-level dedupe) before delegating to per-event logic, which dedupes side effects via the OutboundEffect semantic key. Together the two layers mean 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 is sent, but they are courtesy. The real security boundary is the server-side sharp re-encode during finalize: a file that decodes cleanly is unambiguously an image; anything else throws and the temp object is removed.

Final outputs are always re-encoded; the original bytes never become the served file. Temp keys live under tmp/ and are deleted in every server-observable failure path. A bucket lifecycle rule that expires tmp/ after 1 day catches the residual case where a user abandons the upload between presign and finalize. See Storage for the full upload 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-limit and audit purposes. Render's blueprint sets these by default; Fly's edge-only setup doesn't need them.

Pre-Launch Security Checklist

pnpm setup:doctor

Where To Go Next