Authentication

How the kit signs users up, in and out with self-managed Better Auth on Cloudflare Workers: the flows, the files, and where to change them.

The kit runs its own Better Auth instance inside the Void app. Users sign up with email and password, verify their email, sign in, sign out and reset a forgotten password. Sessions live in Postgres, emails go out through void/email, and auth requests are rate limited per IP.

What You Get

FlowPageNotes
Sign up/auth/sign-upAlways ends on "check your email", also for a taken address, so it never reveals who has an account
Verify emaillink in the email → /auth/verify-emailA good link signs the user in and continues to next; a bad or expired one offers a new link
Sign in/auth/sign-inOne error for a wrong email or password; an unverified user can resend the link
Magic link (AUTH_MAGIC_LINK=true)"Send Email Link" on /auth/sign-in and /auth/sign-upNo password: the emailed link signs in, creating a verified account for a new address. Same answer for every address
Email code (AUTH_EMAIL_OTP=true)"Email me a code" on /auth/sign-in and /auth/sign-upA 6-digit code instead of a link, for devices where opening a link is awkward. 3 tries per code, 10 codes per address per 24 hours; a new address gets a verified account
OAuth (AUTH_GOOGLE_CLIENT_ID + _SECRET)"Continue with Google" on /auth/sign-in and /auth/sign-upOne click; a new email gets an account. Links to an existing account only when both emails are verified. Other providers take one config entry. See OAuth Sign-In
Two-factor (AUTH_TWO_FACTOR=true)set up at /settings/security; asked on /auth/two-factorA code from an authenticator app (or a backup code) after any sign-in method. See Two-Factor Authentication
Passkeys (AUTH_PASSKEY=true)added at /settings/security; "Sign in with a passkey" on /auth/sign-inFingerprint, face or device PIN; can't be phished, and skips the 2FA code. See Passkeys
Bot protection (TURNSTILE_SITE_KEY + _SECRET_KEY)a Turnstile check on sign-in, sign-up, reset and verify-emailGuards password sign-in and sign-up, the reset request and every email sent; usually invisible. See Bot Protection
Sign outthe account menu on every app pageA POST; cross-site requests are rejected
Reset password/auth/password-reset → link → /password-resetEnds every session of the account

All auth endpoints are Better Auth's own, under /api/auth/*. The forms call them from the browser through authClient, so Better Auth's origin check and rate limits apply to every request.

Auth dates use timestamptz, so session and verification expiry represent the same instant in every database session timezone. Schema regeneration preserves this setting.

The database enforces one account per provider identity, one membership per organization and user, one passkey per credential id, and one two-factor record per user. Concurrent invitation acceptance keeps one membership; retrying incomplete factor setup updates the existing record.

Who Can Open a Page

The folder a page lives in decides it. There's no list of protected paths to keep in sync.

FolderWhoExample
apps/web/pages/(app)/Signed-in users onlypages/(app)/dashboard/index.tsx is /dashboard
apps/web/pages/auth/Signed-out visitors only/auth/sign-in, /auth/sign-up
everywhere elseEveryone/, /password-reset

Signed-out visitors of a signed-in page go to /auth/sign-in?next=<page> and come back after signing in. Signed-in users who open an /auth page go to next or the app home (APP_HOME_PATH, default /dashboard). See Sessions and Guards.

Where Things Live

WhatFile
Better Auth options (hooks, rate limits, emails)packages/better-auth/src/options.ts
The app's auth instanceapps/web/config/auth.server.ts
Session helpers (getSession, requireSession, getNextPath)apps/web/lib/session.server.ts
Rate-limit overrides (rateLimitRules); password rules come from PASSWORD_REQUIRE_*apps/web/config/auth.config.server.ts
Auth page pathsapps/web/config/auth-paths.ts
Emailsapps/web/config/auth-mailer.server.ts (binds createQueuedAuthMailer from @kit/better-auth/mailer), strings in packages/i18n/src/messages/<locale>/auth.json
Session middleware and guardsapps/web/middleware/06.session.ts
Formspackages/auth/src/*.tsx
Pagesapps/web/pages/auth/, apps/web/pages/password-reset/
Generated auth tablesapps/web/db/auth-schema.ts (never edit by hand; written by auth:generate, see Adding Plugins)

Pages in This Section