Auth and database

Sign-in runs on Better Auth 1.4 with its Drizzle adapter, so users, sessions and teams live in your own Postgres. There is no Supabase Auth and no password sign-in. The schema is one file, lib/db/schema.ts, and changes reach the database through Drizzle migrations.

Setting the integration up is the setup-auth and setup-database skills (Auth, Database). This page is about the code.

Better Auth

The server instance is auth in lib/auth/index.ts, mounted at app/api/auth/[...all]. The browser client is authClient in lib/auth/auth-client.ts, with the same plugins.

Sign-in methods

The login form (components/auth/LoginForm.tsx) shows a provider's button only when its client id is set. Accounts with the same email are linked for Google and GitHub. The lastLoginMethod plugin remembers the last method used.

Plugins

There is no anonymous plugin: /api/auth/sign-in/anonymous does not exist and user.is_anonymous is always false.

Sessions

• Sessions last 30 days and are extended once a day of use.
• The session is cached in a signed cookie for 10 minutes. Within that window a ban or role change is not visible through the cache.
• The session row stores the client IP, read with the same header order as the rate limiter and attribution (CLIENT_IP_HEADERS in lib/ip.ts).

Hooks

Attribution: proxy.ts writes a first-touch cookie with UTM fields, the ref/via/aff code, referrer and landing page (lib/tracking/capture.ts); the browser adds screen, language and time zone; the hook turns it into a user_source row with parsed user agent and Cloudflare geo headers. With NEXT_PUBLIC_COOKIE_CONSENT_ENABLED=true, a visitor who declined cookies is not tracked.

Reading the session on the server

lib/auth/server.ts has two channels. Both are deduped per request with React cache().

import { getSession, isAdmin } from '@/lib/auth/server'

export async function myAction() {
  const session = await getSession()
  if (!session?.user) return actionResponse.unauthorized()
  // …
}

export async function myAdminAction() {
  if (!(await isAdmin())) return actionResponse.forbidden()
  // …
}

Page redirects belong to components/auth/AuthGuard.tsx, used by the dashboard layout: no session redirects to /login; a role check uses the fresh session. lib/auth/permissions.ts has isAdminUserRole and isSuperAdminUserRole, safe on server and client.

More patterns (client hooks, API routes, sign-out, adding a provider) are in skills/reference/auth.md.

Roles and impersonation

user.role is one of user, admin, superadmin. pnpm create-superadmin <email> (lib/db/scripts/create-superadmin.ts) creates or promotes the owner account.

Some actions add their own checks: changing a role and deleting an account (actions/users/admin.ts) require superadmin.

Impersonation (actions/users/impersonation.ts):

• startImpersonation requires a superadmin (fresh session); the target may not be an admin, a superadmin or banned. Admin accounts can never be borrowed, because the admin plugin lists both roles in adminRoles.
• Better Auth swaps the cookie and keeps the superadmin's own session in a signed admin_session cookie. The borrowed session lasts one hour; session.impersonated_by records who borrowed it.
• components/auth/ImpersonationBanner.tsx shows "Viewing as …" with the way back; stopImpersonation ends it. Both actions log a warning for the audit trail.
• While impersonating you act as that user, including spending their credits.

Teams

The organization plugin (lib/auth/organization.ts):

• The creator becomes owner. A user may create up to 5 organizations.
• Invitations expire after 48 hours and are mailed with emails/organization-invitation.tsx, linking to /accept-invitation/<id>.
• The seat cap follows the team's live subscription: the plan's seats, or 1 (the owner alone) without one. It is checked on invite, on accept and on add, and a race that overfills a team is undone under an advisory lock.
• An organization with a live subscription or any credit history cannot be deleted.

Rate limiting

Two separate mechanisms:

Better Auth's limiter (rateLimit in lib/auth/index.ts) applies only when NODE_ENV=production and NEXT_PUBLIC_RATE_LIMIT_ENABLED=true. Per IP:

With Redis configured the counters are stored there; otherwise Better Auth keeps them in memory.

checkRateLimit(identifier, config) (lib/redis/rate-limit.ts) is for your own actions and routes. Upstash uses a sliding window; self-hosted Redis (ioredis) uses a fixed window that can allow up to twice the quota at a window edge. Without Redis every call is allowed. Presets in RATE_LIMIT_CONFIGS:

import { checkRateLimit, getClientIPFromHeaders, RATE_LIMIT_CONFIGS } from '@/lib/redis'

const ip = await getClientIPFromHeaders()
if (!(await checkRateLimit(ip, RATE_LIMIT_CONFIGS.newsletter))) {
  // over the limit
}

The schema

All tables are in lib/db/schema.ts, in the public schema. Primary keys are uuids. Timestamps are timestamp with time zone. Money columns are integers in cents.

Columns worth knowing:

• user: role (user_role enum), banned, ban_reason, ban_expires, and one customer id per provider: stripe_customer_id, creem_customer_id, paypal_payer_id (each unique). Each id has one writer: lib/billing/customer.ts, lib/billing/creem.ts and lib/billing/paypal.ts.
• session: active_organization_id (null = personal workspace) and impersonated_by, both without a foreign key.
• orders: plan_id (a slug from config/pricing.ts, not a foreign key), order_type, status (pending, completed, partially_refunded, refunded, failed), the amount columns in cents (amount_total, amount_subtotal, amount_discount, amount_tax, amount_refunded), provider, provider_order_id, provider_payment_id, provider_subscription_id. Unique on (provider, provider_order_id).
• subscriptions: plan_id, provider, provider_subscription_id (unique with provider), status, interval, the period columns, and the yearly drip schedule monthly_credits, remaining_grants, next_grant_at.
• credit_transactions: see Credits.

Plans are not in the database. payment_provider is a Postgres enum that mirrors the PaymentProvider type in config/pricing.ts.

Foreign keys and deletion

The app refuses to delete users and organizations with live billing before the database is asked (the beforeDelete hooks above).

Migrations

drizzle.config.ts points Drizzle Kit at lib/db/schema.ts and writes SQL to lib/db/migrations/. It reads DATABASE_URL from .env.local.

Agent: after a schema change, runs pnpm db:generate, shows you the new SQL file, and runs pnpm db:migrate against the development database.

You: approve before anything is run against production. To migrate production from your machine:

DATABASE_URL="<production connection string>" ./node_modules/.bin/drizzle-kit migrate

On Supabase, run migrations with the session pooler or direct connection string, not the transaction pooler on port 6543. To keep several products in one database, each in its own Postgres schema, see skills/reference/db-schema-migration.md.

Connection settings

lib/db/index.ts exports db.

• On Cloudflare Workers with a HYPERDRIVE binding, each request gets its own client through Hyperdrive (at most 5 connections, prepared statements off). A Worker may not reuse a socket across requests.
• Everywhere else one shared client is built by createDatabase in lib/db/config.ts, which merges a platform profile with a database profile.

The last rule means a hosted Postgres that is not one of the four named providers still gets TLS without ?sslmode=require in the URL.

When it fails