Authentication and authorization model
Where identity is read, how access is decided at each boundary, and why there is no fallback user.
Authentication establishes who is calling. Authorization determines whether that caller may perform an action. Kernlift keeps both in one directory, checks them at more than one layer, and has no fallback identity. To set up sign-in methods and roles, see Set up email and password sign-in and Manage users, roles and permissions.
One place reads a session
src/server/auth/ is the only code allowed to read a Better Auth session. It has three parts:
| File | Decides | Main exports |
|---|---|---|
context.ts | Who the caller is | requireAuthContext() (the default, throws without identity), getAuthContext() (returns null, for genuinely optional-identity paths) |
guards.ts | Whether the caller may act | requirePermission, requireOwnership, requireNotBanned, hasPermission |
api-boundary.ts | How an API handler authenticates | withApiAuth, which accepts a session or, when the route opts in, an API key with a named scope |
An AuthContext carries userId, roles, permissions, status, sessionId, apiKeyId and
source. The source is session, api-key or dev-impersonation.
Better Auth itself is built in auth.ts from settings stored in the admin console, and mounted at
/api/auth/* for OAuth callbacks and the password reset link. Because Google and GitHub credentials
are read per request, saving them needs no restart.
There is no identity fallback
An unauthenticated caller is rejected. No code path maps it to a default user. The only exception
is a development sign-in bypass, and it requires both APP_ENV=development and an explicit
AUTH_DEV_IMPERSONATE_USER_ID. Either one alone has no effect, and the server logs a warning the first
time the bypass applies.
Access is checked in layers
A request to a protected page passes several checks. Each check alone is enough to reject it.
| Layer | Where | What it checks |
|---|---|---|
| Request middleware | src/start.ts | Page requests for /app/* and /admin/* without a session cookie go to /auth/sign-in |
| Workspace layout | app.tsx | A banned user goes to /system/permission-denied; missing identity or an inactive account goes to /system/session-expired |
| Admin layout | admin.tsx | Requires admin.access; missing identity goes to /system/session-expired, a missing permission to /system/permission-denied |
| Server function | requireAdminPermission | Each admin function checks its own permission key, so a page is never the only gate on its data |
| API route | withApiAuth | Session or scoped API key; otherwise the route must be on the explicit public list |
Guarding at the layout level means a new page under /app or /admin is protected by default.
Roles, permissions and status
Roles, permissions and status are resolved together from the user's access profile, role
assignments and each role's permissions. Profiles are written only when an operator changes a
user's access, so a user without one resolves to active.
| Status | Effect |
|---|---|
active | Normal access, subject to permissions |
banned | Rejected by every guard; a session is refused at creation. A ban whose end date has passed resolves to active |
pending | Not active, so workspace and admin guards reject it |
requirePermission and requireOwnership both call requireNotBanned first, so an inactive account
fails before any permission check. Roles group permission keys; see Roles and permissions.
Ownership hides existence
Owner-scoped reads include the caller's id in the query. A
record belonging to someone else is then indistinguishable from one that does not exist, so an
endpoint cannot be used to probe for other people's data. Where a record's existence is sensitive,
the route answers 404 rather than 403, as /api/status does for another user's task.
Public endpoints are listed, with reasons
Every API route either uses withApiAuth or appears in an explicit public-endpoint list with a
stated reason. Provider webhooks and signed-grant redemption are on
that list: they authenticate by signature or by an unguessable credential.
API keys and scopes
API keys are hashed at rest, shown once, and carry scopes: ai:run, ai:read, files:write and
files:read. Users can put ai:run, ai:read and files:write on their own keys. files:read is
reserved. With the agent installed, operators can also issue keys with agent:read and agent:run.
Sign-in rate limit
The auth.sign-in rule allows 10 attempts per 300 seconds per IP and email. It is part of the
baseline content that pnpm db:bootstrap-super-admin writes, and each decision is recorded in the
audit log. A blocked caller lands on /system/rate-limited.
How this is enforced
pnpm validate:auth-boundary checks that sessions are read only in src/server/auth/, that the
layouts guard their trees, that there is no identity fallback, that impersonation is double-gated, that
production refuses the template session secret, and that every API route uses withApiAuth or is
listed as public.