Kernlift

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:

FileDecidesMain exports
context.tsWho the caller isrequireAuthContext() (the default, throws without identity), getAuthContext() (returns null, for genuinely optional-identity paths)
guards.tsWhether the caller may actrequirePermission, requireOwnership, requireNotBanned, hasPermission
api-boundary.tsHow an API handler authenticateswithApiAuth, 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.

LayerWhereWhat it checks
Request middlewaresrc/start.tsPage requests for /app/* and /admin/* without a session cookie go to /auth/sign-in
Workspace layoutapp.tsxA banned user goes to /system/permission-denied; missing identity or an inactive account goes to /system/session-expired
Admin layoutadmin.tsxRequires admin.access; missing identity goes to /system/session-expired, a missing permission to /system/permission-denied
Server functionrequireAdminPermissionEach admin function checks its own permission key, so a page is never the only gate on its data
API routewithApiAuthSession 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.

StatusEffect
activeNormal access, subject to permissions
bannedRejected by every guard; a session is refused at creation. A ban whose end date has passed resolves to active
pendingNot 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.

Files

src/server/auth/context.ts
src/server/auth/guards.ts
src/server/auth/api-boundary.ts
src/server/auth/auth.ts
src/routes/{-$locale}/app.tsx
src/routes/{-$locale}/admin.tsx

Next steps