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
| Flow | Page | Notes |
|---|---|---|
| Sign up | /auth/sign-up | Always ends on "check your email", also for a taken address, so it never reveals who has an account |
| Verify email | link in the email → /auth/verify-email | A good link signs the user in and continues to next; a bad or expired one offers a new link |
| Sign in | /auth/sign-in | One 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-up | No 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-up | A 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-up | One 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-factor | A 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-in | Fingerprint, 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-email | Guards password sign-in and sign-up, the reset request and every email sent; usually invisible. See Bot Protection |
| Sign out | the account menu on every app page | A POST; cross-site requests are rejected |
| Reset password | /auth/password-reset → link → /password-reset | Ends 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.
Signing in by link or code proves the address. On an account that never verified it, Better Auth then removes any password and sessions set before (someone could have registered the address in advance), so that user signs in by link or code, or resets the password.
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.
| Folder | Who | Example |
|---|---|---|
apps/web/pages/(app)/ | Signed-in users only | pages/(app)/dashboard/index.tsx is /dashboard |
apps/web/pages/auth/ | Signed-out visitors only | /auth/sign-in, /auth/sign-up |
| everywhere else | Everyone | /, /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
| What | File |
|---|---|
| Better Auth options (hooks, rate limits, emails) | packages/better-auth/src/options.ts |
| The app's auth instance | apps/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 paths | apps/web/config/auth-paths.ts |
| Emails | apps/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 guards | apps/web/middleware/06.session.ts |
| Forms | packages/auth/src/*.tsx |
| Pages | apps/web/pages/auth/, apps/web/pages/password-reset/ |
| Generated auth tables | apps/web/db/auth-schema.ts (never edit by hand; written by auth:generate, see Adding Plugins) |
Pages in This Section
- Setup: secret, site URL, email sender, local database and seed users
- Sessions and Guards: reading the user in loaders, actions, handlers and components
- Emails: what's sent, translations, failures
- Step-Up Codes: emailed codes that confirm a destructive action
- Rate Limits: the limits and how to change them
- Adding Better Auth Plugins: plugins and regenerating the schema
- Testing: seed users and the e2e helpers
- Troubleshooting
Never import void/auth, use auth from void/client, or add an auth.ts file at the app root. Void would switch on its own auth next to the kit's.