Authentication Overview

The Leave Localhost Starter utilizes Better Auth as the core authentication framework, seamlessly integrated with our Convex backend. Better Auth provides a comprehensive, secure, and extensible authentication system out of the box.

Core Architecture

• Better Auth Framework: Handles session management, identity verification, rate limiting, and core security features.
• Convex Integration: The user data, sessions, and authentication state are stored directly in your Convex database via @convex-dev/better-auth/plugins.
• User Synchronization: Database triggers (onCreate, onDelete) ensure that the authentication identities map directly to the users table in Convex for seamless relational queries.
• Environment Variables: Managed through the central env.ts configuration to securely store secrets like provider keys and base URLs.

Features Enabled

• Multiple Providers: Support for Email & Password, Magic Links, Google OAuth, and Microsoft OAuth.
• Multi-Factor Authentication (MFA): Built-in support for Time-Based One-Time Passwords (TOTP).
• Organizations & Roles: Robust multi-tenant support with roles (owner, admin, member, viewer) and secure invitation systems.
• Rate Limiting: Native database-backed rate limiting to prevent brute force attacks.

Customizing Auth

You can modify the authentication configuration directly in packages/backend/convex/auth.ts.

Upgrading Better Auth

Better Auth integration code is isolated in packages/backend/convex/auth/: component-table reads in betterAuthComponentReads.ts, endpoint response normalization in betterAuthEndpointParsers.ts, and shared fail-closed parsing primitives in betterAuthRecord.ts. Before accepting a Better Auth or @convex-dev/better-auth version change, run the boundary tests and the backend typecheck:

bun --cwd packages/backend test convex/auth
bun --cwd packages/backend typecheck

Treat any parser failure as a blocked upgrade. Confirm the changed component or endpoint response contract, then update the relevant module and its tests together; do not relax a parser merely to make the test pass. See the full checklist in Convex Backend → Upgrading Better Auth.