Skip to content

Configuration

Auth’s runtime config lives at src/config/auth.ts. It is shaped by the AuthConfigurations type — import it for IntelliSense.

src/config/auth.ts
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;

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.

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.

The signing algorithm passed to fast-jwt. Default: "HS256". Accepts any Algorithm value from fast-jwt. Most apps stay on the default.

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: true, // default: false

Stores 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 token column.
  • 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 as row.plainToken; login() and createTokenPair() 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 401 instead of the same pair.

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

Default: true. When false, login / createTokenPair return only accessToken.

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

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.

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.

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.

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: "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: 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: [], // 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.

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