Warlock Auth

JWT authentication for Warlock.js applications — a base Auth model your user types extend, an authMiddleware route gate, an authService for login / logout / refresh (with refresh-token rotation + replay detection), persisted access + refresh tokens, multi-user-type support, lifecycle events, brute-force throttling, and three CLI commands.

Installation

yarn add @warlock.js/auth

@warlock.js/auth is coupled to @warlock.js/core — install it inside a Warlock project.

Server-only

@warlock.js/auth's entire runtime surface is server-only — its package.json declares "warlock": { "environment": "server" }. @warlock.js/web's build treats this as a boundary: app client code cannot value-import this package (type-only imports are still allowed), while server loaders/controllers/modules can import it freely.

Configure

import { type AuthConfigurations } from "@warlock.js/auth";
import { env } from "@warlock.js/core";
import { User } from "app/users/models/user";

const authConfigurations: AuthConfigurations = {
  userType: { user: User },
  accessToken: {
    secret: env("JWT_SECRET"),
    expiresIn: "1h",
  },
  refreshToken: {
    secret: env("JWT_REFRESH_SECRET"),
    expiresIn: "30d",
    rotation: true,
  },
};

export default authConfigurations;

The legacy jwt: { secret, expiresIn, refresh: {…} } block is still honored (with a deprecation warning), but prefer the accessToken / refreshToken blocks.

expiresIn must be a duration string ms parses to a positive value ("1h", "30 days", NO_EXPIRATION); anything else throws naming the key on the first token issue, rather than signing a token with no expiry.

A token is only accepted while both its own exp claim and its stored expires_at are in the future — a JWT with no exp at all is rejected outright, since a verifier with no deadline to check succeeds forever. If any deployment ran a pre-4.12.0 version with an invalid expiresIn, tokens issued then may never expire and are still live: run warlock auth.purge-never-expiring --dry-run to find them. See the 4.12.0 entry in CHANGELOG.md.

Documentation

Task-focused guides live under skills/:

• overview — what the package does and when to reach for it
• auth-basics — the Auth model, middleware, and service
• handle-login-and-logout — issue and revoke tokens
• register-user — sign up + first token pair
• protect-routes — gate routes with authMiddleware
• manage-tokens — the full token lifecycle (rotation, revocation, cleanup)
• customize-user-type — multiple user types in one system
• customize-token-storage — override the token models (multi-tenant columns, custom storage)
• throttle-login-attempts — brute-force protection via loginThrottleMiddleware
• verify-email-and-reset-password — email verification, password reset, requireVerifiedEmail
• login-with-providers — Google, passkeys and phone one-time codes, all ending in completeLogin
• run-auth-commands — the bundled CLI commands

Generate the JWT secret

Register the command in warlock.config.ts:

import { registerJWTSecretGeneratorCommand } from "@warlock.js/auth";
import { defineConfig } from "@warlock.js/core";

export default defineConfig({
  cli: {
    commands: [registerJWTSecretGeneratorCommand()],
  },
});

Then run:

warlock jwt.generate

It generates cryptographically-strong JWT_SECRET and JWT_REFRESH_SECRET values and writes them to your .env file. Existing values are left untouched, so it's safe to re-run.

License

MIT © Hasan Zohdy