@warlock.js/auth 5.23.2 → 5.25.0

package/skills/register-user/SKILL.md

@@ -1,147 +1,147 @@
----
-name: register-user
-description: 'Sign up a new user and issue the initial token pair — User.create({...password: await hashPassword(plain)}) then authService.createTokenPair(user). Triggers: `User.create`, `hashPassword`, `verifyPassword`, `authService.createTokenPair`, `toJsonColumns`, `strongPassword`, `authEvents`; "build a register endpoint", "POST /register controller", "sign up a new user", "hash password on signup", "email verification flow"; typical import `import { authService } from "@warlock.js/auth"; import { hashPassword } from "@warlock.js/core"`. Skip: login — `@warlock.js/auth/handle-login-and-logout/SKILL.md`; token internals — `@warlock.js/auth/manage-tokens/SKILL.md`; competing libs `bcrypt`, `bcryptjs`, `argon2`.'
----
-
-# Register-and-issue-tokens flow
-
-Two-step on the server: create the user (with hashed password), then issue tokens. Cascade handles the persistence; `authService` handles the tokens.
-
-```ts title="src/app/users/models/user/user.model.ts"
-import { Auth } from "@warlock.js/auth";
-import { RegisterModel } from "@warlock.js/cascade";
-
-@RegisterModel()
-export class User extends Auth {
-  public static table = "users";
-
-  public get userType(): string {
-    return "user";
-  }
-}
-```
-
-## The minimal shape
-
-```ts
-import { authService } from "@warlock.js/auth";
-import { hashPassword, type RequestHandler } from "@warlock.js/core";
-import { User } from "app/users/models/user/user.model";
-
-export const registerController: RequestHandler = async ({ request, response }) => {
-  const { email, password, name } = request.all();
-
-  // 1. Check duplicates
-  const existing = await User.first({ email });
-  if (existing) {
-    return response.conflict({ error: "Email already registered" });
-  }
-
-  // 2. Create the user with hashed password
-  const user = await User.create({
-    email,
-    name,
-    password: await hashPassword(password),
-  });
-
-  // 3. Issue tokens
-  const tokens = await authService.createTokenPair(user, {
-    userAgent: request.header("user-agent"),
-    ip: request.ip,
-  });
-
-  // 4. Respond
-  return response.successCreate({
-    user,         // shape via static toJsonColumns / static resource
-    tokens,
-  });
-};
-```
-
-That's the whole flow. `User.create({...})` runs the schema validation (including `.email()`, `.min()`, etc. on each field), so you don't need a separate validation pass — see [`@warlock.js/seal/handle-seal-errors/SKILL.md`](@warlock.js/seal/handle-seal-errors/SKILL.md) for catching validation failures.
-
-## Hash the password on the way in
-
-Always pass `hashPassword(plain)` — never store the plain password. The `hashPassword` helper is `bcrypt`-based and async; the cost factor matches the framework default.
-
-```ts
-import { hashPassword, verifyPassword } from "@warlock.js/core";
-
-const hash = await hashPassword("plaintext");      // store this
-const ok = await verifyPassword("plaintext", hash); // compare on login
-```
-
-`authService.attemptLogin` already calls `verifyPassword` against the stored hash — you don't compare passwords manually.
-
-## Schema enforcement
-
-Define the password as `v.string().strongPassword(12)` (or similar) in your User schema so weak passwords are rejected at `create()` time:
-
-```ts
-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
-  // status, role, etc.
-});
-```
-
-But **don't return the password in the public output**:
-
-```ts
-@RegisterModel()
-export class User extends Model<UserSchema> {
-  public static table = "users";
-  public static schema = userSchema;
-  public static toJsonColumns = ["id", "email", "name", "created_at"];   // omit password
-}
-```
-
-Without this, `JSON.stringify(user)` in your response leaks the hash.
-
-## Email verification flow (extending registration)
-
-Since 5.13 auth ships this. Declare `emailVerifiedAt: v.date().optional()` on the schema, then send the verification after creating the user:
-
-```ts
-import { authService, sendEmailVerification } from "@warlock.js/auth";
-
-const user = await User.create({ ...data, password: await hashPassword(data.password) });
-
-await sendEmailVerification(user); // hashed, single-use, 24h token via @warlock.js/notifications
-
-const tokens = await authService.createTokenPair(user);
-return response.successCreate({ user, tokens });
-```
-
-Gate routes that need a confirmed address with `requireVerifiedEmail()` after `authMiddleware`. See [`@warlock.js/auth/verify-email-and-reset-password/SKILL.md`](@warlock.js/auth/verify-email-and-reset-password/SKILL.md).
-
-## Side effects via auth events
-
-Hook post-registration logic:
-
-```ts
-import { authEvents } from "@warlock.js/auth";
-
-authEvents.on("session.created", async (user, refreshToken, deviceInfo) => {
-  if (user.get("created_at") > new Date(Date.now() - 5000)) {
-    // freshly created in the last 5s — treat as registration
-    await sendWelcomeEmail(user);
-  }
-});
-```
-
-Cleaner alternative: emit your own `user.registered` event from the controller after `User.create`. Decouples auth-package events from your domain events.
-
-## Things NOT to do
-
-- Don't pass the plain password to `User.create()`. `await hashPassword(plain)` first.
-- Don't return the user without `toJsonColumns` / `resource` shaping — the password hash will leak otherwise.
-- Don't issue tokens before validating the user shape. `User.create` runs validation; let it throw on bad input before tokens get created.
-- Don't run "send welcome email" inline in the controller. Push it to a queue or run it after-commit via the outbox pattern — see [`@warlock.js/cascade/manage-transactions/SKILL.md`](@warlock.js/cascade/manage-transactions/SKILL.md).
-
-## See also
-
-- [`@warlock.js/auth/handle-login-and-logout/SKILL.md`](@warlock.js/auth/handle-login-and-logout/SKILL.md) — login flow (same `createTokenPair` step)
-- [`@warlock.js/auth/manage-tokens/SKILL.md`](@warlock.js/auth/manage-tokens/SKILL.md) — token issuance internals
-- [`@warlock.js/cascade/define-model/SKILL.md`](@warlock.js/cascade/define-model/SKILL.md) — `toJsonColumns` / `resource` for public output
+---
+name: register-user
+description: 'Sign up a new user and issue the initial token pair — User.create({...password: await hashPassword(plain)}) then authService.createTokenPair(user). Triggers: `User.create`, `hashPassword`, `verifyPassword`, `authService.createTokenPair`, `toJsonColumns`, `strongPassword`, `authEvents`; "build a register endpoint", "POST /register controller", "sign up a new user", "hash password on signup", "email verification flow"; typical import `import { authService } from "@warlock.js/auth"; import { hashPassword } from "@warlock.js/core"`. Skip: login — `@warlock.js/auth/handle-login-and-logout/SKILL.md`; token internals — `@warlock.js/auth/manage-tokens/SKILL.md`; competing libs `bcrypt`, `bcryptjs`, `argon2`.'
+---
+
+# Register-and-issue-tokens flow
+
+Two-step on the server: create the user (with hashed password), then issue tokens. Cascade handles the persistence; `authService` handles the tokens.
+
+```ts title="src/app/users/models/user/user.model.ts"
+import { Auth } from "@warlock.js/auth";
+import { RegisterModel } from "@warlock.js/cascade";
+
+@RegisterModel()
+export class User extends Auth {
+  public static table = "users";
+
+  public get userType(): string {
+    return "user";
+  }
+}
+```
+
+## The minimal shape
+
+```ts
+import { authService } from "@warlock.js/auth";
+import { hashPassword, type RequestHandler } from "@warlock.js/core";
+import { User } from "app/users/models/user/user.model";
+
+export const registerController: RequestHandler = async ({ request, response }) => {
+  const { email, password, name } = request.all();
+
+  // 1. Check duplicates
+  const existing = await User.first({ email });
+  if (existing) {
+    return response.conflict({ error: "Email already registered" });
+  }
+
+  // 2. Create the user with hashed password
+  const user = await User.create({
+    email,
+    name,
+    password: await hashPassword(password),
+  });
+
+  // 3. Issue tokens
+  const tokens = await authService.createTokenPair(user, {
+    userAgent: request.header("user-agent"),
+    ip: request.ip,
+  });
+
+  // 4. Respond
+  return response.successCreate({
+    user,         // shape via static toJsonColumns / static resource
+    tokens,
+  });
+};
+```
+
+That's the whole flow. `User.create({...})` runs the schema validation (including `.email()`, `.min()`, etc. on each field), so you don't need a separate validation pass — see [`@warlock.js/seal/handle-seal-errors/SKILL.md`](@warlock.js/seal/handle-seal-errors/SKILL.md) for catching validation failures.
+
+## Hash the password on the way in
+
+Always pass `hashPassword(plain)` — never store the plain password. The `hashPassword` helper is `bcrypt`-based and async; the cost factor matches the framework default.
+
+```ts
+import { hashPassword, verifyPassword } from "@warlock.js/core";
+
+const hash = await hashPassword("plaintext");      // store this
+const ok = await verifyPassword("plaintext", hash); // compare on login
+```
+
+`authService.attemptLogin` already calls `verifyPassword` against the stored hash — you don't compare passwords manually.
+
+## Schema enforcement
+
+Define the password as `v.string().strongPassword(12)` (or similar) in your User schema so weak passwords are rejected at `create()` time:
+
+```ts
+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
+  // status, role, etc.
+});
+```
+
+But **don't return the password in the public output**:
+
+```ts
+@RegisterModel()
+export class User extends Model<UserSchema> {
+  public static table = "users";
+  public static schema = userSchema;
+  public static toJsonColumns = ["id", "email", "name", "created_at"];   // omit password
+}
+```
+
+Without this, `JSON.stringify(user)` in your response leaks the hash.
+
+## Email verification flow (extending registration)
+
+Since 5.13 auth ships this. Declare `emailVerifiedAt: v.date().optional()` on the schema, then send the verification after creating the user:
+
+```ts
+import { authService, sendEmailVerification } from "@warlock.js/auth";
+
+const user = await User.create({ ...data, password: await hashPassword(data.password) });
+
+await sendEmailVerification(user); // hashed, single-use, 24h token via @warlock.js/notifications
+
+const tokens = await authService.createTokenPair(user);
+return response.successCreate({ user, tokens });
+```
+
+Gate routes that need a confirmed address with `requireVerifiedEmail()` after `authMiddleware`. See [`@warlock.js/auth/verify-email-and-reset-password/SKILL.md`](@warlock.js/auth/verify-email-and-reset-password/SKILL.md).
+
+## Side effects via auth events
+
+Hook post-registration logic:
+
+```ts
+import { authEvents } from "@warlock.js/auth";
+
+authEvents.on("session.created", async (user, refreshToken, deviceInfo) => {
+  if (user.get("created_at") > new Date(Date.now() - 5000)) {
+    // freshly created in the last 5s — treat as registration
+    await sendWelcomeEmail(user);
+  }
+});
+```
+
+Cleaner alternative: emit your own `user.registered` event from the controller after `User.create`. Decouples auth-package events from your domain events.
+
+## Things NOT to do
+
+- Don't pass the plain password to `User.create()`. `await hashPassword(plain)` first.
+- Don't return the user without `toJsonColumns` / `resource` shaping — the password hash will leak otherwise.
+- Don't issue tokens before validating the user shape. `User.create` runs validation; let it throw on bad input before tokens get created.
+- Don't run "send welcome email" inline in the controller. Push it to a queue or run it after-commit via the outbox pattern — see [`@warlock.js/cascade/manage-transactions/SKILL.md`](@warlock.js/cascade/manage-transactions/SKILL.md).
+
+## See also
+
+- [`@warlock.js/auth/handle-login-and-logout/SKILL.md`](@warlock.js/auth/handle-login-and-logout/SKILL.md) — login flow (same `createTokenPair` step)
+- [`@warlock.js/auth/manage-tokens/SKILL.md`](@warlock.js/auth/manage-tokens/SKILL.md) — token issuance internals
+- [`@warlock.js/cascade/define-model/SKILL.md`](@warlock.js/cascade/define-model/SKILL.md) — `toJsonColumns` / `resource` for public output

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

@@ -1,159 +1,159 @@
----
-name: run-auth-commands
-description: 'Three bundled CLI commands — warlock jwt.generate (creates strong JWT secret + writes to .env), warlock auth.cleanup (removes expired refresh tokens), and warlock auth.purge-never-expiring (finds and revokes token rows that can never expire). Register via registerJWTSecretGeneratorCommand(), registerAuthCleanupCommand() and registerAuthPurgeNeverExpiringCommand(). Triggers: `registerJWTSecretGeneratorCommand`, `registerAuthCleanupCommand`, `registerAuthPurgeNeverExpiringCommand`, `warlock jwt.generate`, `warlock auth.cleanup`, `warlock auth.purge-never-expiring`, `cleanupExpiredTokens`, `purgeNeverExpiringTokens`, `command`; "token never expires", "no exp claim", "Invalid Date expires_at"; "generate JWT secret", "bootstrap .env JWT_SECRET", "cron job for expired tokens", "schedule auth cleanup"; typical import `import { registerJWTSecretGeneratorCommand, registerAuthCleanupCommand, registerAuthPurgeNeverExpiringCommand } from "@warlock.js/auth"`. Skip: programmatic cleanup — `@warlock.js/auth/manage-tokens/SKILL.md`; in-process scheduling — `@warlock.js/scheduler/scheduler-basics/SKILL.md`; competing tools `dotenv-cli`, `node-cron`.'
----
-
-# Run auth commands
-
-The package ships three CLI commands. Register them in `warlock.config.ts`; the framework picks them up.
-
-## Register
-
-```ts title="warlock.config.ts"
-import {
-  registerAuthCleanupCommand,
-  registerAuthPurgeNeverExpiringCommand,
-  registerJWTSecretGeneratorCommand,
-} from "@warlock.js/auth";
-import { defineConfig } from "@warlock.js/core";
-
-export default defineConfig({
-  cli: {
-    commands: [
-      registerJWTSecretGeneratorCommand(),
-      registerAuthCleanupCommand(),
-      registerAuthPurgeNeverExpiringCommand(),
-    ],
-  },
-});
-```
-
-## `warlock jwt.generate` — JWT secret bootstrap
-
-```bash
-npx warlock jwt.generate
-```
-
-Generates a cryptographically strong secret string and writes it to your `.env` as `JWT_SECRET=...` (and `JWT_REFRESH_SECRET=...` if refresh tokens are enabled).
-
-Run it once when setting up a new project. Each developer typically runs it locally; production secrets come from your secret manager (Vault, AWS Secrets Manager, k8s secrets) and bypass this command.
-
-**Don't commit `.env`.** The generated secret should never live in the repo. The command writes to `.env`, which `.gitignore` already excludes in a default Warlock project.
-
-## `warlock auth.cleanup` — expired token sweep
-
-```bash
-npx warlock auth.cleanup
-```
-
-Runs `authService.cleanupExpiredTokens()` — deletes every refresh token whose `expires_at` has passed, then sweeps expired access-token rows and hard-deletes expired or consumed `one_time_tokens` rows (verification/reset tokens, OTP codes, passkey challenges). Fires `token.expired` per refresh token and `cleanup.completed` once.
-
-Schedule it periodically. Two common shapes:
-
-### Via the scheduler
-
-```ts
-import { scheduler, job } from "@warlock.js/scheduler";
-import { authService } from "@warlock.js/auth";
-
-scheduler.addJob(
-  job("auth-cleanup", () => authService.cleanupExpiredTokens())
-    .daily()
-    .at("03:00")
-    .preventOverlap(),
-);
-
-scheduler.start();
-```
-
-In-process — no shell call. See [`@warlock.js/scheduler/scheduler-basics/SKILL.md`](@warlock.js/scheduler/scheduler-basics/SKILL.md).
-
-### Via system cron
-
-```cron
-0 3 * * *  cd /path/to/app && /usr/local/bin/npx warlock auth.cleanup
-```
-
-Out-of-process — works when you don't want the scheduler subsystem running in this service.
-
-## How often?
-
-Once a day is usually enough. The check is cheap (single indexed DELETE on `expires_at < now()`), and refresh tokens that have already expired don't grant access — cleanup is housekeeping, not security.
-
-If you have very-short-lived refresh tokens (1h expiry) and a million-user scale where the table grows fast, cleanup more often (hourly).
-
-## `warlock auth.purge-never-expiring` — one-off remediation
-
-```bash
-npx warlock auth.purge-never-expiring --dry-run   # report only
-npx warlock auth.purge-never-expiring             # report, then revoke
-```
-
-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.
-
-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.
-
-Unlike `auth.cleanup`, do **not** schedule it: it is a full table scan (it must read rows to judge them, since neither signal is expressible as a `where`), and once the poisoned rows are gone, 4.12.0 cannot create more.
-
-## Custom commands
-
-If `auth.cleanup` doesn't cover everything your app needs (e.g. you also want to revoke tokens for inactive users), write your own command and combine the auth service helpers:
-
-```ts title="src/app/users/models/user/user.model.ts"
-import { Auth } from "@warlock.js/auth";
-import { RegisterModel } from "@warlock.js/cascade";
-
-@RegisterModel()
-export class User extends Auth {
-  public static table = "users";
-
-  public get userType(): string {
-    return "user";
-  }
-}
-```
-
-```ts
-import { command } from "@warlock.js/core";
-import { authService } from "@warlock.js/auth";
-import { User } from "app/users/models/user/user.model";
-
-export function registerDeepCleanupCommand() {
-  return command({
-    name: "auth.deep-cleanup",
-    description: "Expire stale tokens AND revoke tokens for inactive users",
-    preload: {
-      env: true,
-      config: ["auth", "database"],
-      connectors: ["database"],
-    },
-    action: async () => {
-      await authService.cleanupExpiredTokens();
-
-      const thirtyDaysAgo = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
-      const stale = await User.where("last_seen_at", "<", thirtyDaysAgo).get();
-
-      for (const user of stale) {
-        await authService.revokeAllTokens(user);
-      }
-    },
-  });
-}
-```
-
-Register it the same way as the bundled commands — call the factory inside `defineConfig({ cli: { commands: [...] } })`.
-
-## Things NOT to do
-
-- Don't run `jwt.generate` repeatedly in production. It changes the secret, which invalidates every token in flight. Generate once per environment.
-- Don't run `auth.cleanup` from a long-running scheduler at sub-minute intervals. The DELETE itself is cheap, but the per-token `token.expired` event fan-out has cost. Hourly is plenty even at scale.
-- Don't put the JWT secret in your codebase fallback (`env("JWT_SECRET", "dev-secret")`). A missing secret should fail the boot — not silently degrade to a dev value.
-
-## See also
-
-- [`@warlock.js/auth/manage-tokens/SKILL.md`](@warlock.js/auth/manage-tokens/SKILL.md) — `cleanupExpiredTokens` internals
-- [`@warlock.js/scheduler/scheduler-basics/SKILL.md`](@warlock.js/scheduler/scheduler-basics/SKILL.md) — in-process scheduling
+---
+name: run-auth-commands
+description: 'Three bundled CLI commands — warlock jwt.generate (creates strong JWT secret + writes to .env), warlock auth.cleanup (removes expired refresh tokens), and warlock auth.purge-never-expiring (finds and revokes token rows that can never expire). Register via registerJWTSecretGeneratorCommand(), registerAuthCleanupCommand() and registerAuthPurgeNeverExpiringCommand(). Triggers: `registerJWTSecretGeneratorCommand`, `registerAuthCleanupCommand`, `registerAuthPurgeNeverExpiringCommand`, `warlock jwt.generate`, `warlock auth.cleanup`, `warlock auth.purge-never-expiring`, `cleanupExpiredTokens`, `purgeNeverExpiringTokens`, `command`; "token never expires", "no exp claim", "Invalid Date expires_at"; "generate JWT secret", "bootstrap .env JWT_SECRET", "cron job for expired tokens", "schedule auth cleanup"; typical import `import { registerJWTSecretGeneratorCommand, registerAuthCleanupCommand, registerAuthPurgeNeverExpiringCommand } from "@warlock.js/auth"`. Skip: programmatic cleanup — `@warlock.js/auth/manage-tokens/SKILL.md`; in-process scheduling — `@warlock.js/scheduler/scheduler-basics/SKILL.md`; competing tools `dotenv-cli`, `node-cron`.'
+---
+
+# Run auth commands
+
+The package ships three CLI commands. Register them in `warlock.config.ts`; the framework picks them up.
+
+## Register
+
+```ts title="warlock.config.ts"
+import {
+  registerAuthCleanupCommand,
+  registerAuthPurgeNeverExpiringCommand,
+  registerJWTSecretGeneratorCommand,
+} from "@warlock.js/auth";
+import { defineConfig } from "@warlock.js/core";
+
+export default defineConfig({
+  cli: {
+    commands: [
+      registerJWTSecretGeneratorCommand(),
+      registerAuthCleanupCommand(),
+      registerAuthPurgeNeverExpiringCommand(),
+    ],
+  },
+});
+```
+
+## `warlock jwt.generate` — JWT secret bootstrap
+
+```bash
+npx warlock jwt.generate
+```
+
+Generates a cryptographically strong secret string and writes it to your `.env` as `JWT_SECRET=...` (and `JWT_REFRESH_SECRET=...` if refresh tokens are enabled).
+
+Run it once when setting up a new project. Each developer typically runs it locally; production secrets come from your secret manager (Vault, AWS Secrets Manager, k8s secrets) and bypass this command.
+
+**Don't commit `.env`.** The generated secret should never live in the repo. The command writes to `.env`, which `.gitignore` already excludes in a default Warlock project.
+
+## `warlock auth.cleanup` — expired token sweep
+
+```bash
+npx warlock auth.cleanup
+```
+
+Runs `authService.cleanupExpiredTokens()` — deletes every refresh token whose `expires_at` has passed, then sweeps expired access-token rows and hard-deletes expired or consumed `one_time_tokens` rows (verification/reset tokens, OTP codes, passkey challenges). Fires `token.expired` per refresh token and `cleanup.completed` once.
+
+Schedule it periodically. Two common shapes:
+
+### Via the scheduler
+
+```ts
+import { scheduler, job } from "@warlock.js/scheduler";
+import { authService } from "@warlock.js/auth";
+
+scheduler.addJob(
+  job("auth-cleanup", () => authService.cleanupExpiredTokens())
+    .daily()
+    .at("03:00")
+    .preventOverlap(),
+);
+
+scheduler.start();
+```
+
+In-process — no shell call. See [`@warlock.js/scheduler/scheduler-basics/SKILL.md`](@warlock.js/scheduler/scheduler-basics/SKILL.md).
+
+### Via system cron
+
+```cron
+0 3 * * *  cd /path/to/app && /usr/local/bin/npx warlock auth.cleanup
+```
+
+Out-of-process — works when you don't want the scheduler subsystem running in this service.
+
+## How often?
+
+Once a day is usually enough. The check is cheap (single indexed DELETE on `expires_at < now()`), and refresh tokens that have already expired don't grant access — cleanup is housekeeping, not security.
+
+If you have very-short-lived refresh tokens (1h expiry) and a million-user scale where the table grows fast, cleanup more often (hourly).
+
+## `warlock auth.purge-never-expiring` — one-off remediation
+
+```bash
+npx warlock auth.purge-never-expiring --dry-run   # report only
+npx warlock auth.purge-never-expiring             # report, then revoke
+```
+
+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.
+
+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.
+
+Unlike `auth.cleanup`, do **not** schedule it: it is a full table scan (it must read rows to judge them, since neither signal is expressible as a `where`), and once the poisoned rows are gone, 4.12.0 cannot create more.
+
+## Custom commands
+
+If `auth.cleanup` doesn't cover everything your app needs (e.g. you also want to revoke tokens for inactive users), write your own command and combine the auth service helpers:
+
+```ts title="src/app/users/models/user/user.model.ts"
+import { Auth } from "@warlock.js/auth";
+import { RegisterModel } from "@warlock.js/cascade";
+
+@RegisterModel()
+export class User extends Auth {
+  public static table = "users";
+
+  public get userType(): string {
+    return "user";
+  }
+}
+```
+
+```ts
+import { command } from "@warlock.js/core";
+import { authService } from "@warlock.js/auth";
+import { User } from "app/users/models/user/user.model";
+
+export function registerDeepCleanupCommand() {
+  return command({
+    name: "auth.deep-cleanup",
+    description: "Expire stale tokens AND revoke tokens for inactive users",
+    preload: {
+      env: true,
+      config: ["auth", "database"],
+      connectors: ["database"],
+    },
+    action: async () => {
+      await authService.cleanupExpiredTokens();
+
+      const thirtyDaysAgo = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
+      const stale = await User.where("last_seen_at", "<", thirtyDaysAgo).get();
+
+      for (const user of stale) {
+        await authService.revokeAllTokens(user);
+      }
+    },
+  });
+}
+```
+
+Register it the same way as the bundled commands — call the factory inside `defineConfig({ cli: { commands: [...] } })`.
+
+## Things NOT to do
+
+- Don't run `jwt.generate` repeatedly in production. It changes the secret, which invalidates every token in flight. Generate once per environment.
+- Don't run `auth.cleanup` from a long-running scheduler at sub-minute intervals. The DELETE itself is cheap, but the per-token `token.expired` event fan-out has cost. Hourly is plenty even at scale.
+- Don't put the JWT secret in your codebase fallback (`env("JWT_SECRET", "dev-secret")`). A missing secret should fail the boot — not silently degrade to a dev value.
+
+## See also
+
+- [`@warlock.js/auth/manage-tokens/SKILL.md`](@warlock.js/auth/manage-tokens/SKILL.md) — `cleanupExpiredTokens` internals
+- [`@warlock.js/scheduler/scheduler-basics/SKILL.md`](@warlock.js/scheduler/scheduler-basics/SKILL.md) — in-process scheduling