@warlock.js/auth 5.29.0 → 5.31.0

package/package.json

@@ -12,13 +12,13 @@
     "ms": "^2.1.3"
   },
   "peerDependencies": {
-    "@warlock.js/fs": "5.29.0",
-    "@warlock.js/cache": "5.29.0",
-    "@warlock.js/cascade": "5.29.0",
-    "@warlock.js/core": "5.29.0",
-    "@warlock.js/logger": "5.29.0",
-    "@warlock.js/seal": "5.29.0",
-    "@warlock.js/notifications": "5.29.0",
+    "@warlock.js/fs": "5.31.0",
+    "@warlock.js/cache": "5.31.0",
+    "@warlock.js/cascade": "5.31.0",
+    "@warlock.js/core": "5.31.0",
+    "@warlock.js/logger": "5.31.0",
+    "@warlock.js/seal": "5.31.0",
+    "@warlock.js/notifications": "5.31.0",
     "@simplewebauthn/server": "^13.1.0",
     "jose": "^6.1.0"
   },
@@ -35,7 +35,8 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/warlockjs/auth"
+    "url": "git+https://github.com/warlockjs/framework.git",
+    "directory": "packages/auth"
   },
   "keywords": [
     "nodejs",
@@ -47,7 +48,7 @@
   ],
   "author": "hassanzohdy",
   "license": "MIT",
-  "version": "5.29.0",
+  "version": "5.31.0",
   "type": "module",
   "main": "./esm/index.mjs",
   "module": "./esm/index.mjs",

package/skills/auth-basics/SKILL.md

@@ -51,10 +51,7 @@ import { defineConfig } from "@warlock.js/core";
 
 export default defineConfig({
   cli: {
-    commands: [
-      registerJWTSecretGeneratorCommand(),
-      registerAuthCleanupCommand(),
-    ],
+    commands: [registerJWTSecretGeneratorCommand(), registerAuthCleanupCommand()],
   },
   database: {
     migrations: authMigrations,
@@ -98,19 +95,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
 

package/skills/customize-token-storage/SKILL.md

@@ -5,7 +5,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.
 
@@ -56,7 +56,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 {
@@ -88,12 +93,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",
   },
@@ -114,7 +119,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
 
@@ -124,23 +129,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.
 
@@ -155,6 +160,6 @@ 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.

package/skills/customize-user-type/SKILL.md

@@ -99,7 +99,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
 ```
 

package/skills/index.md

@@ -1,11 +1,13 @@
 ---
-description: "JWT authentication for Warlock apps: login/logout, refresh-token rotation, protected routes, multiple user types. Exports `Auth`, `authService`, `authMiddleware`, `authEvents`, `currentUser`, `loginThrottleMiddleware`, `requireVerifiedEmail`, `GoogleProvider`, `AuthErrorCodes`. Use for: \"log a user in and issue tokens\", \"protect this route\", \"add an admin user type\", \"rate-limit login attempts\", \"verify email / reset password\", \"sign in with Google\". Not this package: general route middleware lives in @warlock.js/core; request-body validation is @warlock.js/seal."
+description: 'JWT authentication for Warlock apps: login/logout, refresh-token rotation, protected routes, multiple user types. Exports `Auth`, `authService`, `authMiddleware`, `authEvents`, `currentUser`, `loginThrottleMiddleware`, `requireVerifiedEmail`, `GoogleProvider`, `AuthErrorCodes`. Use for: "log a user in and issue tokens", "protect this route", "add an admin user type", "rate-limit login attempts", "verify email / reset password", "sign in with Google". Not this package: general route middleware lives in @warlock.js/core; request-body validation is @warlock.js/seal.'
 ---
+
 # @warlock.js/auth
 
 A user model extends the `Auth` base model and declares a `userType`. `authService.login(Model, credentials)` verifies the password and issues persisted access + refresh tokens; `authMiddleware("user")` gates routes per type. Refresh tokens rotate within a token family, with replay detection. Server-only, and requires `@warlock.js/core`.
 
 ## The 80% path
+
 1. Orient with `overview.md`, then `auth-basics.md` for the shape of config and models.
 2. Extend `Auth` for your user model: `customize-user-type.md`, `register-user.md`.
 3. Log in / out: `handle-login-and-logout.md`; token lifecycle: `manage-tokens.md`.
@@ -14,6 +16,7 @@ A user model extends the `Auth` base model and declares a `userType`. `authServi
 6. Social sign-in: `login-with-providers.md`; CLI (JWT secret, token cleanup): `run-auth-commands.md`.
 
 ## Conventions and pitfalls
+
 - Tokens are persisted rows, not stateless JWTs alone; revoking a family invalidates its refresh and access rows.
 - `authMiddleware()` with no argument resolves the configured default user type. Be explicit when an app has several.
 - Not for session-cookie auth; this is JWT-based.

package/skills/login-with-providers/SKILL.md

@@ -16,13 +16,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.
 
@@ -200,17 +200,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);
@@ -224,16 +232,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.)
@@ -250,16 +265,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.

package/skills/manage-tokens/SKILL.md

@@ -15,7 +15,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
 };
 ```
 
@@ -90,7 +90,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");
 }

package/skills/overview/SKILL.md

@@ -30,41 +30,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

package/skills/protect-routes/SKILL.md

@@ -64,21 +64,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:
 
@@ -88,7 +88,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
   },
 };
@@ -120,7 +120,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"),
@@ -146,9 +146,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 }`
@@ -158,6 +163,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.
@@ -182,8 +188,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 })) {
@@ -194,10 +201,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
 
@@ -213,7 +222,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";

package/skills/register-user/SKILL.md

@@ -52,7 +52,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,
   });
 };
@@ -67,7 +67,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
 ```
 
@@ -81,7 +81,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.
 });
 ```
@@ -93,7 +93,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
 }
 ```
 

package/skills/run-auth-commands/SKILL.md

@@ -93,7 +93,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.