Authentication

Master switch for the entire authentication subsystem.

Required when enabled. full provisions the auth tables, mounts all auth routes and runs the session middleware — this is your IDP. consumer mounts no auth tables or routes; it only verifies incoming JWTs, delegating login to a separate IDP.

• full— IDP: auth tables + auth routes + JWT/session middleware.
• consumer— Resource server: JWT-verify middleware only, no auth tables or routes.

Role assigned to every newly created user (register, OAuth auto-create, invite). If the named role is missing a warning is logged and sign-up still succeeds — default-role assignment is intentionally non-fatal.

Example: "user-free"

For consumer mode with authorization enabled: the URL (or env-var name) of the IDP whose POST /auth/check this service calls for scope-based decisions.

Example: "http://idp-api:9000"

Cookie Domain attribute for sharing auth across subdomains. Use a leading dot — ".vorion.ai" — to cover every subdomain. Accepts a literal value or an env-var name. Omit for host-only cookies.

A safety buffer applied to cookie Max-Age so the middleware proactively refreshes a token slightly before it actually expires, avoiding edge-of-expiry race conditions.

Signed tenant binding for schema-per-tenant deployments, where the active tenant is resolved from the request independently of the caller — so an access token minted for tenant A would otherwise be structurally valid against tenant B. When enabled, tokens carry a signed tenant claim the middleware checks against the resolved x-tenant-schema. 'lenient' (default) enforces the claim when present but allows legacy tokens without it (no flag-day logout; closes within the token TTL); 'strict' requires the claim whenever a tenant is resolved; 'off' disables it. Single-tenant deployments are unaffected in any mode.

• lenient— Enforce the tenant claim when present; allow legacy tokens that lack it.
• strict— Require the tenant claim whenever a tenant is resolved.
• off— Disable tenant binding entirely.

Allow-list of frontend origins permitted to drive the outbound host of email links (reset / magic-link / verify / invite) via the x-app-origin / Origin / x-forwarded-host headers. The configured action redirect URL's own host is ALWAYS trusted; this adds extra hosts for multi-tenant deployments where tenants live on different subdomains. Accepts exact hosts or *.domain wildcards. A header origin not on this list (and not the configured URL's host) is ignored, preventing link poisoning / token exfiltration via a spoofed host header. Besides an array, a single bare string is accepted and resolved as an env-var name (e.g. "FRONTEND_URL") — the same env-var-name resolution cookieDomain uses — whose value may itself be a comma/space-separated list of origins; a literal comma-separated string also works. This lets a deployment avoid hardcoding customer domains in the image.

Example: ["app.example.com", "*.tenants.example.com"] // or "FRONTEND_URL"

When true, register / resend-verification / invite return a UNIFORM generic response whether or not the email already exists, so an attacker cannot enumerate registered accounts by diffing responses. Side effects (creating users, sending mail, cooldown/attempt limits) still run silently server-side. Default false preserves the explicit 'email already registered' / 'already verified' responses; enable for public sign-up.

Double-submit-cookie CSRF protection for COOKIE-authenticated, state-changing requests (POST/PUT/PATCH/DELETE). Default off (cookies are already SameSite=Lax). When enabled the middleware sets a readable csrf_token cookie and requires the client to echo it in an x-csrf-token header; requests authenticated via an Authorization header are exempt (not CSRF-able). Pass true to enable with defaults, or an object to rename the cookie / header.

Composable rules for what makes an acceptable password.

Short-lived API credential — minutes, not days. Verified on every protected request.

Long-lived (days). Exchanged at the refresh route for a fresh access token. Same fields as accessToken, with its own secret, name and a longer expiresIn (e.g. 7d).

Identifies the device session (e.g. 30d) so users can list and revoke devices. Unlike the other two this is NOT a JWT — it is an opaque random id kept in Redis. Its secret must still be set in full mode (boot + middleware presence check) but is never used to sign; algorithm / issuer / audience are ignored. name (cookie name), expiresIn, setHeadersEnabled and returnJson apply (see the callout below).

Each route object (login, logout, register, …) carries at least these three fields, plus route-specific extras documented below.

Credential sign-in configuration.

Sign-up configuration.

Device-session policy.

Passwordless sign-in via emailed link. Extras: verifyRoute, expiresIn (e.g. 15m), redirectUrl.

Admin-initiated user creation. Extras: tokenExpiresIn (e.g. 7d), redirectUrl to a set-password page.

Forgot-password flow. Extra: redirectUrl to the reset form.

Change password while authenticated (requires current password).

Set an initial password (invited/OAuth users with none yet).

Declared in the type (route, resendRoute, isPublic, enabled) but NOT consumed by the plugin — setting it has no effect. The verify + resend endpoints are generated from register.emailVerification at the fixed public paths GET /verify-email and POST /resend-verification.

Exchanges a refresh token for a new access token. Usually isPublic.

Revokes the session and clears auth cookies.

Passkey configuration.

Profile endpoint configuration.

Challenge configuration.

Social-login configuration.

API-key issuance policy.

Cohort endpoints for grouping users into segments — all cohort endpoints are GODMIN-ONLY (every handler requires a godmin user via requireGodmin; non-godmin callers get 403 Forbidden). enabled defaults to TRUE — the cohort endpoints are auto-added (non-consumer mode with a DB) unless enabled is set false. basePath defaults to '/auth/admin/cohorts'.

Domains (and their sub-domains, case-insensitive) exempted from SECURITY emails — registration verification, password-reset, and new-device approval — via isEmailExempt. Perfect for trusted internal domains where those mails are redundant.

Example: ["yourcompany.com", "internal.local"]

Login writes a SessionRecord to Redis (opaque crypto.randomUUID() id) and, when the user_sessions table is present, a matching DB row. The session id is what the session_token cookie carries and what the middleware resolves per request. (There is an issueSession() orchestrator primitive in Services/Auth/Session, but the live login route does not use it — it calls signRefreshToken + createSession directly.)

A hand-rolled HS256 JWT (sub = userId, plus iat/exp). Beyond those it embeds the user's roles as a custom claim (when they have any), and — only in JWT embed mode (jwtClaimsMode !== 'resolve', the default) — the user's claims plus per-action claimScopes (row-level ownership scope) so embed-mode consumers can enforce it; in resolve mode claims/claimScopes are omitted and re-resolved from Redis at request time. H9 (multi-tenant): the login path also stamps a `tenant` custom claim equal to the resolved x-tenant-schema whenever a tenant is present, and the request middleware rejects (401) an otherwise-valid token whose `tenant` does not match the request's tenant (verifyTenantBinding) — the default 'lenient' mode still rejects a present-but-mismatched claim (it only tolerates a token with no tenant claim at all; 'strict' rejects that too). iss/aud are stamped only when authentication.accessToken.issuer/audience are configured — both are undefined by default and are therefore omitted from the token; the live login path does not embed a sessionId either. SECURITY (M5): the LOGIN-minted token (signAccessToken) does NOT embed the refresh token — the refresh credential is returned separately so capturing this short-lived access token never yields the long-lived refresh token. (This applies to the login path only; the middleware's silent-refresh re-mint takes a different path that DOES carry the refresh token — see 'single-flight refresh'.) The middleware also asserts the access token's sub equals the resolved session's userId. Default TTL is 15 minutes; accessToken config tunes it.

A signed JWT verified statelessly at /auth/refresh — the route checks the signature with the refresh secret (which is DISTINCT from the access secret, and that is what actually stops an access token being replayed as a refresh token; an audience check only runs if authentication.refreshToken.audience is configured, and it asserts the token's aud equals whatever value the operator set there — not a hardcoded 'refresh'), with NO Redis/session lookup, so rememberMe works without server state. A consequence: a single refresh token is NOT individually revocable. Revocation is done at the SESSION layer — logout, logout-everywhere and per-session revoke delete the session (and revoke the DB row), and the access-token↔session subject binding makes that immediately effective. /auth/refresh additionally re-checks account state (isActive / isLocked / cohort-expiry) and re-fetches fresh roles/claims on every use.

This lock guards the middleware's AUTOMATIC silent-refresh — the server-side branch that re-mints the ACCESS token — NOT the explicit /auth/refresh route (which uses no lock and rotates BOTH tokens). The silent-refresh branch is narrowly gated: it fires only when the access token is invalid/expired AND a still-valid refresh token accompanies the request AND the session is a rememberMe session (sessionData.rememberMe === true) — a non-rememberMe session, or a request without a valid refresh token, never triggers the silent re-mint. Before minting it also re-checks the account is active + unlocked via evaluateAccountState (a kill-switch that /auth/refresh performs too), so an admin deactivation/lock takes effect on this path. On this path only the access token is re-minted (the generateToken callback calls signNewAccessToken); the refresh token is untouched, so 'access-token re-minting' is more accurate than 'token rotation' here. NOTE — unlike the login-minted token, signNewAccessToken embeds the CURRENT refresh token as the refreshTokenId custom claim (the caller feeds it the raw tokens.refresh_token), so the silently re-minted access token DOES contain the long-lived refresh token; capturing this particular token would yield it, and the M5 'never' above holds for the login-minted token, not this one. Access-token re-minting is serialised with a Redis lock (acquireLock in refreshAccessTokenWithLock) so a burst of tabs hitting an expired access token at once re-mints exactly once instead of racing. The lock key is per-user (refresh_lock:userId) while the freshly-minted token is cached per user:session (access_token:userId:sessionId); lock losers waitForLock and read that cached token.

Each session stores id, userId, createdAt/expiresAt/lastActiveAt, optional clientMeta, deviceInfo (name, type desktop|mobile|tablet|unknown, browser, OS, IP, userAgent, and optional geo enrichment locationCountry/locationCity set from the request IP at login), loginMethod and rememberMe. fingerprintHash and refreshTokenHash are declared on the type but are NOT populated by the live login path (createSession forwards neither), so a real login session leaves them undefined. This per-device record is exactly what the Sessions/Devices endpoints (and the DevicesPage UI) list and revoke.

The live auth path hashes passwords with bcrypt (cost 10) via Bun's built-in `password` module — hashPassword() in register/utils.ts calls password.hash(plain, { algorithm: 'bcrypt', cost: 10 }), and verifyPassword() in login/utils.ts calls password.verify(). The same bcrypt hashPassword is reused by the register, password-set, password-change and password-reset routes. (A separate scryptSync primitive exists under Services/Auth/Password/Generate + Validate, but it has no auth call sites — it is not wired into the live login/registration routes.) The password-policy config governs what is allowed before this point.

The live runtime does NOT do a per-request fingerprint recompute-and-compare. Device identity comes from the client's deviceHint (deviceInfo.deviceHint → deviceFingerprint), stored on the session / DB row by saveSessionToDb and used to detect a new device for the approval flow (config.authentication.sessions / deviceTrust). The Services/Auth/Fingerprint Generate/Validate primitives and SessionRecord.fingerprintHash exist but are not populated by the login path (createSession forwards no fingerprintHash), so there is no fingerprintValid check on ordinary requests.

The request middleware runs its own inline validation rather than the ValidateSessionResult primitive: it verifies the access-token JWT signature, loads the live Redis session record, then asserts String(jwt.payload.sub) === String(session.userId), returning 401 on mismatch or a missing session. It never invokes validateSession and does no fingerprint comparison. The Services/Auth/SessionStore validateSession / ValidateSessionResult type is an available primitive with no live call sites.