@warlock.js/auth 5.30.0 → 5.31.0

package/skills/throttle-login-attempts/SKILL.md

@@ -7,7 +7,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
 
@@ -23,6 +23,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`).
@@ -34,10 +63,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.",
 });
@@ -55,16 +84,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
 
@@ -92,20 +121,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.

package/skills/verify-email-and-reset-password/SKILL.md

@@ -94,10 +94,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`)
 
@@ -115,7 +115,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
 };