Authentication Overview

Authentication is built on Better Auth rather than hand-rolled session logic. A single auth instance is configured in packages/auth/server.ts, mounted at the catch-all route /api/auth/[...all], and backed by the Prisma/PostgreSQL adapter. Every flow — email/password, social, magic link, email OTP, two-factor, and password reset — runs through that one instance. The auth pages reach it server-side: a form dispatches a server action, and the action calls auth.api.* directly. The typed authClient (packages/auth/client.ts) matches the server plugin list and exports types. Auth pages and session reads do not call it at runtime — forms use auth.api.* in server actions; session helpers are getServerSession / requireAuth.

Ownership: who owns what

The integration is split between the @repo/auth package (the Better Auth server + client instances and the RBAC definitions) and the auth pages in the web app (apps/web/app/[locale]/auth/*), which are thin UIs over colocated server actions.

@repo/auth package (packages/auth/)

Package exports (package.json):

The auth pages (apps/web/app/[locale]/auth/)

Most pages follow the same "thin page, fat client" shape: a Server Component (page.tsx) awaits params, loads the localized error dictionary, and renders a "use client" form component colocated in a components/ subdir next to the page. Each form keeps react-hook-form for client-side validation and submits through a server action driven by useActionState; the action re-validates with safeParse and returns field/root errors as state (no design-system split, no authClient in the browser).

// page.tsx — the pattern, repeated for most flows
export default async function ForgotPasswordPage({ params }: ForgotPasswordPageProps) {
  const { locale } = await params;
  const dict = await getDictionary(locale);
  return <ForgotPasswordForm errors={dict.errors.action} />;
}

Sign-in is the one exception: its page.tsx is a Server Component that hosts the <Tabs> shell directly (reading ?tab= to pre-select a tab and ?callbackUrl= for the post-login destination) and renders three per-method client components rather than a single client.

Shared pieces (AuthCard, SocialProviders, and the zod schemas) live at auth/components/ and auth/schemas.ts — there is no design-system auth-molecule layer.

Enabled methods & plugins

The auth instance enables a wide surface through the plugin array in server.ts. Each server plugin has a matching client plugin in client.ts.

See Configuration for the full breakdown of each option.

Architecture

Outbound: an auth page dispatches its colocated server action, which calls auth.api.* in-process — no browser fetch to /api/auth/* is involved. That route still matters for traffic the server can't originate: the links in verification, reset and magic-link emails, and OAuth provider callbacks. The Better Auth instance runs the flow, persists via Prisma, and sends transactional email through @repo/email. Server Components read the resulting session through the cached helpers in lib/auth/auth.ts (auth.api.getSession — session-verified, cookie-cache eligible); the edge middleware.ts only gates on cookie presence before that — see Sessions & Route Protection.

Because auth.api.* bypasses Better Auth's HTTP-path rate limiter (which only runs on /api/auth/*), brute-forceable actions re-apply enforceRateLimit server-side — see apps/web/lib/auth/rate-limit.ts.

Persistence

Better Auth's Prisma adapter reads and writes a small set of tables (packages/database/prisma/schema.prisma):

Doc pages in this section

Source files

• packages/auth/server.ts — the betterAuth({...}) instance and plugin array
• packages/auth/client.ts — authClient and the bound method exports
• packages/auth/permissions.ts — admin + org RBAC (see Sessions & Route Protection)
• packages/auth/keys.ts — env schema
• packages/utils/auth.ts — timing constants (session/OTP/magic-link expiry)
• apps/web/app/api/auth/[...all]/route.ts — the Better Auth Next.js handler
• apps/web/app/[locale]/auth/* — the auth pages and their clients
• apps/web/lib/auth/auth.ts — getServerSession, requireAuth, hasOrgPermission
• apps/web/middleware.ts — edge route gating (cookie-presence check only) and CSP nonce