Authentication
Cookie sessions, the auth routes, and how role checks are enforced.
Authentication
Session cookies
Signing in sets one HttpOnly cookie, jv_session. It holds a 256-bit random token; the database keeps only its SHA-256 digest in auth_sessions, alongside user_id, expires_at, last_seen_at and revoked_at. The cookie is sent automatically with every same-origin fetch, which is why the dashboard never handles a token in JavaScript. Because it is HttpOnly, client code cannot read it — the settings page reports the mechanics rather than a value for that reason.
A session ends after 24 hours without activity. Each request slides that window forward (the row is renewed when less than 20 hours remain) and last_seen_at is rewritten at most once a minute, so a busy tab is not a write per request. No session outlives 30 days from its first sign-in. Signing out sets revoked_at rather than deleting the row, which is what makes a copied token useless afterwards.
Two cookies from an earlier version — session_id and user_id — are cleared on the next login or logout. Nothing reads them.
Routes
- POST /api/auth/register — create an account.
- POST /api/auth/login — exchange email and password for the session cookie.
- POST /api/auth/logout — revoke the current session.
- GET /api/auth/session — describe the current session: the user, or the reason it ended, or 503 when the database could not be reached.
- POST /api/auth/forgot-password — issue a reset token and send the link.
- POST /api/auth/reset-password — consume the token and set a new password.
- GET /api/auth/verify-token — check a reset token before showing the form.
There is also POST /api/auth/signup, kept for the marketing signup form, which routes into the same registration path.
Every one of these is rate limited per IP, and per email address where one is submitted: 20 login attempts per 15 minutes, 10 signups an hour, 5 reset mails an hour. A blocked caller gets 429 with a Retry-After header.
Enforcing it in a route handler
import { getSession } from "@/lib/auth-actions"
const session = await getSession()
if (!session) {return NextResponse.json({ success: false, message: "Unauthorized" }, { status: 401 })
}getSession() throws SessionUnreachableError when the database did not answer, and that must not be answered with 401: a 401 says the caller is signed out, and nothing of the sort happened. Let it escape as a 500 so the client retries. For the same reason app/api/auth/session answers 503 rather than an empty user.
For role checks use getCurrentUser() with isSuperAdmin()/isPrivilegedRole() from lib/session and lib/team-settings-model, and answer 403 rather than 401 when the caller is signed in but not allowed.
Redirects
proxy.ts checks only that the cookie is present and sends anonymous visitors to /login; it is a redirect aid, never the boundary. The dashboard layout resolves the session on the server: anonymous goes to /login, an invalid session goes to /login?reason=not_found|expired|revoked, and an unreachable database falls through to the page instead of redirecting. The login page shows that reason and returns the visitor to ?next= after signing in, accepting only a single-slash-rooted same-origin path.
ADMIN_EMAILS
A comma-separated allow-list of emails treated as super-admin regardless of the stored role. It exists so the first administrator can bootstrap governance. Set it in the environment (and in .env.example with a note about where the value comes from) rather than in code.
Password resets
The link carries a 256-bit random token; password_reset_tokens stores only its SHA-256 digest, with an expiry. /forgot-password requests one, /reset-password consumes it. A token can be used once. If the database cannot answer, both routes reply 503 instead of calling the link invalid.
Development note
Some task routes permit unauthenticated access when NODE_ENV is development or ENABLE_TEST_MODE is "true", so the CSV importer and scripted tests can run without a browser session. In production that flag is off and the 401 path applies.