Sessions, login, and first run

Cookies, CSRF, 2FA, password recovery, and setup.

Repository-validated operator guidance View source ↗

#Cookies and CSRF

Login sets two cookies: __Host-forge_session (HttpOnly JWT, 24 hours by default, max 7 days) and __Host-forge_csrf (readable). Every mutating request must send the X-CSRF-Token header matching the cookie and the session-bound derived value, and the origin must match the panel URL. Bearer tokens and API keys skip CSRF because they are not ambient credentials. Production refuses insecure cookies; misconfigured SameSite fails startup, not silently.

#Login, 2FA, recovery

Flow	Behavior
Login	5 attempts per minute per IP+email; TOTP users get a 5-minute confirmation token bound to IP and user-agent instead of a session.
Checkpoint	Single-use, IP/UA-bound; 10 failures lock out for 15 minutes.
Refresh	Rotates the session, revoking the old token ID.
Logout	Revokes the token ID and clears cookies.
Password reset	Single-use 30-minute token, enumeration-safe responses.
Sessions page	List and revoke your own sessions; admins enforce 2FA policy none, admin, or all.

FLOW

Session establishment

01Loginconfirm

022FA checkpointsign

03Session cookieverify

04CSRF-bound mutations

#First run

With no admin present, GET /setup/status reports required: true and POST /setup creates the first admin (with optional organization, node, SMTP, and backup provider) and signs you in. If an admin exists, setup answers 403. The demo stack instead seeds admin@example.com for development only.

Secrets that protect everything

API_AUTH_SECRET must be 32+ characters in production. Session signing, CSRF derivation, OAuth tokens, and websocket tickets all chain from it. Leaking it invalidates every assumption on this page.