@lastshotlabs/bunshot 0.0.21 → 0.0.27

package/docs/sections/auth-flow/full.md

@@ -1,16 +1,24 @@
-## Auth Flow
+### Auth Flow
 
 Sessions are backed by Redis by default. Each login creates an independent session keyed by a UUID (`session:{appName}:{sessionId}`), so multiple devices / tabs can be logged in simultaneously. Set `db.sessions: "mongo"` to store them in MongoDB instead — useful when running without Redis. See [Running without Redis](#running-without-redis).
 
-### Browser clients
+#### Browser clients
 1. `POST /auth/login` → JWT set as HttpOnly cookie automatically
 2. All subsequent requests send the cookie — no extra code needed
 
-### API / non-browser clients
+#### API / non-browser clients
 1. `POST /auth/login` → read `token` from response body
 2. Send `x-user-token: <token>` header on every request
 
-### Session management
+#### Current user
+
+```
+GET /auth/me  →  { userId, email?, emailVerified?, googleLinked? }
+```
+
+Requires an active session (cookie or `x-user-token` header). Returns the authenticated user's profile — `email`, `emailVerified`, and `googleLinked` are populated when the auth adapter implements `getUser`.
+
+#### Session management
 
 Each login creates an independent session so multiple devices stay logged in simultaneously. The framework enforces a configurable cap (default: 6) — the oldest session is evicted when the limit is exceeded.
 
@@ -24,11 +32,11 @@ Session metadata (IP address, user-agent, timestamps) is persisted even after a
 
 Set `sessionPolicy.includeInactiveSessions: true` to surface expired/deleted sessions in `GET /auth/sessions` with `isActive: false` — useful for a full device-history UI similar to Google or Meta's account security page.
 
-#### Sliding sessions
+##### Sliding sessions
 
 Set `sessionPolicy.trackLastActive: true` to update `lastActiveAt` on every authenticated request. This adds one DB write per request but enables a sliding-session experience — sessions that are actively used stay fresh. Pair with refresh tokens (below) for true sliding behavior: short-lived access tokens (15 min) keep authorization tight, while a long-lived refresh token (30 days) lets the client silently renew without re-entering credentials.
 
-### Refresh Tokens
+#### Refresh Tokens
 
 When configured, login and register return short-lived access tokens (default 15 min) alongside long-lived refresh tokens (default 30 days). The client uses `POST /auth/refresh` to obtain a new access token when the current one expires.
 
@@ -46,7 +54,7 @@ await createServer({
 
 **When not configured**, the existing 7-day JWT behavior is unchanged — fully backward compatible.
 
-#### Endpoints
+##### Endpoints
 
 | Endpoint | Purpose |
 |---|---|
@@ -54,15 +62,15 @@ await createServer({
 | `POST /auth/register` | Returns `token` + `refreshToken` |
 | `POST /auth/refresh` | Rotates refresh token, returns new `token` + `refreshToken` |
 
-#### Rotation with grace window
+##### Rotation with grace window
 
 On each refresh, the server generates a new refresh token but keeps the old one valid for `rotationGraceSeconds` (default 30s). If the client's network drops mid-refresh, it can safely retry with the old token. If the old token is reused *after* the grace window, the entire session is invalidated — this is token-family theft detection.
 
-#### Cookie behavior
+##### Cookie behavior
 
-The refresh token is set as an `HttpOnly` cookie (`refresh_token`) alongside the existing session cookie. For non-browser clients, it's also returned in the JSON body and accepted via the `x-refresh-token` header.
+The refresh token is set as an `HttpOnly` cookie (`refresh_token`) alongside the existing session cookie. For non-browser clients, it is accepted via the `x-refresh-token` header or in the request body. **The refresh token is not returned in the JSON response body** — it is only delivered via the `HttpOnly` cookie to prevent accidental exposure in logs or client-side code.
 
-### MFA / TOTP
+#### MFA / TOTP
 
 Enable multi-factor authentication with TOTP (Google Authenticator, Authy, etc.):
 
@@ -87,7 +95,7 @@ Requires `otpauth` peer dependency:
 bun add otpauth
 ```
 
-#### Endpoints
+##### Endpoints
 
 | Endpoint | Auth | Purpose |
 |---|---|---|
@@ -98,7 +106,7 @@ bun add otpauth
 | `POST /auth/mfa/recovery-codes` | userAuth | Regenerate codes (requires TOTP code) |
 | `GET /auth/mfa/methods` | userAuth | Get enabled MFA methods |
 
-#### Login flow with MFA enabled
+##### Login flow with MFA enabled
 
 1. `POST /auth/login` with credentials → password OK + MFA enabled → `{ mfaRequired: true, mfaToken: "...", mfaMethods: ["totp"] }` (no session created)
 2. `POST /auth/mfa/verify` with `{ mfaToken, code }` → verifies TOTP or recovery code → creates session → returns normal token response
@@ -109,7 +117,45 @@ The verify endpoint accepts an optional `method` field (`"totp"` or `"emailOtp"`
 
 **Recovery codes**: 10 random 8-character alphanumeric codes, stored as SHA-256 hashes. Each code can only be used once. Enabling a second MFA method regenerates recovery codes — save the new set.
 
-### Email OTP
+##### Enforcing MFA for all users
+
+By default MFA is opt-in — individual users choose whether to enable it. Set `required: true` to enforce MFA at the app level:
+
+```ts
+await createServer({
+  auth: {
+    mfa: {
+      issuer: "My App",
+      required: true, // all authenticated users must complete MFA setup
+    },
+  },
+});
+```
+
+When `required` is `true`:
+
+- Authenticated users who have **not** completed MFA setup receive a `403` response on all non-auth endpoints:
+  ```json
+  { "error": "MFA setup required", "code": "MFA_SETUP_REQUIRED" }
+  ```
+- **Exempt paths** remain accessible so users can complete setup: all `/auth/*` routes (login, logout, register, MFA setup, OAuth, sessions), `/health`, `/docs`, `/openapi.json`, and the root `/`.
+- **Unauthenticated requests** pass through normally — the middleware only gates users who are logged in but lack MFA.
+- **OAuth users** must also set up MFA — OAuth login creates a session, but the user is still blocked from service endpoints until MFA is configured.
+- **Disabling MFA** (via `DELETE /auth/mfa`) when `required: true` immediately blocks the user from service endpoints until they re-enable it.
+
+**Client-side handling:** Check for the `MFA_SETUP_REQUIRED` code in 403 responses and redirect users to an MFA setup page that calls `POST /auth/mfa/setup`.
+
+**Per-route usage:** The `requireMfaSetup` middleware is also exported for apps that want manual, per-route enforcement instead of global:
+
+```ts
+import { userAuth, requireMfaSetup } from "@lastshotlabs/bunshot";
+
+router.get("/dashboard", userAuth, requireMfaSetup, (c) => {
+  return c.json({ message: "Welcome" });
+});
+```
+
+#### Email OTP
 
 An alternative to TOTP that sends a one-time code to the user's email. Users can enable TOTP, email OTP, or both.
 
@@ -129,7 +175,7 @@ await createServer({
 });
 ```
 
-#### Endpoints
+##### Endpoints
 
 | Endpoint | Auth | Purpose |
 |---|---|---|
@@ -138,26 +184,26 @@ await createServer({
 | `DELETE /auth/mfa/email-otp` | userAuth | Disable email OTP |
 | `POST /auth/mfa/resend` | none (uses mfaToken) | Resend email OTP code (max 3 per challenge) |
 
-#### Setup flow
+##### Setup flow
 
 1. `POST /auth/mfa/email-otp/enable` → sends code to email → returns `{ setupToken }`
 2. `POST /auth/mfa/email-otp/verify-setup` with `{ setupToken, code }` → enables email OTP → returns recovery codes
 
 This two-step flow ensures the `onSend` callback actually delivers emails before MFA is activated, preventing lockout from misconfigured email providers.
 
-#### Login flow with email OTP
+##### Login flow with email OTP
 
 1. `POST /auth/login` → `{ mfaRequired: true, mfaToken, mfaMethods: ["emailOtp"] }` — code is auto-sent to user's email
 2. `POST /auth/mfa/verify` with `{ mfaToken, code }` → creates session
 3. If the code didn't arrive: `POST /auth/mfa/resend` with `{ mfaToken }` (max 3 resends, capped at 3x challenge TTL)
 
-#### Disabling email OTP
+##### Disabling email OTP
 
 - If TOTP is also enabled: requires a TOTP code in the `code` field
 - If email OTP is the only method: requires the account password in the `password` field
 - Disabling the last MFA method turns off MFA entirely
 
-### WebAuthn / Security Keys
+#### WebAuthn / Security Keys
 
 Hardware security keys (YubiKey, etc.) and platform authenticators (Touch ID, Windows Hello) via the WebAuthn/FIDO2 standard. Users can register multiple keys and use them as an MFA method alongside TOTP and email OTP.
 
@@ -186,7 +232,7 @@ bun add @simplewebauthn/server
 
 If `mfa.webauthn` is configured but the dependency is missing, the server fails fast at startup with a clear error message.
 
-#### Endpoints
+##### Endpoints
 
 | Endpoint | Auth | Purpose |
 |---|---|---|
@@ -196,13 +242,15 @@ If `mfa.webauthn` is configured but the dependency is missing, the server fails
 | `DELETE /auth/mfa/webauthn/credentials/:credentialId` | userAuth | Remove a single key |
 | `DELETE /auth/mfa/webauthn` | userAuth | Disable WebAuthn entirely |
 
-#### Registration flow
+##### Registration flow
 
 1. `POST /auth/mfa/webauthn/register-options` → returns `{ options, registrationToken }`
 2. Client passes `options` to `navigator.credentials.create()` — browser prompts user to tap/scan key
 3. `POST /auth/mfa/webauthn/register` with `{ registrationToken, attestationResponse, name? }` → stores credential → returns recovery codes
 
-#### Login flow with WebAuthn
+> Credentials are registered with `residentKey: "required"` and `userVerification: "required"`, making them usable as discoverable passkeys. This enables passwordless login via `allowPasswordlessLogin` without requiring users to re-register.
+
+##### Login flow with WebAuthn
 
 1. `POST /auth/login` → `{ mfaRequired: true, mfaToken, mfaMethods: ["webauthn"], webauthnOptions: {...} }`
 2. Client passes `webauthnOptions` to `navigator.credentials.get()` — browser prompts for key
@@ -210,17 +258,87 @@ If `mfa.webauthn` is configured but the dependency is missing, the server fails
 
 The `webauthnOptions` object follows the WebAuthn spec — pass it directly to `navigator.credentials.get()`. The `webauthnResponse` is the full result from the browser API.
 
-#### Credential removal
+##### Credential removal
 
 - Removing a spare key (other keys or MFA methods still active): no extra verification needed
 - Removing the last credential of the last MFA method: requires TOTP code or password
 - `DELETE /auth/mfa/webauthn` (disable all): always requires verification
 
-#### Sign count validation
+##### Sign count validation
 
 WebAuthn authenticators increment a sign count on each use to detect cloned keys. By default, a backward count logs a warning but allows authentication. Set `strictSignCount: true` to reject authentication when the count goes backward.
 
-### Account Deletion
+#### Email Verification
+
+Opt-in via `auth.emailVerification`. Requires `primaryField: "email"` (default).
+
+```ts
+await createServer({
+  auth: {
+    emailVerification: {
+      onSend: async (email, token) => {
+        // Send via any provider (Resend, SendGrid, etc.)
+        await sendEmail(email, `Verify your email: https://myapp.com/verify?token=${token}`);
+      },
+      required: true,      // Block login until verified (default: false)
+      tokenExpiry: 86400,  // Seconds — default: 86400 (24 hours)
+    },
+  },
+});
+```
+
+When configured, two routes are mounted:
+
+| Endpoint | Auth | Purpose |
+|---|---|---|
+| `POST /auth/verify-email` | none | Consume verification token |
+| `POST /auth/resend-verification` | none (uses credentials) | Resend verification email |
+
+A verification token is sent automatically on registration via `emailVerification.onSend`. The token is SHA-256 hashed before storage. Rate-limited by IP (verify) and identifier (resend).
+
+When `required: true`, unverified users receive `403 { error: "Email not verified" }` on `/auth/login`.
+
+#### Password Reset
+
+Opt-in via `auth.passwordReset`. Requires `primaryField: "email"` (default) and a `setPassword` implementation on your auth adapter.
+
+```ts
+await createServer({
+  auth: {
+    passwordReset: {
+      onSend: async (email, token) => {
+        await sendEmail(email, `Reset your password: https://myapp.com/reset?token=${token}`);
+      },
+      tokenExpiry: 3600,  // Seconds — default: 3600 (1 hour)
+    },
+  },
+});
+```
+
+When configured, two routes are mounted:
+
+| Endpoint | Auth | Purpose |
+|---|---|---|
+| `POST /auth/forgot-password` | none | Request reset email (always returns 200 — never reveals whether address is registered) |
+| `POST /auth/reset-password` | none | Consume token, set new password, revoke all sessions |
+
+The forgot-password endpoint uses a fire-and-forget pattern and is rate-limited by **both IP and email address** to prevent distributed email-bombing. Tokens are SHA-256 hashed before storage and single-use. After a successful reset, all active sessions are revoked.
+
+#### Primary Field
+
+By default, users register and log in with their email address. Change this via `auth.primaryField`:
+
+```ts
+await createServer({
+  auth: {
+    primaryField: "username",  // "email" (default) | "username" | "phone"
+  },
+});
+```
+
+When set to `"username"` or `"phone"`, the registration/login body uses that field name instead of `email`. Email verification and password reset are only available when `primaryField` is `"email"`. Implement `adapter.findByIdentifier` on your custom adapter for non-email primary fields — it falls back to `findByEmail` when absent.
+
+#### Account Deletion
 
 Enable `DELETE /auth/me` for user-initiated account deletion:
 
@@ -245,18 +363,47 @@ await createServer({
 });
 ```
 
-#### Behavior
+##### Behavior
 
 - Requires `userAuth` middleware (user must be logged in)
 - Body: `{ password?: string }` — required for credential accounts, skipped for OAuth-only
 - Revokes all sessions, deletes tokens, calls `adapter.deleteUser(userId)`
 - Rate limited (3/hour by userId)
 
-#### Queued deletion
+##### Queued deletion
 
-When `queued: true`, deletion is enqueued as a BullMQ job instead of running synchronously. The endpoint returns `202 Accepted` immediately. With `gracePeriod > 0`, the user can cancel via `POST /auth/cancel-deletion`.
+When `queued: true`, deletion is enqueued as a BullMQ job instead of running synchronously. The endpoint returns `202 Accepted` immediately and the user's sessions are revoked at that point. The actual user data deletion executes after the delay set by `gracePeriod`.
 
-### Password Policy
+The framework starts a built-in BullMQ worker automatically (in-process, alongside the API server) to process deletion jobs. Requires BullMQ and Redis:
+
+```bash
+bun add bullmq
+```
+
+With `gracePeriod > 0`, the `POST /auth/cancel-deletion` route is mounted. Provide `onDeletionScheduled` to send the cancel token to the user:
+
+```ts
+auth: {
+  accountDeletion: {
+    queued: true,
+    gracePeriod: 7 * 24 * 60 * 60,  // 7 days in seconds
+    onDeletionScheduled: async (userId, email, cancelToken) => {
+      await sendEmail(email, `Cancel deletion: https://myapp.com/cancel?token=${cancelToken}`);
+    },
+  },
+}
+```
+
+The cancel endpoint accepts the token and removes the pending BullMQ job:
+
+```
+POST /auth/cancel-deletion  →  { message: "Account deletion cancelled" }
+Body: { token: string }
+```
+
+The cancel token expires when the grace period elapses and can only be used once.
+
+#### Password Policy
 
 Configure password complexity requirements via `auth.passwordPolicy`. The policy applies to registration and password reset — login uses `min(1)` intentionally to avoid locking out users registered under older/weaker policies.
 
@@ -275,7 +422,7 @@ await createServer({
 
 When not configured, the default policy requires 8+ characters with at least one letter and one digit.
 
-### Protecting routes
+#### Protecting routes
 
 ```ts
 import { userAuth, requireRole, requireVerifiedEmail } from "@lastshotlabs/bunshot";
@@ -286,7 +433,7 @@ router.use("/content", userAuth, requireRole("admin", "editor")); // allow eithe
 router.use("/dashboard", userAuth, requireVerifiedEmail);       // returns 403 if email not verified
 ```
 
-### Custom auth adapter
+#### Custom auth adapter
 
 By default, `/auth/*` routes store users in MongoDB via `mongoAuthAdapter`. Pass `auth: { adapter: myAdapter }` to `createServer` to use any other store — Postgres, SQLite, an external service, etc. Alternatively, use `db.auth` to select a built-in adapter (`"mongo"` | `"sqlite"` | `"memory"`).
 
@@ -367,7 +514,7 @@ The adapter is responsible for:
 
 Everything else (password hashing, JWT signing, Redis sessions) is handled by the package.
 
-### Auth Rate Limiting
+#### Auth Rate Limiting
 
 All built-in auth endpoints are rate-limited out of the box with sensible defaults. No configuration needed — just be aware of the behavior:
 
@@ -377,7 +524,7 @@ All built-in auth endpoints are rate-limited out of the box with sensible defaul
 | `POST /auth/register` | IP address | Every attempt | 5 / hour |
 | `POST /auth/verify-email` | IP address | Every attempt | 10 / 15 min |
 | `POST /auth/resend-verification` | Identifier (email/username/phone) | Every attempt | 3 / hour |
-| `POST /auth/forgot-password` | IP address | Every attempt | 5 / 15 min |
+| `POST /auth/forgot-password` | IP address **and** email address | Every attempt | 5 / 15 min (shared window per key) |
 | `POST /auth/reset-password` | IP address | Every attempt | 10 / 15 min |
 | `POST /auth/refresh` | IP address | Every attempt | 30 / min |
 | `POST /auth/mfa/verify` | IP address | Every attempt | 10 / 15 min |
@@ -385,7 +532,7 @@ All built-in auth endpoints are rate-limited out of the box with sensible defaul
 
 Login is keyed by the **identifier being targeted** — an attacker rotating IPs to brute-force `alice@example.com` is blocked regardless of source IP. A successful login resets the counter so legitimate users aren't locked out.
 
-#### Tuning limits
+##### Tuning limits
 
 ```ts
 await createServer({
@@ -401,7 +548,7 @@ await createServer({
 });
 ```
 
-#### Manually clearing a limit (admin unlock)
+##### Manually clearing a limit (admin unlock)
 
 If a legitimate user gets locked out, call `bustAuthLimit` with the same key format the limiter uses:
 
@@ -416,9 +563,9 @@ router.post("/admin/unblock-login", userAuth, requireRole("admin"), async (c) =>
 });
 ```
 
-Key formats: `login:{identifier}`, `register:{ip}`, `verify:{ip}`, `resend:{userId}`.
+Key formats: `login:{identifier}`, `register:{ip}`, `verify:{ip}`, `resend:{identifier}`, `forgot:ip:{ip}`, `forgot:email:{email}`, `reset:{ip}`, `refresh:ip:{ip}`, `deleteaccount:{userId}`.
 
-#### Using the rate limiter in your own routes
+##### Using the rate limiter in your own routes
 
 `trackAttempt` and `isLimited` are exported so you can apply the same Redis-backed rate limiting to any route in your app. They use the same store configured via `auth.rateLimit.store`.
 
@@ -452,17 +599,17 @@ if (await isLimited(key, opts)) {
 
 Keys are automatically namespaced to the app (e.g. `rl:MyApp:submit:1.2.3.4`) when the Redis store is active, so they won't collide on a shared Redis instance.
 
-#### Store
+##### Store
 
 The rate limit store defaults to `"redis"` when Redis is enabled (recommended for multi-instance deployments — limits are shared across all servers). Falls back to `"memory"` automatically when Redis is disabled. In-memory limits don't persist across restarts.
 
 ---
 
-### Bot Protection
+#### Bot Protection
 
 The built-in IP rate limiter is ineffective against bots that rotate IPs. The `botProtection` config adds two IP-rotation-resistant layers that run before the IP rate limit check.
 
-#### Fingerprint rate limiting
+##### Fingerprint rate limiting
 
 When `fingerprintRateLimit: true`, every request is also rate-limited by an HTTP fingerprint — a 12-char hash derived from `User-Agent`, `Accept-*`, `Connection`, and the presence/absence of browser-only headers (`sec-fetch-*`, `sec-ch-ua-*`, `origin`, `referer`, etc.).
 
@@ -481,7 +628,7 @@ await createServer({
 
 The fingerprint bucket uses the same window and max as `security.rateLimit`, and is stored in the same backend as `auth.rateLimit.store` (Redis by default, shared across all instances).
 
-#### IP / CIDR blocklist
+##### IP / CIDR blocklist
 
 Block known datacenter ranges, proxy providers, or individual IPs outright. Matched requests receive a 403 before any other processing — no session lookup, no rate-limit increment.
 
@@ -501,7 +648,7 @@ await createServer({
 
 Both options can be combined. The middleware order is: blocklist → IP rate limit → fingerprint rate limit.
 
-#### Apply `botProtection` to individual routes
+##### Apply `botProtection` to individual routes
 
 `botProtection` is also exported for per-route use:
 
@@ -513,7 +660,7 @@ router.use("/api/submit", botProtection({ blockList: ["198.51.100.0/24"] }));
 
 ---
 
-### Trusted Proxy
+#### Trusted Proxy
 
 By default, Bunshot uses the socket-level IP address for all rate limiting and session metadata — the `X-Forwarded-For` header is **ignored entirely**. This prevents attackers from spoofing IPs to bypass rate limits.
 
@@ -542,7 +689,7 @@ router.post("/api/action", async (c) => {
 });
 ```
 
-### JWT Secret Validation
+#### JWT Secret Validation
 
 JWT secrets are validated on first use. The framework throws a clear error if:
 - The environment variable (`JWT_SECRET_DEV` or `JWT_SECRET_PROD`) is missing
@@ -556,21 +703,30 @@ node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"
 
 ---
 
-### Setting a password after social login
+#### Setting a password after social login
 
 If a user signed up via Google or Apple and later wants to add a password, send an authenticated request to `POST /auth/set-password`:
 
 ```ts
-// Client (logged-in user)
+// Client (logged-in user) — first time setting a password (no currentPassword needed)
 await fetch("/auth/set-password", {
   method: "POST",
   headers: { "Content-Type": "application/json", "x-user-token": token },
   body: JSON.stringify({ password: "mynewpassword" }),
 });
+
+// Changing an existing password — currentPassword is required
+await fetch("/auth/set-password", {
+  method: "POST",
+  headers: { "Content-Type": "application/json", "x-user-token": token },
+  body: JSON.stringify({ password: "mynewpassword", currentPassword: "oldpassword" }),
+});
 ```
 
 The built-in route hashes the password and calls `adapter.setPassword(userId, hash)`. If your adapter does not implement `setPassword`, the route returns `501 Not Implemented`.
 
+**If the account already has a password set**, `currentPassword` must be provided. Missing it returns `400 { error: "Current password is required to change an existing password." }`. An incorrect `currentPassword` returns `401 { error: "Current password is incorrect." }`.
+
 To support it with a custom adapter:
 
 ```ts
@@ -583,7 +739,7 @@ const myAdapter: AuthAdapter = {
 };
 ```
 
-### CSRF Protection
+#### CSRF Protection
 
 Opt-in via `security.csrf` — protects cookie-authenticated browser clients against cross-site request forgery attacks. Mobile apps and SPAs using header-based auth (`x-user-token`) are not affected and do not need CSRF.
 

package/docs/sections/auth-flow/overview.md

@@ -1,10 +1,10 @@
-## Auth Flow
+### Auth Flow
 
 Sessions are backed by Redis (default), MongoDB, SQLite, or memory. Each login creates an independent session keyed by UUID, so multiple devices stay logged in simultaneously.
 
 - **Browser clients**: `POST /auth/login` sets an HttpOnly cookie automatically
 - **API clients**: Read `token` from the response body, send `x-user-token: <token>` header
 
-Features include session management (list/revoke), refresh tokens (short-lived access + long-lived refresh with rotation), MFA (TOTP via Google Authenticator, email OTP, recovery codes), account deletion (immediate or queued with grace period), custom auth adapters, rate limiting on all auth endpoints, bot protection (fingerprint rate limiting + CIDR blocklist), and password set/reset flows.
+Features include session management (list/revoke), current user endpoint (`GET /auth/me`), email verification (opt-in, with `required` gate), password reset (fire-and-forget, dual-keyed rate limiting), refresh tokens (short-lived access + long-lived refresh with rotation), MFA (TOTP via Google Authenticator, email OTP, WebAuthn, recovery codes), account deletion (immediate or queued BullMQ with grace period and cancel endpoint), custom auth adapters, rate limiting on all auth endpoints, bot protection (fingerprint rate limiting + CIDR blocklist), configurable primary field (email/username/phone), and CSRF protection.
 
 Protect routes with `userAuth`, `requireRole("admin")`, and `requireVerifiedEmail` middleware.