Configuration
Auth’s runtime config lives at src/config/auth.ts. It is shaped by the AuthConfigurations type — import it for IntelliSense.
The whole config, minimal version
Section titled “The whole config, minimal version”import type { AuthConfigurations } from "@warlock.js/auth";import { env } from "@warlock.js/core";import { User } from "@/app/users/models/user.model";
const authConfig: AuthConfigurations = { userType: { user: User, }, jwt: { secret: env("JWT_SECRET"), expiresIn: "1h", refresh: { secret: env("JWT_REFRESH_SECRET"), enabled: true, expiresIn: "30d", rotation: true, maxPerUser: 5, }, },};
export default authConfig;Every option, explained
Section titled “Every option, explained”userType — required
Section titled “userType — required”The slug-to-model registry. Each key is a user-type slug; each value is a Cascade model class extending Auth.
userType: { user: User, admin: Admin, vendor: Vendor,}Every token carries its slug; the middleware looks it up here to hydrate the right model. The slug appears in the user_type column on access_tokens + refresh_tokens rows.
See Customize user type for the multi-user-type model.
jwt.secret — required
Section titled “jwt.secret — required”The signing key for access tokens. Pull it from env("JWT_SECRET") — never hard-code it.
Use at least 32 bytes (warlock jwt.generate writes 64). In production, a shorter accessToken.secret or refreshToken.secret logs a one-time warning at the first token issue: one captured token is enough to guess a short secret offline and forge tokens for any user.
jwt.algorithm
Section titled “jwt.algorithm”The signing algorithm passed to fast-jwt. Default: "HS256". Accepts any Algorithm value from fast-jwt. Most apps stay on the default.
jwt.expiresIn
Section titled “jwt.expiresIn”Access-token lifetime, as a ms package string ("1h", "15m", "7d"). Default: "1h".
For “never expires”, use the exported sentinel:
import { NO_EXPIRATION } from "@warlock.js/auth";
jwt: { secret: env("JWT_SECRET"), expiresIn: NO_EXPIRATION, // resolves to "100y"}NO_EXPIRATION is "100y" — practically forever. Useful for service tokens; almost never right for end-user access tokens. In production, an access-token lifetime over 30 days logs a one-time warning; prefer a short lifetime with refresh tokens:
accessToken: { secret: env("JWT_SECRET"), expiresIn: "1h" },refreshToken: { enabled: true, secret: env("JWT_REFRESH_SECRET"), expiresIn: "7d" },accessToken.issuer / accessToken.audience — New in 5.53
Section titled “accessToken.issuer / accessToken.audience — New in 5.53”accessToken: { secret: env("JWT_SECRET"), issuer: "https://api.example.com", // default: unset audience: "web-app", // default: unset (string or string[])}When set, every access and refresh token this app signs carries the iss / aud claim, and every token it accepts must carry a matching one. Set them when several apps or services share a signing secret, so a token minted by one is refused by the others. Unset (the default) changes nothing.
Tokens signed before you set either value have no such claim and are refused, so every signed-in user signs in again once. Deploy the change when that is acceptable.
hashTokensAtRest — New in 5.53
Section titled “hashTokensAtRest — New in 5.53”hashTokensAtRest: true, // default: falseStores only the SHA-256 digest of each access and refresh token in access_tokens.token / refresh_tokens.token, never the token itself, so a copied table (a backup, a replica, a read-only SQL injection) cannot be replayed as a login. Turn it on for every new app.
- No migration: the digest goes in the existing
tokencolumn. - Lookups accept both forms, so rows issued before the switch keep working until they expire, and turning it off again signs no one out.
- A row loaded from the database no longer holds the raw token. The row
authService.createRefreshToken()/user.generateRefreshToken()returns exposes it asrow.plainToken;login()andcreateTokenPair()return the raw tokens as before. - Automatic cookie renewal keeps its short duplicate window by parking the new pair, encrypted, in the cache for that window. Without a shared cache driver, a duplicate renewal on another server inside the window answers
401instead of the same pair.
jwt.refresh.secret
Section titled “jwt.refresh.secret”Separate signing key for refresh tokens. Generated alongside JWT_SECRET by warlock jwt.generate. Keeping it distinct from jwt.secret prevents an access-token compromise from forging refresh tokens (and vice versa).
jwt.refresh.enabled
Section titled “jwt.refresh.enabled”Default: true. When false, login / createTokenPair return only accessToken.
jwt.refresh.expiresIn
Section titled “jwt.refresh.expiresIn”Refresh-token lifetime as a ms string. Default: "7d" — used both as the documented recommendation and as the runtime fallback when the value is omitted. To issue non-expiring refresh tokens, set expiresIn: NO_EXPIRATION (resolves to "100y").
jwt.refresh.rotation
Section titled “jwt.refresh.rotation”Default: true. When true, each successful refreshTokens(...) call revokes the old refresh token and issues a new one in the same family. The first re-use of a revoked token triggers family-wide revocation — the canonical JWT replay defense.
jwt.refresh.maxPerUser
Section titled “jwt.refresh.maxPerUser”Default: 5. Hard cap on simultaneous active refresh tokens per user. The oldest get revoked when the cap is hit. Lower = smaller revocation surface; higher = more devices a user can stay logged in on.
jwt.refresh.logoutWithoutToken
Section titled “jwt.refresh.logoutWithoutToken”Behavior when authService.logout(user) is called without a refresh token:
"revoke-all"(default) — revoke every refresh token for this user. Fail-safe."error"— throw. Forces the client to send the refresh token.
The default is right for most apps. If the client lost the refresh token, logout still works; the user has to log back in on every device.
password.salt
Section titled “password.salt”Default: 12. The bcrypt cost factor for hashPassword. Higher = more secure but slower per login. The default is a sane balance for 2026 hardware.
cookie.name / cookie.path — New in 5.12
Section titled “cookie.name / cookie.path — New in 5.12”cookie: { name: "access_token", // default path: "/", // default}The cookie name and Path attribute authService.setAuthCookie / clearAuthCookie use by default (a per-call options.name / options.path overrides either). HttpOnly, SameSite=Lax, and Secure outside development are not configurable here — they come from core’s secureCookieDefaults() floor. See Handle login and logout.
cookie.hostPrefix — New in 5.53
Section titled “cookie.hostPrefix — New in 5.53”cookie: { hostPrefix: true, // default: false}Writes the auth cookies as __Host-access_token / __Host-refresh_token. Browsers only accept a __Host- cookie that is Secure, has Path=/ and no Domain, so a sibling subdomain or a plain-HTTP page cannot plant or overwrite the session cookie. It needs cookie.path: "/" and no cookie.cookieDomain (nor a domain in http.cookies.options); a cookie write that breaks either rule throws, naming the setting to change.
While you switch, the unprefixed cookie is still read, so signed-in users stay signed in, and logout clears both names.
csrf.allowedOrigins — New in 5.12
Section titled “csrf.allowedOrigins — New in 5.12”csrf: { allowedOrigins: [], // default}Extra origins allowed on a cookie-authenticated unsafe-method (POST/PUT/PATCH/DELETE) request, on top of the request’s own origin. Only relevant when a route uses authMiddleware([], "cookie:<name>") — header-token auth and safe methods are never checked. See Protect routes → CSRF Origin check.
Reading config at runtime
Section titled “Reading config at runtime”Auth reads its config via @warlock.js/core’s config.key("auth..."). You don’t usually need to read it directly — but if you do:
import { config } from "@warlock.js/core";
const expiresIn = config.key("auth.jwt.expiresIn", "1h");const maxPerUser = config.key("auth.jwt.refresh.maxPerUser", 5);Related
Section titled “Related”- First protected route — the smallest end-to-end flow.
- Customize user type — multi-user-type setup.
- Manage tokens — rotation, family revocation, max-per-user in depth.