Appearance
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
| Plugin | Why |
|---|---|
username | Client logins like dessertshop-admin. Pattern: lowercase letters/digits with single hyphens (USERNAME_PATTERN). |
admin | user.role and user management by the owner. Roles in packages/auth/src/permissions.ts; owner is the admin role. Default role client. |
organization | A 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. |
twoFactor | TOTP for Client Admins (and anyone the owner requires). Issuer shoot&grow-crew. |
Accounts are provisioned, never self-served
emailAndPassword.disableSignUpis 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
| Layer | Guards | Lives in |
|---|---|---|
| Better Auth admin permissions | The admin plugin's own endpoints (create/list/ban users, revoke sessions) | packages/auth/src/permissions.ts |
| Business access | Who sees which client, lead, video, event | packages/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.
| Gate | Starts when | Ends when |
|---|---|---|
| New password | The 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 app | A 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.