Security Baseline

Default protections for startup env validation, security headers, error boundaries, and API error handling.

MuseMVP ships with a set of security defaults out of the box: environment validation at server startup, security response headers on every route, layered error boundaries, unified API error handling, plus hardening for billing webhooks and email flows. All of these are enabled by default with no extra configuration.

Design Principle

Misconfiguration in production should fail fast at startup instead of surfacing later as a confusing runtime error mid-request; non-fatal issues degrade to warning logs and never block a deployment.

Startup Environment Validation

Server-side environment variables are validated by a composed Zod schema in each app’s src/env/schema.ts and src/env/readiness.ts, invoked once at server startup via register() in src/instrumentation.ts.

Hard error: a production runtime missing BETTER_AUTH_SECRET throws immediately and aborts startup. The build phase does not throw for these hard errors; SKIP_ENV_VALIDATION=true bypasses validation and must not hide missing production config.
Non-fatal warnings: the following misconfigurations only emit warning logs and never block startup.

Scenario	Warning Condition	Impact
Worker bindings	Missing `DB` or `R2_BUCKET`	Database or storage requests fail
Email service	Missing Cloudflare account/token credentials	Transactional email fails

Security Response Headers

The headers() function in next.config.ts sends the following security headers on every route (/:path*):

Header	Value	Purpose
`Strict-Transport-Security`	`max-age=63072000; includeSubDomains; preload`	Enforce HTTPS
`X-Frame-Options`	`SAMEORIGIN`	Block cross-site iframe embedding (clickjacking)
`X-Content-Type-Options`	`nosniff`	Disable MIME type sniffing
`Referrer-Policy`	`strict-origin-when-cross-origin`	Limit referrer leakage
`Permissions-Policy`	`camera=(), microphone=(), geolocation=(), browsing-topics=()`	Disable sensitive browser capabilities by default

About CSP

A Content-Security-Policy is intentionally not included yet: Next.js inline scripts require per-request nonces, and third-party scripts (analytics, Turnstile, Google One Tap) need explicit allow-listing. It is planned as a dedicated follow-up.

Error Boundaries

The App Router uses layered error boundaries so an uncaught exception never results in a blank screen:

Global Fallback

src/app/global-error.tsx — Last line of defense; replaces the root layout, renders its own html/body with inline styles and non-localized copy.

Landing Page Boundary

src/app/(landing-page)/[locale]/error.tsx — Catches exceptions within the marketing segment and renders the shared fallback.

App Boundary

src/app/(saas-page)/app/error.tsx — Catches exceptions within the SaaS app segment and renders the shared fallback.

Both segment boundaries share the ErrorState fallback component, offering Try again and Back to home actions, with copy maintained in the i18n errors namespace (en/zh).

API Error Handling

The Hono API (src/backend/api/app.ts) handles errors and request body size at the entry layer:

Unified error shape: app.onError catches every exception that escapes a handler, logs it, and returns a unified JSON error structure ({ ok: false, error: "Internal Server Error" }) without leaking internal details to clients.

HTTPException passthrough: an HTTPException thrown deliberately by a route keeps its own response and is never overwritten.

Request body limit: hono/body-limit caps request bodies at 1MB, returning 413 when exceeded. Avatar uploads use the separate session-protected /files/avatars/* route with a 5 MiB payload limit.

Billing and Email Hardening

Enforced webhook signature verification: in production, Creem, Stripe, and Dodo webhooks require their webhook secrets from env and throw when the secret is missing. Waffo verifies x-waffo-signature with the SDK webhook verifier, not the merchant API-signing private key.
Env-only credentials: payment and storage secrets are environment variables. Export legacy credentials securely before upgrading; the current version has no admin-settings export command. See Environment Variables.
Newsletter unsubscribe tokens: unsubscribe links are signed with HMAC-SHA256 using NEWSLETTER_TOKEN_SECRET. There is no fallback to BETTER_AUTH_SECRET.
Auth emails report real failures: when an OTP, magic link, or password-reset email fails to send, the client receives a real error instead of a silent success that leaves the user waiting for an email that never arrives.

Permission Architecture

Better Auth entrypoints, session behavior, and role-based middleware boundaries

Middleware Design

Next.js middleware and route guards

Workers production rejects Resend and console mail. Missing credentials may warn at startup; D1/R2 binding failures appear when called. Verify real flows in Worker preview.