Authentication, tiers & headers

Authentication model

VerifAIer uses two credential types, chosen by tier. Both are local-first primitives, there is no hosted OAuth, OIDC, or SSO integration in the current implementation.

Session tokens (browser + API clients)

POST /api/auth/login exchanges email + password for a session. The session token is an HMAC keyed by SESSION_SECRET with an 8-hour default TTL (AUTH_TOKEN_TTL=28800). Two transports are accepted, cookie first:

1. vai_session cookie: set by login, HttpOnly; Secure in production; SameSite=Lax. Browser clients use this automatically. A non-HttpOnly vai_session_active=1 flag cookie lets JS detect a session without reading the token.
2. X-Session-Token header: for API clients, the CLI and the MCP server. Backwards-compatible; carries the raw token returned in the login response body.

sequenceDiagram
  autonumber
  participant C as Client
  participant API as /api/auth/login
  participant RL as RateLimiter
  participant S as session service
  C->>API: POST {email, password}
  API->>RL: is_allowed(login:IP, 20, 900s)
  alt over limit
    RL-->>C: 429 Too many login attempts
  else allowed
    API->>S: authenticate_user(email, password)
    alt bad credentials
      S-->>C: 401 Invalid credentials
    else ok
      S->>S: create_session(user_id) → HMAC token
      API-->>C: 200 {session_token, ...} + Set-Cookie vai_session (HttpOnly)
    end
  end

API keys (control tier)

The Control Center data endpoints (/api/control/*) authenticate with an X-API-Key header. Keys are formatted vrf_<8-hex-prefix>_<secret>, stored as PBKDF2-HMAC-SHA256 hashes (100k iterations) with a per-key salt, and scoped to an organization. The prefix is a fast DB lookup index; the full key is shown once at creation and never stored. Provision one with the owner bootstrap script (scripts/cc_bootstrap_owner.py → create_org_and_key).

API tiers

The Control Center also exposes a session-based console subset (/api/control/auth/login, /auth/me, /auth/logout and some member/settings management) that binds an org membership; those use org-membership sessions rather than an API key. See the authenticated APIs.

Authorization model

Authorization today is deliberately coarse and honest about its scope:

• Session tier, authentication-gated, no role enforcement. The require_authenticated_user guard accepts any valid session ("No role enforcement, all authenticated users are accepted"). The AuthenticatedUser record carries organization_id, membership_id and role fields, but for the current session path they are empty strings, reserved for future RBAC gates, not yet enforced.
• API-key tier, org-scoped. A validated X-API-Key resolves to an org_id; control-center data is scoped to that organization.
• Billing, org-access checks. /api/billing/* adds an explicit _require_org_access(org_id, user) check on top of authentication.
• Control console, role-aware. A subset of /api/control/* uses require_admin_session / require_user_session (org-membership sessions) where an admin vs. member distinction applies.

Headers

Request headers

Response headers

Every response carries hardening headers set by _SecurityHeadersMiddleware (with setdefault, so handlers can override but never lose them):

X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
Referrer-Policy: strict-origin-when-cross-origin

CORS is applied by CORSMiddleware: origins from CORS_ORIGINS (JSON array, default ["*"] for the extension + dev dashboard), credentials disabled, methods limited to GET, POST, DELETE, OPTIONS. Restrict CORS_ORIGINS in production.

Security considerations