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.

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. Same fields as accessToken with its own secret and name.

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).

Standalone verify + resend endpoints (route, resendRoute).

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.

Enables cohort endpoints for grouping users into segments. When enabled the cohort endpoints are auto-added to the generated client. basePath sets their route prefix.

Email domains whose users skip email verification on register (matched by isEmailExempt). Perfect for trusted internal domains where confirmation is redundant.

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

generateSession (writes a SessionRecord) → generateRefreshToken (writes a Redis-backed refresh record) → signJWT (the access token). If the refresh step fails the just-created session is deleted, so a half-issued login never lingers. Returns accessToken, refreshToken, their expiries and the sessionId.

A hand-rolled HS256 JWT (sub = userId, iss = 'auth', aud = 'api', plus iat/exp). It carries the sessionId and embeds the refresh token id as a custom claim, so the server can tie an access token back to its session and refresh record. Default TTL is 15 minutes; accessToken config tunes it.

Also a signed JWT, but the source of truth is its record in Redis. Validation verifies the signature, asserts aud === 'refresh' (so an access token can't be replayed as a refresh token), then looks the record up in Redis and checks expiry. Because the record lives in Redis, revocation is simply deleting the key — that is how logout, logout-everywhere and per-session revoke work.

Token rotation is serialised with a Redis lock (acquireLock), so a burst of tabs refreshing at once rotates exactly once instead of racing and invalidating each other. The losers wait on the lock and read the freshly-minted token.

Each session stores id, userId, createdAt/expiresAt/lastActiveAt, deviceInfo (name, type desktop|mobile|tablet, browser, OS, IP, userAgent), fingerprintHash, refreshTokenHash, loginMethod and rememberMe. This per-device record is exactly what the Sessions/Devices endpoints (and the DevicesPage UI) list and revoke.

Passwords are hashed with scryptSync using a fresh 16-byte random salt and a 64-byte derived key, stored as salt_hex:derivedKey_hex. Verification re-derives with the stored salt and compares — no external bcrypt/argon dependency, just the Node crypto primitive. The password-policy config governs what is allowed before this point.

At login a fingerprint is derived from request characteristics and its hash saved on the session. On subsequent requests the fingerprint is recomputed and compared, so a stolen token presented from a very different device can be flagged (fingerprintValid in the validation result).

Validating a request checks the JWT signature, that the session still exists in the store, and (when supplied) that the device fingerprint matches — returning { isValid, reason, context: { userId, sessionId, fingerprintValid } } so middleware can both authorise and explain a rejection.