@warlock.js/auth 5.30.0 → 5.31.0

package/llms-full.txt

@@ -59,10 +59,7 @@ import { defineConfig } from "@warlock.js/core";
 
 export default defineConfig({
   cli: {
-    commands: [
-      registerJWTSecretGeneratorCommand(),
-      registerAuthCleanupCommand(),
-    ],
+    commands: [registerJWTSecretGeneratorCommand(), registerAuthCleanupCommand()],
   },
   database: {
     migrations: authMigrations,
@@ -106,19 +103,19 @@ That is deliberate. `ms` answers `undefined` for a string it can't parse (`"30da
 
 Two values that look right and are not:
 
-- `expiresIn: 2592000` — a bare number. `ms` *formats* numbers instead of parsing them, so this is rejected; write `"30d"`.
+- `expiresIn: 2592000` — a bare number. `ms` _formats_ numbers instead of parsing them, so this is rejected; write `"30d"`.
 - `expiresIn: env("JWT_TTL")` where the variable is unset — resolves to `""` and is rejected. Give the env read a default: `env("JWT_TTL") || "1h"`.
 
 ## Pick a skill
 
-| If the task is about… | Load |
-| --- | --- |
-| Gating routes with `authMiddleware(allowedUserType)`, any-authenticated vs typed access | The `protect-routes` topic |
-| `authService.login(...)`, `attemptLogin`, full credentials-to-tokens flow + logout | The `handle-login-and-logout` topic |
-| Token lifecycle — `generateAccessToken`, `createRefreshToken`, rotation, family revocation, max-per-user | The `manage-tokens` topic |
-| Register a new user + issue tokens in one flow | The `register-user` topic |
-| Multi-user-type apps (`user`, `admin`, `client`), `config.auth.userType.<name>` mapping | The `customize-user-type` topic |
-| `warlock jwt.generate` + `warlock auth.cleanup` CLI commands | The `run-auth-commands` topic |
+| If the task is about…                                                                                    | Load                                |
+| -------------------------------------------------------------------------------------------------------- | ----------------------------------- |
+| Gating routes with `authMiddleware(allowedUserType)`, any-authenticated vs typed access                  | The `protect-routes` topic          |
+| `authService.login(...)`, `attemptLogin`, full credentials-to-tokens flow + logout                       | The `handle-login-and-logout` topic |
+| Token lifecycle — `generateAccessToken`, `createRefreshToken`, rotation, family revocation, max-per-user | The `manage-tokens` topic           |
+| Register a new user + issue tokens in one flow                                                           | The `register-user` topic           |
+| Multi-user-type apps (`user`, `admin`, `client`), `config.auth.userType.<name>` mapping                  | The `customize-user-type` topic     |
+| `warlock jwt.generate` + `warlock auth.cleanup` CLI commands                                             | The `run-auth-commands` topic       |
 
 ## Things NOT to do
 
@@ -137,7 +134,7 @@ description: 'Override the persisted AccessToken / RefreshToken models to add co
 
 # Customize token storage
 
-The package ships `AccessToken` and `RefreshToken` models and runs the whole token flow through their **named statics** — `issue`, `findByToken`, `activeFor`, `revokeAllFor`, etc. The auth service never references a column name directly; it resolves the *active* model from config. So you change token storage by **registering a subclass**, not by forking.
+The package ships `AccessToken` and `RefreshToken` models and runs the whole token flow through their **named statics** — `issue`, `findByToken`, `activeFor`, `revokeAllFor`, etc. The auth service never references a column name directly; it resolves the _active_ model from config. So you change token storage by **registering a subclass**, not by forking.
 
 Reach for this when you need an extra column on the token tables — the common case is a tenant key (`organization_id`) so tokens are partitioned per organization, or richer device metadata.
 
@@ -188,7 +185,12 @@ export class AppAccessToken extends AccessToken {
 Refresh tokens follow the same shape — extend `refreshTokenSchema`, and override `issue(user, token, options)` (`options` is `{ familyId, expiresAt, deviceInfo? }`) the same way, copying the base fields plus your column.
 
 ```ts title="src/app/auth/models/app-refresh-token.ts"
-import { RefreshToken, refreshTokenSchema, type Auth, type RefreshTokenIssueOptions } from "@warlock.js/auth";
+import {
+  RefreshToken,
+  refreshTokenSchema,
+  type Auth,
+  type RefreshTokenIssueOptions,
+} from "@warlock.js/auth";
 import { v } from "@warlock.js/seal";
 
 export class AppRefreshToken extends RefreshToken {
@@ -220,12 +222,12 @@ import { AppRefreshToken } from "app/auth/models/app-refresh-token";
 export default {
   userType: { user: User },
   accessToken: {
-    model: AppAccessToken,            // ← the override
+    model: AppAccessToken, // ← the override
     secret: env("JWT_SECRET"),
     expiresIn: "1h",
   },
   refreshToken: {
-    model: AppRefreshToken,           // ← the override
+    model: AppRefreshToken, // ← the override
     secret: env("JWT_REFRESH_SECRET"),
     expiresIn: "30d",
   },
@@ -246,7 +248,7 @@ See the `write-migration` topic of the `warlock-js-cascade` skill for the migrat
 
 ## Why all three — the strict-mode trap
 
-This is the failure people hit. Cascade's `strictMode: "strip"` **drops any field your schema doesn't declare** before the INSERT. So if you set `organization_id` in `issue()` but don't add it to the schema (step 1), the value is silently stripped, and a NOT-NULL `organization_id` column then **fails the INSERT**. The chain is: `issue()` sets it → the *schema* must declare it so it survives → the *migration* must create the column. All three, or nothing.
+This is the failure people hit. Cascade's `strictMode: "strip"` **drops any field your schema doesn't declare** before the INSERT. So if you set `organization_id` in `issue()` but don't add it to the schema (step 1), the value is silently stripped, and a NOT-NULL `organization_id` column then **fails the INSERT**. The chain is: `issue()` sets it → the _schema_ must declare it so it survives → the _migration_ must create the column. All three, or nothing.
 
 ## You do NOT need read-side scoping
 
@@ -256,23 +258,23 @@ Token lookups go by the unique `token` string (`findByToken`), which already uni
 
 Your subclass inherits and may override these statics — the service calls them, never raw queries:
 
-| Static | Role |
-| --- | --- |
-| `issue(user, token, …)` | persist a freshly-signed token (override to add columns) |
-| `findByToken(token)` | look a row up by its token string |
-| `findForUser(user, token)` | a user-scoped lookup (logout) |
-| `activeFor(user)` | active, unexpired sessions, newest-first |
-| `revokeAllFor(user)` / `revokeFamily(id)` | revoke a set, returning the revoked rows |
-| `enforceMax(user, max)` | cap concurrent refresh tokens |
-| `purgeExpired()` | delete expired rows (CLI cleanup) |
+| Static                                         | Role                                                     |
+| ---------------------------------------------- | -------------------------------------------------------- |
+| `issue(user, token, …)`                        | persist a freshly-signed token (override to add columns) |
+| `findByToken(token)`                           | look a row up by its token string                        |
+| `findForUser(user, token)`                     | a user-scoped lookup (logout)                            |
+| `activeFor(user)`                              | active, unexpired sessions, newest-first                 |
+| `revokeAllFor(user)` / `revokeFamily(id)`      | revoke a set, returning the revoked rows                 |
+| `enforceMax(user, max)`                        | cap concurrent refresh tokens                            |
+| `purgeExpired()`                               | delete expired rows (CLI cleanup)                        |
 | `findNeverExpiring()` / `purgeNeverExpiring()` | find/delete rows that can never expire (CLI remediation) |
 
 Plus two instance getters, both of which the route gate consults on every request:
 
-| Getter | Role |
-| --- | --- |
-| `isExpired` | whether the row's persisted expiry has passed — **the middleware rejects the request when this is `true`** |
-| `neverExpires` | whether nothing can ever retire the row (unusable `expires_at`, or a token with no `exp` claim) |
+| Getter         | Role                                                                                                       |
+| -------------- | ---------------------------------------------------------------------------------------------------------- |
+| `isExpired`    | whether the row's persisted expiry has passed — **the middleware rejects the request when this is `true`** |
+| `neverExpires` | whether nothing can ever retire the row (unusable `expires_at`, or a token with no `exp` claim)            |
 
 If you rename a column, override the statics **and these getters** so they map to your name — the service depends on the method, not the column.
 
@@ -287,7 +289,7 @@ If you rename a column, override the statics **and these getters** so they map t
 
 ## See also
 
-- The `customize-user-type` topic — multiple user *types* (a different axis from token *storage*).
+- The `customize-user-type` topic — multiple user _types_ (a different axis from token _storage_).
 - The `manage-tokens` topic — the token lifecycle your statics power.
 - The `define-model` topic of the `warlock-js-cascade` skill — extending models and schemas.
 
@@ -395,7 +397,9 @@ const dashboardController: RequestHandler = async ({ response }) => response.suc
 
 router.get("/account", userAccountController, { middleware: [authMiddleware("user")] });
 router.get("/admin/users", listUsersController, { middleware: [authMiddleware("admin")] });
-router.get("/back-office", backOfficeController, { middleware: [authMiddleware(["admin", "staff"])] });
+router.get("/back-office", backOfficeController, {
+  middleware: [authMiddleware(["admin", "staff"])],
+});
 router.get("/dashboard", dashboardController, { middleware: [authMiddleware([])] }); // any logged-in
 ```
 
@@ -686,13 +690,13 @@ authService.setAuthCookie(response, tokens.accessToken); // cookie session, or r
 
 ## Install
 
-| Method | Command | Installs |
-| --- | --- | --- |
-| Google | `warlock add auth-google` | `jose` |
-| Apple, LinkedIn | `warlock add auth-google` (or `npm install jose`) — there is no separate `auth-apple` / `auth-linkedin` feature yet | `jose` |
-| GitHub, Discord, Facebook, X | nothing — plain OAuth 2 over `fetch` | nothing |
-| Passkeys | `warlock add auth-passkeys` | `@simplewebauthn/server` (add `@simplewebauthn/browser` to your client bundle) |
-| Phone code | `warlock add notifications` + your own `sms`/`whatsapp` channel | nothing else. Auth ships no SMS/WhatsApp driver |
+| Method                       | Command                                                                                                             | Installs                                                                       |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| Google                       | `warlock add auth-google`                                                                                           | `jose`                                                                         |
+| Apple, LinkedIn              | `warlock add auth-google` (or `npm install jose`) — there is no separate `auth-apple` / `auth-linkedin` feature yet | `jose`                                                                         |
+| GitHub, Discord, Facebook, X | nothing — plain OAuth 2 over `fetch`                                                                                | nothing                                                                        |
+| Passkeys                     | `warlock add auth-passkeys`                                                                                         | `@simplewebauthn/server` (add `@simplewebauthn/browser` to your client bundle) |
+| Phone code                   | `warlock add notifications` + your own `sms`/`whatsapp` channel                                                     | nothing else. Auth ships no SMS/WhatsApp driver                                |
 
 The SDKs are optional peers, loaded with `import()` only when a method runs. If one is missing, the call throws `AuthProviderSdkMissingError` (500), and the message names the `warlock add` command. Run the migrations: `authMigrations` now includes `provider_accounts` and `passkey_credentials`, and `one_time_tokens` gained an `attempts` column.
 
@@ -870,17 +874,25 @@ passkeys: { rpID: "example.com", rpName: "Example", origin: "https://example.com
 
 ```ts
 // Register (logged in)
-router.post("/auth/passkeys/register/options", async ({ request, response }) =>
-  response.success(await generatePasskeyRegistrationOptions(request.locals.user)),
-  { middleware: [authMiddleware("user")] });
-router.post("/auth/passkeys/register", async ({ request, response }) => {
-  await verifyPasskeyRegistration(request, request.locals.user, request.input("credential"));
-  return response.success({ registered: true });
-}, { middleware: [authMiddleware("user")] });
+router.post(
+  "/auth/passkeys/register/options",
+  async ({ request, response }) =>
+    response.success(await generatePasskeyRegistrationOptions(request.locals.user)),
+  { middleware: [authMiddleware("user")] },
+);
+router.post(
+  "/auth/passkeys/register",
+  async ({ request, response }) => {
+    await verifyPasskeyRegistration(request, request.locals.user, request.input("credential"));
+    return response.success({ registered: true });
+  },
+  { middleware: [authMiddleware("user")] },
+);
 
 // Log in
 router.post("/auth/passkeys/login/options", async ({ response }) =>
-  response.success(await generatePasskeyAuthenticationOptions()));
+  response.success(await generatePasskeyAuthenticationOptions()),
+);
 router.post("/auth/passkeys/login", async ({ request, response }) => {
   const { tokens } = await verifyPasskeyAuthentication(request, request.input("credential"));
   authService.setAuthCookie(response, tokens.accessToken);
@@ -894,16 +906,23 @@ Browser:
 import { startAuthentication, startRegistration } from "@simplewebauthn/browser";
 
 const post = (url: string, body?: unknown) =>
-  fetch(url, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) })
-    .then((r) => r.json());
+  fetch(url, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  }).then((r) => r.json());
 
 // register
 const regOptions = await post("/auth/passkeys/register/options");
-await post("/auth/passkeys/register", { credential: await startRegistration({ optionsJSON: regOptions }) });
+await post("/auth/passkeys/register", {
+  credential: await startRegistration({ optionsJSON: regOptions }),
+});
 
 // log in
 const authOptions = await post("/auth/passkeys/login/options");
-await post("/auth/passkeys/login", { credential: await startAuthentication({ optionsJSON: authOptions }) });
+await post("/auth/passkeys/login", {
+  credential: await startAuthentication({ optionsJSON: authOptions }),
+});
 ```
 
 (Unwrap `response.success`'s envelope if your app wraps payloads.)
@@ -920,16 +939,26 @@ otp: { channel: "sms" /* or "whatsapp" */, phoneField: "phone", expiresIn: "5m",
 ```
 
 ```ts
-router.post("/auth/otp/request", async ({ request, response }) => {
-  await requestOtp(User, request.input("phone"), { channel: request.input("via") === "whatsapp" ? "whatsapp" : "sms" });
-  return response.success({ message: "If that number is registered, a code is on its way." });
-}, { middleware: [otpRequestThrottleMiddleware()] }); // 3 / 1h per phone + IP
-
-router.post("/auth/otp/verify", async ({ request, response }) => {
-  const { tokens } = await verifyOtp(User, request.input("phone"), request.input("code"));
-  authService.setAuthCookie(response, tokens.accessToken);
-  return response.success({ ok: true });
-}, { middleware: [otpVerifyThrottleMiddleware()] }); // 5 failures / 15m per phone + IP
+router.post(
+  "/auth/otp/request",
+  async ({ request, response }) => {
+    await requestOtp(User, request.input("phone"), {
+      channel: request.input("via") === "whatsapp" ? "whatsapp" : "sms",
+    });
+    return response.success({ message: "If that number is registered, a code is on its way." });
+  },
+  { middleware: [otpRequestThrottleMiddleware()] },
+); // 3 / 1h per phone + IP
+
+router.post(
+  "/auth/otp/verify",
+  async ({ request, response }) => {
+    const { tokens } = await verifyOtp(User, request.input("phone"), request.input("code"));
+    authService.setAuthCookie(response, tokens.accessToken);
+    return response.success({ ok: true });
+  },
+  { middleware: [otpVerifyThrottleMiddleware()] },
+); // 5 failures / 15m per phone + IP
 ```
 
 - Codes have 6 digits and are stored in `one_time_tokens` (purpose `otp`) as a salted HMAC keyed from your access-token secret, never as plain SHA-256, which is trivially reversible for 6 digits. A new request invalidates the previous code.
@@ -972,7 +1001,7 @@ type RefreshTokenOutput = { token: string; expiresAt: string };
 
 type TokenPair = {
   accessToken: AccessTokenOutput;
-  refreshToken?: RefreshTokenOutput;   // omitted if config.auth.refreshToken.enabled = false
+  refreshToken?: RefreshTokenOutput; // omitted if config.auth.refreshToken.enabled = false
 };
 ```
 
@@ -1047,7 +1076,7 @@ The family ties together "successive rotations of one session." In 5.19 it is al
 const sessions = await authService.getActiveSessions(user);
 
 for (const session of sessions) {
-  session.get("device_info");     // { userAgent, ip, deviceId? } if provided at login
+  session.get("device_info"); // { userAgent, ip, deviceId? } if provided at login
   session.get("created_at");
   session.get("expires_at");
 }
@@ -1187,41 +1216,50 @@ Nine task skills. Most apps need `auth-basics` + `protect-routes` + `handle-logi
 ### Foundations
 
 #### `auth-basics`
+
 Start here. The `Auth` base model, `authMiddleware` gate, `authService` (login/logout/refresh), AccessToken + RefreshToken persistence, multi-user-type support.
 
 ### The flows
 
 #### `handle-login-and-logout`
+
 `authService.login(Model, credentials, deviceInfo?)` — verify password, issue the token pair, fire events. `authService.logout(user, accessToken?, refreshToken?)` — revoke tokens. For your `POST /login` and `POST /logout` controllers.
 
 #### `register-user`
+
 Sign up a new user and issue the first token pair — `User.create({ ...password: await hashPassword(plain) })` then `authService.createTokenPair(user)`. For `POST /register`.
 
 #### `protect-routes`
+
 `authMiddleware` object and legacy overloads: typed/default hard gates, optional resolution, credential source, and page-local redirects. Sets `request.locals.user` + `request.decodedAccessToken` when a user resolves.
 
 ### Going deeper
 
 #### `manage-tokens`
+
 The token lifecycle — `generateAccessToken`, `createRefreshToken`, `createTokenPair`, `refreshTokens` (rotation + replay detection), `revokeAllTokens`, `revokeTokenFamily`, `cleanupExpiredTokens`, `getActiveSessions`. For custom login/registration, token revocation, "logout everywhere", and scheduled cleanup.
 
 #### `customize-user-type`
+
 Support multiple user types in one system — each `Auth` subclass overrides `userType`, `config.auth.userType.<slug>` maps the slug to a model class, `authMiddleware("admin")` / `authMiddleware(["admin", "staff"])` gates per type.
 
 #### `customize-token-storage`
+
 Override the persisted `AccessToken` / `RefreshToken` models to add columns (multi-tenant `organization_id`), rename, or change storage — extend the model + schema and register it under `config.auth.accessToken.model` / `config.auth.refreshToken.model`.
 
 #### `throttle-login-attempts`
+
 Brute-force / credential-stuffing protection — `loginThrottleMiddleware()` counts only failed logins, resets on success, locks per-account + per-IP after a threshold, and rejects pre-controller with 429. Cache-backed, fails open on a cache outage.
 
 #### `run-auth-commands`
+
 Two CLI commands — `warlock jwt.generate` (strong JWT secret → `.env`) and `warlock auth.cleanup` (remove expired refresh tokens). Register via `registerJWTSecretGeneratorCommand()` and `registerAuthCleanupCommand()`.
 
 ## What this package deliberately doesn't do
 
 - **Session-cookie auth.** It's JWT/token-based. If you need server-side sessions, this isn't it.
 - **OAuth / social login / SSO.** No provider adapters here — wire those at the controller layer and create the user through this package's models.
-- **Authorization / roles / permissions (RBAC).** It authenticates (who you are) and gates by user *type*, not fine-grained permissions. Build RBAC on top.
+- **Authorization / roles / permissions (RBAC).** It authenticates (who you are) and gates by user _type_, not fine-grained permissions. Build RBAC on top.
 - **Standalone use.** It depends on `@warlock.js/core` for routing, models (Cascade), and config.
 
 ## See also
@@ -1299,21 +1337,21 @@ The user is loaded via `Model.find(decodedToken.id)` against the `config.auth.us
 
 A token passes three separate checks, in order — a token can fail any one of them while satisfying the other two:
 
-1. **The JWT verifies** — signature, algorithm, `tokenType`, and (since 4.12.0) the presence of an `exp` claim that has not passed. A token with *no* `exp` is rejected: there is no deadline to check, so it would otherwise verify indefinitely.
+1. **The JWT verifies** — signature, algorithm, `tokenType`, and (since 4.12.0) the presence of an `exp` claim that has not passed. A token with _no_ `exp` is rejected: there is no deadline to check, so it would otherwise verify indefinitely.
 2. **The access-token row still exists** — deleting it (logout) invalidates the token immediately, before its JWT expiry.
 3. **The row's own `expires_at` has not passed** (since 4.12.0). The database is the authority on the session: a row whose expiry has elapsed is rejected and deleted, even if the JWT itself is still within its lifetime. A row with a missing or unparseable `expires_at` is treated as expired, not as never-expiring.
 
 Missing or invalid credentials return 401; an authenticated disallowed user type returns 403:
 
-| Error code | When |
-| --- | --- |
-| `MissingAccessToken` | No credential at the configured source |
+| Error code           | When                                                                                                                          |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `MissingAccessToken` | No credential at the configured source                                                                                        |
 | `InvalidAccessToken` | Token doesn't verify (signature, missing/passed `exp`, wrong token type), has no DB row, or the row's `expires_at` has passed |
-| `Unauthorized` | Token valid but user-type isn't in the allowed list (403) |
+| `Unauthorized`       | Token valid but user-type isn't in the allowed list (403)                                                                     |
 
 ## Page routes: redirect to login instead of the JSON 401
 
-By default every auth failure — API or page — returns the JSON `401` above. That's right for an API client, but a logged-out human who *navigates* to a guarded page route gets a raw JSON error blob instead of a login screen.
+By default every auth failure — API or page — returns the JSON `401` above. That's right for an API client, but a logged-out human who _navigates_ to a guarded page route gets a raw JSON error blob instead of a login screen.
 
 Opt into a redirect with `auth.pageAuth` (5.8+). Set `loginPath` and a guarded **page** route (`route.isPage`) that a logged-out browser hits redirects to `loginPath?returnUrl=<original path>` instead of returning the JSON 401:
 
@@ -1323,7 +1361,7 @@ import { User } from "app/users/models/user/user.model";
 export default {
   userType: { user: User },
   pageAuth: {
-    loginPath: "/login",        // set this to turn the redirect on
+    loginPath: "/login", // set this to turn the redirect on
     returnUrlParam: "returnUrl", // optional, this is the default
   },
 };
@@ -1355,7 +1393,7 @@ declare module "@warlock.js/auth" {
 import { type RequestHandler } from "@warlock.js/core";
 
 export const accountController: RequestHandler = async ({ request, response }) => {
-  const user = request.locals.user!;          // typed via the RequestUser augmentation above
+  const user = request.locals.user!; // typed via the RequestUser augmentation above
   return response.success({
     id: user.id,
     email: user.get("email"),
@@ -1381,9 +1419,14 @@ Every route inside the group is gated — the group's `middleware` array applies
 Use `optional: true` in the object form when a public route should receive a verified user when one is present. Missing or invalid credentials continue anonymously; a hard gate remains the default.
 
 ```ts
-middleware: [authMiddleware({ source: "header", optional: true })]
+middleware: [authMiddleware({ source: "header", optional: true })];
 ```
 
+`authMiddleware()` marks itself as an auth guard for `warlock dev`'s
+unguarded-route warning (`isAuthGuardMiddleware()` from `@warlock.js/core`);
+the optional form does not count, so a mutating route behind only optional
+auth still needs `public: true` to stay quiet.
+
 ## Automatic cookie renewal
 
 Add `refresh: { source: "cookie", key: "refresh_token", overlapMs?: 5000 }`
@@ -1393,6 +1436,7 @@ through `authService.setAuthCookie`; it never replays a handler. `overlapMs` is
 clamped to 0–10,000 ms (default 5,000). Only the exact immediate successor is
 tolerated during that window. The legacy `refreshTokens` API stays strict; a
 later old-token presentation revokes its family.
+
 ## Custom error responses
 
 The middleware uses the framework's `response.unauthorized({...})` shape. To override the response globally, hook the framework's error transformer to remap `AuthErrorCodes.*` codes.
@@ -1417,8 +1461,9 @@ import { User } from "app/users/models/user/user.model";
 
 const articlesController: RequestHandler = async ({ request, response }) => {
   // Who-may-act-on-whom: an ABAC policy on top of the RBAC grant
-  definePolicy("users.create", (actor, target, ctx) =>
-    ctx.hasRole("superAdmin") || (target as User).userType === "teacher",
+  definePolicy(
+    "users.create",
+    (actor, target, ctx) => ctx.hasRole("superAdmin") || (target as User).userType === "teacher",
   );
 
   if (await can(request.locals.user!, "users.create", { resource: request.body })) {
@@ -1429,10 +1474,12 @@ const articlesController: RequestHandler = async ({ request, response }) => {
 };
 
 // Permission-based route gate, in place of a user-type gate
-router.post("/articles", articlesController, { middleware: [authMiddleware([]), gate("articles.create")] });
+router.post("/articles", articlesController, {
+  middleware: [authMiddleware([]), gate("articles.create")],
+});
 ```
 
-Use `authMiddleware` to establish *who the caller is*, and `access` to decide *what they may do*. They compose — `access` reads the user `authMiddleware` put on the request.
+Use `authMiddleware` to establish _who the caller is_, and `access` to decide _what they may do_. They compose — `access` reads the user `authMiddleware` put on the request.
 
 ## Cookie credentials
 
@@ -1448,7 +1495,7 @@ A route is header-only or cookie-only, never both — `tokenFrom` accepts exactl
 
 ### Writing and clearing the cookie: `authService.setAuthCookie` / `clearAuthCookie`
 
-Reading a cookie is opt-in per route (above); *writing* one is a separate, explicit step your login/logout controller calls — `authService.login`/`logout` never set cookies implicitly, so upgrading never starts emitting `Set-Cookie` for an existing bearer-only app.
+Reading a cookie is opt-in per route (above); _writing_ one is a separate, explicit step your login/logout controller calls — `authService.login`/`logout` never set cookies implicitly, so upgrading never starts emitting `Set-Cookie` for an existing bearer-only app.
 
 ```ts
 import { type RequestHandler } from "@warlock.js/core";
@@ -1594,7 +1641,7 @@ export const registerController: RequestHandler = async ({ request, response })
 
   // 4. Respond
   return response.successCreate({
-    user,         // shape via static toJsonColumns / static resource
+    user, // shape via static toJsonColumns / static resource
     tokens,
   });
 };
@@ -1609,7 +1656,7 @@ Always pass `hashPassword(plain)` — never store the plain password. The `hashP
 ```ts
 import { hashPassword, verifyPassword } from "@warlock.js/core";
 
-const hash = await hashPassword("plaintext");      // store this
+const hash = await hashPassword("plaintext"); // store this
 const ok = await verifyPassword("plaintext", hash); // compare on login
 ```
 
@@ -1623,7 +1670,7 @@ Define the password as `v.string().strongPassword(12)` (or similar) in your User
 const userSchema = v.object({
   email: v.string().email(),
   name: v.string().min(2).max(120),
-  password: v.string().strongPassword(12),   // 12+ chars, upper/lower/digit/symbol
+  password: v.string().strongPassword(12), // 12+ chars, upper/lower/digit/symbol
   // status, role, etc.
 });
 ```
@@ -1635,7 +1682,7 @@ But **don't return the password in the public output**:
 export class User extends Model<UserSchema> {
   public static table = "users";
   public static schema = userSchema;
-  public static toJsonColumns = ["id", "email", "name", "created_at"];   // omit password
+  public static toJsonColumns = ["id", "email", "name", "created_at"]; // omit password
 }
 ```
 
@@ -1786,7 +1833,7 @@ Register with `registerAuthPurgeNeverExpiringCommand()`.
 
 Finds every token row that **can never retire itself**, on two independent signals: an `expires_at` that is missing or unparseable, and a stored token carrying no `exp` claim. It reports `id` / `user_id` / `user_type` / `expires_at` per row — never the token string, which is a live credential until the row is deleted — and then deletes them. Affected users must log in again.
 
-**This is not a substitute for `auth.cleanup`, and `auth.cleanup` is not a substitute for it.** Cleanup selects `expires_at < now`; an `Invalid Date` compares `false` against *every* date, so such a row satisfies neither `< now` nor `> now` and no date predicate can ever reach it. The "no `exp` claim" signal is not in a column at all — it is inside the JWT.
+**This is not a substitute for `auth.cleanup`, and `auth.cleanup` is not a substitute for it.** Cleanup selects `expires_at < now`; an `Invalid Date` compares `false` against _every_ date, so such a row satisfies neither `< now` nor `> now` and no date predicate can ever reach it. The "no `exp` claim" signal is not in a column at all — it is inside the JWT.
 
 Run it once after upgrading to 4.12.0 **if any deployment ever ran an `expiresIn` that `ms` could not parse** (`"30dayz"`, `"0d"`, `""`, a bare number). Those configurations minted tokens that verify forever. It is safe to run when unaffected — it reports nothing and deletes nothing.
 
@@ -1863,7 +1910,7 @@ description: 'Brute-force / credential-stuffing protection via `loginThrottleMid
 
 `loginThrottleMiddleware(options?)` returns a Warlock middleware that defends the login (and refresh / password-reset) routes against brute-force and credential-stuffing — without punishing a user who fat-fingers a password then gets it right.
 
-The trick that makes it different from a plain rate limiter: it's **failure-aware**. It hooks the response *after* your controller runs (`response.onSent`), counts only the attempts that actually failed, and **clears the counter the moment a login succeeds**. A generic request limiter can't do that — it runs before the controller and counts every hit, success or not.
+The trick that makes it different from a plain rate limiter: it's **failure-aware**. It hooks the response _after_ your controller runs (`response.onSent`), counts only the attempts that actually failed, and **clears the counter the moment a login succeeds**. A generic request limiter can't do that — it runs before the controller and counts every hit, success or not.
 
 ## The shortest version
 
@@ -1879,6 +1926,35 @@ That's the whole feature for most apps. Defaults: **5** failed attempts within a
 
 > **Heads-up — account-lockout is a DoS surface.** Because the default tracks per-`email`, an attacker who knows a victim's address can lock them out by spamming failed logins. The per-IP counter mitigates it (the attacker's own IP trips too); for purely anonymous endpoints prefer `by: ["ip"]`, and for high-value accounts consider a CAPTCHA step over a hard lock. See [Gotchas](#gotchas).
 
+## What new apps get by default
+
+The auth package registers no routes, so throttles apply where you attach them.
+A 5.31 `create-warlock` app already attaches `loginThrottleMiddleware()` to
+`/auth/login`, `tokenIssueThrottleMiddleware()` to `/auth/forgot-password`,
+`tokenConsumeThrottleMiddleware()` to `/auth/reset-password` and a 30/minute
+route `rateLimit` to `/auth/refresh-token`, all marked `public: true`. Every
+route also sits under core's global limit (60 requests/minute per IP). Older
+apps add the middleware to their own `src/app/auth/routes.ts`:
+
+```ts
+import { tokenConsumeThrottleMiddleware, tokenIssueThrottleMiddleware } from "@warlock.js/auth";
+import { router, type RequestHandler } from "@warlock.js/core";
+
+const forgotPasswordController: RequestHandler = async ({ response }) =>
+  response.success({ sent: true });
+const resetPasswordController: RequestHandler = async ({ response }) =>
+  response.success({ reset: true });
+
+router.post("/auth/forgot-password", forgotPasswordController, {
+  public: true,
+  middleware: [tokenIssueThrottleMiddleware()],
+});
+router.post("/auth/reset-password", resetPasswordController, {
+  public: true,
+  middleware: [tokenConsumeThrottleMiddleware()],
+});
+```
+
 ## How it behaves
 
 1. **Before the controller** — if the account or the IP is currently locked, it short-circuits with `429` and never touches the database or the bcrypt verify (this is also what neutralises the CPU-DoS angle of brute-forcing). The body carries `AuthErrorCodes.TooManyAttempts` (`EC004`).
@@ -1890,10 +1966,10 @@ Per-account tracking stops a password-spray against one user from many IPs; per-
 
 ```ts
 loginThrottleMiddleware({
-  max: 5,                 // failures allowed in the window before lockout
-  window: "15m",          // counting window — ms-format string or seconds (number)
+  max: 5, // failures allowed in the window before lockout
+  window: "15m", // counting window — ms-format string or seconds (number)
   lockoutDuration: "15m", // how long the lock lasts once tripped
-  by: ["email", "ip"],    // identifiers tracked, each independently
+  by: ["email", "ip"], // identifiers tracked, each independently
   identifierKey: "email", // which credential field is the account key
   errorMessage: "Too many attempts. Try again later.",
 });
@@ -1911,16 +1987,16 @@ loginThrottleMiddleware({
 });
 ```
 
-| Option | Default | Purpose |
-| --- | --- | --- |
-| `max` | `5` | Failures within the window before lockout |
-| `window` | `"15m"` | Counting window (`ms`-string or seconds) |
-| `lockoutDuration` | `"15m"` | Lock TTL once tripped |
-| `by` | `["email", "ip"]` | Identifiers tracked independently |
-| `identifierKey` | `"email"` | Credential field used as the account key |
-| `errorMessage` | i18n `auth.errors.tooManyAttempts` | 429 message override |
-| `isFailure` | `(res) => !res.isOk` | What counts as a failed attempt |
-| `identify` | built-in email + ip extraction | Custom identifier list |
+| Option            | Default                            | Purpose                                   |
+| ----------------- | ---------------------------------- | ----------------------------------------- |
+| `max`             | `5`                                | Failures within the window before lockout |
+| `window`          | `"15m"`                            | Counting window (`ms`-string or seconds)  |
+| `lockoutDuration` | `"15m"`                            | Lock TTL once tripped                     |
+| `by`              | `["email", "ip"]`                  | Identifiers tracked independently         |
+| `identifierKey`   | `"email"`                          | Credential field used as the account key  |
+| `errorMessage`    | i18n `auth.errors.tooManyAttempts` | 429 message override                      |
+| `isFailure`       | `(res) => !res.isOk`               | What counts as a failed attempt           |
+| `identify`        | built-in email + ip extraction     | Custom identifier list                    |
 
 ## The 429 response
 
@@ -1948,20 +2024,20 @@ router.post("/auth/forgot-password", forgotController, {
 
 ## When to use this vs core's `rateLimit`
 
-| | `loginThrottleMiddleware` (auth) | `middleware.rateLimit` (core) |
-| --- | --- | --- |
-| Counts | only **failed** logins | **every** request |
-| Resets on a successful login | yes | no |
-| Locks per account / per IP | yes | per key (default IP) |
-| Storage | `@warlock.js/cache` (shared across replicas) | in-process map |
+|                              | `loginThrottleMiddleware` (auth)             | `middleware.rateLimit` (core) |
+| ---------------------------- | -------------------------------------------- | ----------------------------- |
+| Counts                       | only **failed** logins                       | **every** request             |
+| Resets on a successful login | yes                                          | no                            |
+| Locks per account / per IP   | yes                                          | per key (default IP)          |
+| Storage                      | `@warlock.js/cache` (shared across replicas) | in-process map                |
 
-They compose. For a hard ceiling on request volume *and* failure-aware account lockout, stack both: `middleware: [middleware.rateLimit({ max: 30, duration: 60_000 }), loginThrottleMiddleware()]`.
+They compose. For a hard ceiling on request volume _and_ failure-aware account lockout, stack both: `middleware: [middleware.rateLimit({ max: 30, duration: 60_000 }), loginThrottleMiddleware()]`.
 
 ## Gotchas
 
 - **Needs an initialised cache driver.** Storage is `@warlock.js/cache` (a peer dep, transitively present via core). If the driver isn't configured at runtime, the middleware **fails open** — it logs and lets the request through, because a throttle outage must never become an auth outage. That also means: no cache, no protection. Verify your cache config in production.
 - **Account lockout can be weaponised.** An attacker who knows a victim's email can lock them out by spamming failures. The per-IP counter mitigates this (the attacker's IP locks too), but for purely anonymous endpoints prefer `by: ["ip"]`. For high-value accounts, consider a CAPTCHA step instead of a hard lock.
-- **Counts are atomic and exact across servers (redis/pg).** Each failure does a create-only `cache.set(key, 0, { ttl: window })` (only the first failure opens the window and sets the TTL) followed by an atomic `cache.increment(key)`, so concurrent failures on different servers are never lost. The memory cache driver is per-process — counts and locks are then per-process, so use redis/pg when running more than one instance.
+- **Counts are atomic and exact across servers (redis/pg).** Each failure does a create-only `cache.set(key, 0, { ttl: window })` (only the first failure opens the window and sets the TTL) followed by an atomic `cache.increment(key, 1, { ttl: window })`, so concurrent failures on different servers are never lost. Passing the TTL on the increment also expires a counter recreated after its seed expires, without extending an existing window. The memory cache driver is per-process — counts and locks are then per-process, so use redis/pg when running more than one instance.
 - **Account and IP keys are hashed.** The built-in extractor keys both by an HMAC of the trimmed, lower-cased value (`email.<hmac>`, `ip.<hmac>`), keyed from `auth.accessToken.secret`, so cache logs never show the address or IP and a list of known emails cannot reverse the key. Without a configured secret it falls back to SHA-256. A custom `identify` is used as is — hash personal values yourself (`throttleIdentifierHash(kind, value)` is exported).
 - **Fixed window, not sliding.** The window is anchored at the first failure and does not extend on each subsequent one — predictable lockout timing. The lock key is independent and always lasts `lockoutDuration`: the lock stores its own deadline, so even a sliding-expiry driver (`memoryExtended`) cannot extend it.
 - **Needs a real cache driver.** The `null` driver stores nothing, so the throttle never locks; it warns once when that happens. On Redis, any version from 6 works.
@@ -2073,10 +2149,10 @@ router.post("/auth/reset-password", resetPasswordController, {
 
 Both presets wrap `loginThrottleMiddleware` and accept its options:
 
-| Preset | Tracks | Counts | Default |
-| --- | --- | --- | --- |
-| `tokenIssueThrottleMiddleware` | email + IP | **every** request (a reset request's success is the anti-enumeration answer, so failure-aware counting would never trip) | 3 / 1h, 1h lock |
-| `tokenConsumeThrottleMiddleware` | IP | failures only, cleared on success | 10 / 15m, 15m lock |
+| Preset                           | Tracks     | Counts                                                                                                                   | Default            |
+| -------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------ |
+| `tokenIssueThrottleMiddleware`   | email + IP | **every** request (a reset request's success is the anti-enumeration answer, so failure-aware counting would never trip) | 3 / 1h, 1h lock    |
+| `tokenConsumeThrottleMiddleware` | IP         | failures only, cleared on success                                                                                        | 10 / 15m, 15m lock |
 
 ## Configuration (`src/config/auth.ts`)
 
@@ -2094,7 +2170,9 @@ const authConfigurations: AuthConfigurations = {
     identifierField: "email",
     url: (token) => `${env("APP_URL")}/reset-password?token=${token}`,
     notification: myResetNotification,
-    setPassword: async (user, plain) => { /* optional */ },
+    setPassword: async (user, plain) => {
+      /* optional */
+    },
   },
   oneTimeToken: { model: AppOneTimeToken }, // optional model override
 };