Next.js boilerplate with Better Auth

One config, server-only importers

src/lib/auth/auth.ts constructs the only betterAuth() instance in this repo. Only server code imports it:

• src/app/api/auth/[...all]/route.ts: the handler
• src/lib/auth/session.ts: the server-side session helpers
• src/lib/auth/actions.ts: the server actions behind Settings (profile, password, connected accounts, sessions)
• src/components/auth/account-settings.tsx: server components that read the account's sign-in methods and sessions
• scripts/auth/*: terminal scripts, run through tsServer

Anything else imports session.ts (server), actions.ts (a server action called from a client component) or client.ts (browser). Importing auth.ts from a client component drags the ORM, the mailer and BETTER_AUTH_SECRET into the browser bundle.

Never construct a second betterAuth(): not for a script, not for a test, not for "just this one job". Two instances mean two configurations, and the one that signed a cookie is not necessarily the one that verifies it.

The endpoint guard runs before every endpoint

auth.ts registers endpointGuard, a plugin whose hooks.before runs for every Better Auth endpoint, over HTTP and through auth.api.*. The rules live in src/lib/auth/endpoint-guard.ts (pure, tested in endpoint-guard.test.ts against the full endpoint list of the installed version):

• An impersonation session is read-only at the API. It may call IMPERSONATION_ALLOWED_PATHS (get-session, list-accounts, sign-out, stop-impersonating) and nothing else: 403 IMPERSONATION_READ_ONLY. It is an allowlist, so an endpoint a new plugin or an upgrade adds is refused until you add it on purpose. Never add /list-sessions (it returns every session's token) or anything that returns provider tokens.
• Adding a way in needs a recent sign-in. setPassword, /link-social and /change-email need a session created within RECENT_SIGN_IN_MINUTES (src/lib/auth/policy.ts): 403 RECENT_SIGN_IN_REQUIRED. The UI answers it with ReauthenticateAlert ("Confirm it's you": sign out, sign in with ?next=/settings/security, come back).

Rules for changing it:

• Keep endpointGuard after every other plugin and before nextCookies(). A plugin that signs a request in from a header does it in its own hook, and the guard must see the result.
• Match on the declared route (ctx.path), never on the request URL. A server-only endpoint has no route: match it by operationId in RECENT_SIGN_IN_OPERATIONS, and keep the matching check in its server action.
• A new endpoint that adds a sign-in method, a credential or an address goes in RECENT_SIGN_IN_PATHS. A new endpoint an impersonating admin genuinely needs goes in IMPERSONATION_ALLOWED_PATHS only if it cannot change the account and returns no token. Update the endpoint list in the test either way.

See docs/solutions/better-auth/guarding-the-auth-api-itself.md.

Never roll your own crypto

Better Auth already signs the session cookie, hashes passwords (scrypt), single-uses magic-link and reset tokens, and constant-time compares them. In this repo that means:

• No crypto.createHash("sha256") over a user id to make "a quick token".
• No Math.random(), Date.now() or nanoid() used as a credential. A token someone can predict is a token someone can mint.
• No hand-written JWT signing or verification, and no second cookie that carries identity beside the session cookie.
• No === on secrets. Comparison of a submitted token against a stored one happens inside Better Auth, in constant time, or it does not happen.

If a flow seems to need a new kind of token (an invite link, an email change confirmation, an API key), the answer is a Better Auth plugin or a row with an expiry, a single-use flag and a crypto.randomUUID() value that is hashed before storage. Never a homemade signature scheme.

Runtime and caching

• The catch-all handler runs on the Node runtime. The adapter opens a TCP connection to Postgres; the edge runtime cannot. export const runtime = "nodejs" in that route is load-bearing.
• Any route or page that reads the session must be dynamic. A cached response built for one visitor is served to the next one, and the session is the one thing that must never be shared.
• The corollary: never read the session in src/app/layout.tsx. One getSessionUser() there makes every route in the repo dynamic, marketing pages and blog posts included. The session provider subscribes in the browser for exactly this reason. A segment that is already per-visitor may read it in its own layout.
• Never read document.cookie looking for the session. It is HttpOnly, so a successful read means the cookie is misconfigured.

Rate limiting

auth.ts enables Better Auth's limiter with storage: "database", in every environment. Three things follow, and each of them has been the cause of a real outage somewhere:

• Do not switch it back to memory. This app runs on serverless functions. An in-process counter is one counter per warm instance, so the effective limit is the configured one times the fleet size, which for /sign-in/magic-link and /request-password-reset means an unbounded relay for mailing strangers from your verified domain, and for /sign-in/email a password-guessing budget multiplied by every warm instance.
• Do not delete the rate_limit table or drop it from the schema. With database storage configured and no table, every request to /api/auth/* fails on a missing relation.
• Do not remove rateLimit.customStorage. It counts each request in one atomic statement (consumeRateLimitRow in src/lib/auth/adapter.ts). Better Auth's own database storage lets a burst of simultaneous sign-ins past the limit on Postgres. The server actions that check a password or send an email (src/lib/auth/actions.ts) count through the same function, per account, because Better Auth's limiter never sees a server action.
• Do not remove advanced.ipAddress.ipAddressHeaders. Without a resolvable client IP the limiter falls back to a single shared bucket for the whole internet, and the first few sign-ins each minute lock out everybody else. Behind a proxy of your own, add trustedProxies rather than widening the limits.

Enforce limits on the server. Disabling a button after a click is feedback, not a control.

Secrets and origins

• BETTER_AUTH_SECRET is read only inside auth.ts (and setup.ts, which only asks whether it is set). It is never logged, never passed to a client component, never included in an error message.
• A missing secret, BETTER_AUTH_URL or DATABASE_URL turns sign-in off (setup.ts): the auth pages say what to set, /api/auth answers 503, getSession() answers null. Keep new auth entry points behind the same check instead of letting them 500.
• Each environment gets its own secret. A preview deployment sharing production's secret means a cookie minted on a preview URL is valid in production.
• BETTER_AUTH_URL seeds trustedOrigins, which is the CSRF check. Do not loosen it to "*", and do not add an origin you do not control. VERCEL_URL is the one exception and it is added conditionally: the platform sets it, it names the current preview deployment, and it is absent everywhere else.
• Rotating the secret invalidates every session. That is a deliberate, announced act. See the session-invalidation solution doc.

Errors that reach the user

Every message comes from src/lib/auth/errors.ts, keyed by Better Auth's error code, so the forms, the pages and the server actions say the same thing.

• A failed password sign-in is "Email or password is incorrect.", never "no such account". A failed emailed link is "invalid or already used, ask for a new one".
• "Forgot password" and "email me a link" show the same "check your inbox" panel whether or not the address exists, and Better Auth sends the email after the response (advanced.backgroundTasks), so the timing matches too.
• Sign-up is the one place that says "already has an account", and only while REQUIRE_EMAIL_VERIFICATION is off: with it on, Better Auth answers a taken address like a new one. The trade-off is written next to the flag in src/lib/auth/policy.ts.

Those properties are easy to break by "improving" the error handling. Keep errors next to the field or in an Alert at the top of the form, and never only in a toast.

Sign-in methods: where each one is switched

Method	Switch	Notes
Email and password	PASSWORD_SIGN_IN in src/lib/auth/policy.ts	Off hides the password field, sign-up form, "Forgot password?" and the password card, and Better Auth refuses the endpoints
Magic link	MAGIC_LINK_SIGN_IN in policy.ts	Off removes the option and lists its two endpoints in disabledPaths
Email verification required	REQUIRE_EMAIL_VERIFICATION in policy.ts	Off by default; the trade-off is in the comment above it
Google, GitHub, Microsoft	both of the provider's env keys set	src/lib/auth/providers.ts is the only file that reads them

Change a method there and nowhere else. The pages, the forms, the settings cards and auth.ts all read these, so a button can never point at a method the server refuses.

Sign-in UI rules

• A button only for a configured provider. Pages call enabledOAuthProviders() on the server and pass { id, label } to the client. Never hardcode a "Continue with Google" button, and never pass keys, secrets or process.env reads to a client component.
• Google first, then GitHub, then Microsoft. The order is the order of OAUTH_PROVIDERS. A new provider goes into that array (see the add-oauth-provider skill), not into a page.
• TRUSTED_LINKING_PROVIDERS stays short. It lets a provider join an existing account with the same email even when the provider does not vouch for the address. Only Google is in it. Adding a provider that lets users or tenant admins set unverified addresses (GitHub, Microsoft Entra) is an account-takeover bug.
• Every redirect target goes through safeNext() before it reaches callbackURL, redirect() or a link. It judges the normalised path as well as the raw string: /..//evil.example folds to //evil.example. Emailed links and OAuth failures land on the sign-in page via authErrorURL(next), which turns ?error= into a sentence from errors.ts.
• Changes to an existing account are server actions in src/lib/auth/actions.ts: validated with zod, first line checks the session, and every change is refused while an admin impersonates the account (the endpoint guard refuses the raw endpoints too). Only calls that must redirect the browser (OAuth sign-in and linking) or answer before the page moves (sign-in, sign-up, reset) use authClient.
• Session tokens never reach the browser. The sessions list maps Better Auth's rows to ids on the server; revoking looks the token up again inside the action.
• setPassword is server-only in Better Auth. An account that signed up with OAuth or a magic link gets "Set a password" through setPasswordAction; an account with a password gets "Change password". Setting one needs a recent sign-in, checked in the action and in the guard.
• Build with the kit. Forms use Field, FieldLabel, FieldControl, Input (or PasswordInput), FieldError and an Alert for the form-level error. On a failed submit, focusFirstError() from @/components/auth/focus-first-error moves focus to the first invalid field so a screen reader reads its error. Accessible names are part of the contract: the end-to-end tests find "Email", "Password", "Sign in", "Create account" and "Continue with Google" by role and label.

Adding an auth email

Emails for auth go through sendAuthEmail in auth.ts, which imports @/lib/email and the template lazily (the Better Auth CLI loads auth.ts outside Next, where a static import of a server-only module throws). Add the template next to magic-link.tsx, reset-password.tsx and verify-email.tsx in src/lib/email/templates/, and give the plain-text part the raw URL.

The rule

Every server action, route handler and protected page re-reads the role from the session on the server and re-checks it. Not once at the edge, not once at login, not once in a layout that a later refactor might move: on every request that does something privileged.

// server action
"use server";
import { requireRole } from "@/lib/auth/session";

export async function deleteAccount(userId: string) {
  await requireRole("admin");   // first line, before any argument is trusted
  // ...
}

Never trust a role that arrived from the client

These are all the same bug:

// no
export async function promote(formData: FormData) {
  if (formData.get("role") === "admin") { /* ... */ }
}

// no
export async function POST(request: Request) {
  const { userId, isAdmin } = await request.json();
  if (isAdmin) { /* ... */ }
}

// no
const role = request.headers.get("x-user-role");

A form field, a JSON body, a header, a query parameter and a localStorage value are all attacker-controlled. The only trustworthy answer to "who is this and what are they" comes from getSessionUser(), which reads the signed cookie server-side.

The same applies to identity, not just role: never accept a userId from the client and act on it. Take the id from the session and use the client's value only to name the target of an action, after checking the actor may act on it.

Client-side role checks are cosmetics

useSessionUser() and useCanSee() from @/components/auth/session-provider exist so an admin link is not rendered for a regular user. That is a courtesy. The endpoint behind the link is what an attacker calls, so it does its own requireRole.

They also start out null on every page load (the session is fetched in the browser after hydration) and stay null for a suspended account. Neither is a security property; both are reasons to render a neutral state rather than branching on !user as if it meant "signed out".

A checklist for any new privileged feature:

1. The page or action calls requireUser / requireRole before anything else.
2. Hiding the entry point in the UI is a second, independent step.
3. If (1) is missing, the feature is broken even though it looks correct in the browser.

Where a role may be written

• Roles change through the Better Auth admin plugin (auth.api.setRole, which the admin panel calls), bun run auth:make-admin <email> for the first admin, or a deliberate SQL statement run by a human. Never through a route that takes the new role from the request body without a requireRole("admin") above it.
• A user may never set their own role, including at sign-up. The role column has a NOT NULL DEFAULT 'user'; nothing in the sign-up path overrides it.
• The role vocabulary lives in src/lib/auth/roles.ts. Add a role there and nowhere else. A string literal "editor" compared inline is a role that exists in one file and is silently absent from every other check. Add it to RANK in the same edit; hasRole fails closed on a role it cannot rank, so a half-added role silently denies everything instead of erroring. src/lib/auth/guards.test.ts reads ROLES rather than a hardcoded list, so it keeps covering the new one.

The cookie cache

Sessions carry a short signed cache of the user row, so most requests answer without a database read. A role written directly into the table is therefore not visible for up to five minutes. Promotions and demotions that must take effect immediately go through the admin plugin API, which refreshes the cache, or are followed by revoking that user's sessions.