Skip to content

Auth ​

Better Auth, configured in packages/auth/src/index.ts. The web client mirrors the plugins in apps/web/src/lib/auth-client.ts.

Plugins ​

PluginWhy
usernameClient logins like dessertshop-admin. Pattern: lowercase letters/digits with single hyphens (USERNAME_PATTERN).
adminuser.role and user management by the owner. Roles in packages/auth/src/permissions.ts; owner is the admin role. Default role client.
organizationA client business is an organization. Org role owner = Client Admin, member = Client Member. Users cannot create organizations; the server does on conversion. Membership limit from access.maxLoginsPerClient.
twoFactorTOTP for Client Admins (and anyone the owner requires). Issuer shoot&grow-crew.

Accounts are provisioned, never self-served ​

  • emailAndPassword.disableSignUp is on. There is no sign-up page.
  • Staff accounts are created by the owner through the admin plugin.
  • Client accounts are created on conversion (Pipeline): organization, Client Admin user, temporary password hash flagged "must change", set-password link.
  • Sessions use cookies with SameSite=None; Secure; HttpOnly, because web and API are different origins in deployment.

Seats: the owner account is bootstrapped ​

ensureBootstrapUsers (packages/auth/src/admin.ts) creates and reconciles the owner account from OWNER_PASSWORD on every start (a Worker: once per isolate). Development staff seats (manager, sales, videographer, editor) exist only when DEV_SEATS_PASSWORD is set and are refused on the production stage. See Local backend.

Two kinds of role check ​

LayerGuardsLives in
Better Auth admin permissionsThe admin plugin's own endpoints (create/list/ban users, revoke sessions)packages/auth/src/permissions.ts
Business accessWho sees which client, lead, video, eventpackages/api/src/access.ts

Do not express business rules as admin-plugin permissions.

Sign-in policy ​

Two things can hold a signed-in person back until they are done. The server enforces both (packages/api/src/sign-in-policy.ts): every procedure except v1.me.policy answers FORBIDDEN with PASSWORD_CHANGE_REQUIRED or TWO_FACTOR_REQUIRED. The web app only mirrors this: loadSession reports a gate and /_app sends the browser to /security.

GateStarts whenEnds when
New passwordThe owner creates a login or sets its password through the admin plugin (user.mustChangePassword). Dev seats and the owner are exempt: their password comes from a secret.The person changes it (/security, Better Auth changePassword) or sets it from an emailed link.
Authenticator appA Client Admin has none and access.requireClientAdminTwoFactor is on (default). Client Members are never asked.They scan the code and enter a valid six digits (/security).

Once an authenticator app is on, /login asks for the code after the password, or a backup code.

Forgot password. /forgot calls v1.public.password.forgot, which emails a single-use set-password link (reset_password, valid access.setPasswordLinkTtlHours) and answers identically whether or not the account exists. It is limited per caller and per account. The owner, banned users and disabled logins get nothing.

The local e2e stack (e2e/stack.sh) switches the authenticator requirement off so the client specs can sign in with a password only.

Limits read at request time ​

access.passwordMinLength and access.maxLoginsPerClient are read from Settings on each request (packages/auth/src/limits.ts), so a change applies at once. A Better Auth hook enforces the length on change, reset and owner-set passwords; the organization membershipLimit is a function. The static minPasswordLength handed to Better Auth is only the lowest value the setting allows.

Audit ​

Password changes, owner-created logins and owner-set passwords write audit_log rows from the same hook (user.change-password, user.create, user.set-password-by-owner); set-password links and reset requests write theirs in public-password.ts.

Regenerating the schema ​

After changing plugins, run from packages/auth: bunx auth@latest generate --config src/auth.cli.ts --output ../db/src/schema/auth.ts, review the diff, then bun run db:generate (Database). auth.cli.ts builds the auth object with dummy config; it never connects to a database.

Internal documentation. Not for clients.