@lastshotlabs/bunshot 0.0.13 → 0.0.16

package/docs/sections/adding-routes/full.md

@@ -0,0 +1,182 @@
+## Adding Routes
+
+Drop a file in your `routes/` directory that exports a `router` — see the [Quick Start](#quick-start) example above. Routes are auto-discovered via glob — no registration needed. Subdirectories are supported, so you can organise by feature:
+
+```
+routes/
+  products.ts
+  ingredients/
+    list.ts
+    detail.ts
+```
+
+### OpenAPI Schema Registration
+
+Import `createRoute` from `@lastshotlabs/bunshot` (not from `@hono/zod-openapi`). The wrapper automatically registers every unnamed request body and response schema as a named entry in `components/schemas`. Schemas you already named via `registerSchema` are never overwritten.
+
+Every Zod schema that appears in your OpenAPI spec ends up as a named entry in `components/schemas` — either auto-named by the framework or explicitly named by you. There are four registration methods, each suited to a different scenario.
+
+---
+
+### Method 1 — Route-level auto-registration (via `createRoute`)
+
+The most common case. When you define a route with `createRoute`, every unnamed request body and response schema is automatically registered under a name derived from the HTTP method and path.
+
+**Naming convention**
+
+| Route | Part | Generated name |
+|-------|------|----------------|
+| `POST /products` | request body | `CreateProductsRequest` |
+| `POST /products` | 201 response | `CreateProductsResponse` |
+| `GET /products/{id}` | 200 response | `GetProductsByIdResponse` |
+| `DELETE /products/{id}` | 404 response | `DeleteProductsByIdNotFoundError` |
+| `PATCH /products/{id}` | request body | `UpdateProductsByIdRequest` |
+
+HTTP methods → verbs: `GET → Get`, `POST → Create`, `PUT → Replace`, `PATCH → Update`, `DELETE → Delete`.
+
+Status codes → suffixes: `200/201/204 → Response`, `400 → BadRequestError`, `401 → UnauthorizedError`, `403 → ForbiddenError`, `404 → NotFoundError`, `409 → ConflictError`, `422 → ValidationError`, `429 → RateLimitError`, `500 → InternalError`, `501 → NotImplementedError`, `503 → UnavailableError`. Unknown codes fall back to the number.
+
+**Limitation:** if the same Zod object is used in two different routes, each route names it after itself — you get two identical inline shapes instead of one shared `$ref`. Use Method 2 or 3 to fix this.
+
+---
+
+### Method 2 — Directory / glob auto-discovery (via `modelSchemas`)
+
+Use this when you have schemas shared across multiple routes. Point `modelSchemas` at one or more directories and Bunshot imports every `.ts` file **before** routes are loaded. Any exported Zod schema is registered automatically — same object referenced in multiple routes → same `$ref` in the spec.
+
+**Naming:** export name with the trailing `Schema` suffix stripped (`LedgerItemSchema` → `"LedgerItem"`). Already-registered schemas are never overwritten.
+
+```ts
+// src/schemas/ledgerItem.ts
+import { z } from "zod";
+export const LedgerItemSchema = z.object({ id: z.string(), name: z.string(), amount: z.number() });
+// → auto-registered as "LedgerItem"
+```
+
+```ts
+// src/config/index.ts
+await createServer({
+  routesDir: import.meta.dir + "/routes",
+  modelSchemas: import.meta.dir + "/schemas",  // string shorthand — registration: "auto"
+});
+```
+
+```ts
+// src/routes/ledger.ts  AND  src/routes/ledgerDetail.ts
+import { LedgerItemSchema } from "@schemas/ledgerItem"; // same Zod object instance
+createRoute({ responses: { 200: { content: { "application/json": { schema: LedgerItemSchema } } } } });
+// → $ref: "#/components/schemas/LedgerItem" in both routes
+```
+
+**Multiple directories and glob patterns**
+
+```ts
+modelSchemas: [
+  import.meta.dir + "/schemas",                         // dedicated schemas dir
+  import.meta.dir + "/models",                           // co-located with DB models
+  import.meta.dir + "/services/**/*.schema.ts",          // selective glob
+]
+```
+
+**Full config object** — use when you need to set `registration` or mix paths and globs:
+
+```ts
+modelSchemas: {
+  paths: [import.meta.dir + "/schemas", import.meta.dir + "/models"],
+  registration: "auto",   // default — auto-registers exports with suffix stripping
+}
+```
+
+**`registration: "explicit"`** — files are imported but nothing is auto-registered. Registration is left entirely to `registerSchema` / `registerSchemas` calls inside each file. Use this when you want zero magic and full name control:
+
+```ts
+modelSchemas: { paths: import.meta.dir + "/schemas", registration: "explicit" }
+```
+
+---
+
+### Method 3 — Batch explicit registration (via `registerSchemas`)
+
+`registerSchemas` lets you name a group of schemas all at once. Object keys become the `components/schemas` names; the same object is returned so you can destructure and export normally. No suffix stripping — names are taken as-is.
+
+```ts
+// src/schemas/index.ts
+import { registerSchemas } from "@lastshotlabs/bunshot";
+import { z } from "zod";
+
+export const { LedgerItem, Product, ErrorResponse } = registerSchemas({
+  LedgerItem:    z.object({ id: z.string(), name: z.string(), amount: z.number() }),
+  Product:       z.object({ id: z.string(), price: z.number() }),
+  ErrorResponse: z.object({ error: z.string() }),
+});
+```
+
+Pair with `registration: "explicit"` in `modelSchemas` so the file is imported before routes, or call it inline at the top of any route file — route files are auto-discovered so the top-level call runs before the spec is served.
+
+---
+
+### Method 4 — Single explicit registration (via `registerSchema`)
+
+`registerSchema("Name", schema)` registers one schema and returns it unchanged. Useful for a single shared type (e.g. a common error envelope) or to override the name auto-discovery would generate.
+
+```ts
+// src/schemas/errors.ts
+import { registerSchema } from "@lastshotlabs/bunshot";
+import { z } from "zod";
+
+export const ErrorResponse = registerSchema("ErrorResponse",
+  z.object({ error: z.string() })
+);
+```
+
+Registration is idempotent — calling `registerSchema` on an already-registered schema is a no-op. This means you can safely call it in files that are also covered by `modelSchemas` auto-discovery: whichever runs first wins, and the other is silently skipped.
+
+---
+
+### Priority and interaction
+
+All four methods write to the same process-global registry. The rules are simple:
+
+1. **First write wins** — once a schema has a name, it cannot be renamed.
+2. **`modelSchemas` files are imported before routes**, so explicit calls inside them always take precedence over what `createRoute` would generate for the same object.
+3. **`registerSchema` / `registerSchemas` take precedence over auto-discovery** when they appear at module top level (they run at import time, before `maybeAutoRegister` inspects the export list).
+4. **`createRoute` never overwrites** a schema already in the registry — it only fills gaps.
+
+**Decision guide:**
+
+| Situation | Use |
+|-----------|-----|
+| Route-specific, one-off schema | `createRoute` auto-registration (Method 1) |
+| Shared across routes, happy with suffix-stripped export name | `modelSchemas` auto-discovery (Method 2) |
+| Shared across routes, want explicit names or batch control | `registerSchemas` (Method 3) |
+| Single shared schema or custom name override | `registerSchema` (Method 4) |
+
+**Protected routes**
+
+Use `withSecurity` to declare security schemes on a route without breaking `c.req.valid()` type inference. (Inlining `security` directly in `createRoute({...})` causes TypeScript to collapse the handler's input types to `never`.)
+
+```ts
+import { createRoute, withSecurity } from "@lastshotlabs/bunshot";
+
+router.openapi(
+  withSecurity(
+    createRoute({ method: "get", path: "/me", ... }),
+    { cookieAuth: [] },
+    { userToken: [] }
+  ),
+  async (c) => {
+    const userId = c.get("authUserId"); // fully typed
+  }
+);
+```
+
+Pass each security scheme as a separate object argument. The security scheme names (`cookieAuth`, `userToken`, `bearerAuth`) are registered globally by `createApp`.
+
+**Load order:** By default, routes load in filesystem order. If a route needs to be registered before another (e.g. for Hono's first-match-wins routing), export a `priority` number — lower values load first. Routes without a `priority` load last.
+
+```ts
+// routes/tenants.ts — must match before generic routes
+export const priority = 1;
+export const router = createRouter();
+// ...
+```

package/docs/sections/adding-routes/overview.md

@@ -0,0 +1,23 @@
+## Adding Routes
+
+Drop a file in your `routes/` directory that exports a `router` — routes are auto-discovered via glob. Subdirectories are supported.
+
+```ts
+import { z } from "zod";
+import { createRoute, createRouter } from "@lastshotlabs/bunshot";
+
+export const router = createRouter();
+
+router.openapi(
+  createRoute({
+    method: "get",
+    path: "/hello",
+    responses: {
+      200: { content: { "application/json": { schema: z.object({ message: z.string() }) } }, description: "Hello" },
+    },
+  }),
+  (c) => c.json({ message: "Hello world!" }, 200)
+);
+```
+
+Import `createRoute` from `@lastshotlabs/bunshot` (not `@hono/zod-openapi`) to get automatic OpenAPI schema registration. Four registration methods are available — route-level auto-registration, directory/glob auto-discovery via `modelSchemas`, batch explicit via `registerSchemas`, and single explicit via `registerSchema`. Use `withSecurity` to add auth requirements without breaking type inference.

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

@@ -0,0 +1,456 @@
+## 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
+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
+1. `POST /auth/login` → read `token` from response body
+2. Send `x-user-token: <token>` header on every request
+
+### 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.
+
+```
+GET    /auth/sessions             → [{ sessionId, createdAt, lastActiveAt, expiresAt, ipAddress, userAgent, isActive }]
+DELETE /auth/sessions/:sessionId  → revoke a specific session (other sessions unaffected)
+POST   /auth/logout               → revoke only the current session
+```
+
+Session metadata (IP address, user-agent, timestamps) is persisted even after a session expires when `sessionPolicy.persistSessionMetadata: true` (default). This enables tenant apps to detect logins from novel devices or locations and prompt for MFA or send a security alert.
+
+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
+
+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
+
+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.
+
+```ts
+await createServer({
+  auth: {
+    refreshTokens: {
+      accessTokenExpiry: 900,        // seconds, default: 900 (15 min)
+      refreshTokenExpiry: 2_592_000, // seconds, default: 2_592_000 (30 days)
+      rotationGraceSeconds: 30,      // default: 30 — old token still works briefly after rotation
+    },
+  },
+});
+```
+
+**When not configured**, the existing 7-day JWT behavior is unchanged — fully backward compatible.
+
+#### Endpoints
+
+| Endpoint | Purpose |
+|---|---|
+| `POST /auth/login` | Returns `token` + `refreshToken` |
+| `POST /auth/register` | Returns `token` + `refreshToken` |
+| `POST /auth/refresh` | Rotates refresh token, returns new `token` + `refreshToken` |
+
+#### 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
+
+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.
+
+### MFA / TOTP
+
+Enable multi-factor authentication with TOTP (Google Authenticator, Authy, etc.):
+
+```ts
+await createServer({
+  auth: {
+    mfa: {
+      issuer: "My App",          // shown in authenticator apps (default: app name)
+      algorithm: "SHA1",         // default, most compatible
+      digits: 6,                 // default
+      period: 30,                // seconds, default
+      recoveryCodes: 10,         // number of recovery codes, default: 10
+      challengeTtlSeconds: 300,  // MFA challenge window, default: 5 min
+    },
+  },
+});
+```
+
+Requires `otpauth` peer dependency:
+
+```bash
+bun add otpauth
+```
+
+#### Endpoints
+
+| Endpoint | Auth | Purpose |
+|---|---|---|
+| `POST /auth/mfa/setup` | userAuth | Generate TOTP secret + otpauth URI (for QR code) |
+| `POST /auth/mfa/verify-setup` | userAuth | Confirm with TOTP code, returns recovery codes |
+| `POST /auth/mfa/verify` | none (uses mfaToken) | Complete login after password verified |
+| `DELETE /auth/mfa` | userAuth | Disable all MFA (requires TOTP code) |
+| `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
+
+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
+
+The verify endpoint accepts an optional `method` field (`"totp"` or `"emailOtp"`) to target a specific verification method. When omitted, methods are tried automatically.
+
+**OAuth logins skip MFA** — the OAuth provider is treated as the second factor.
+
+**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
+
+An alternative to TOTP that sends a one-time code to the user's email. Users can enable TOTP, email OTP, or both.
+
+```ts
+await createServer({
+  auth: {
+    mfa: {
+      challengeTtlSeconds: 300,
+      emailOtp: {
+        onSend: async (email, code) => {
+          await sendEmail(email, `Your login code: ${code}`);
+        },
+        codeLength: 6,  // default
+      },
+    },
+  },
+});
+```
+
+#### Endpoints
+
+| Endpoint | Auth | Purpose |
+|---|---|---|
+| `POST /auth/mfa/email-otp/enable` | userAuth | Send verification code to email |
+| `POST /auth/mfa/email-otp/verify-setup` | userAuth | Confirm code, enable email OTP |
+| `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
+
+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
+
+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
+
+- 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
+
+### Account Deletion
+
+Enable `DELETE /auth/me` for user-initiated account deletion:
+
+```ts
+await createServer({
+  auth: {
+    accountDeletion: {
+      onBeforeDelete: async (userId) => {
+        // Throw to abort (e.g., check for active subscription)
+      },
+      onAfterDelete: async (userId) => {
+        // Cleanup: delete S3 files, cancel Stripe, etc.
+        // Runs at execution time — query current state, not a snapshot
+      },
+      queued: false,           // set true for async deletion via BullMQ
+      gracePeriod: 0,          // seconds before queued deletion executes
+      onDeletionScheduled: async (userId, email, cancelToken) => {
+        // Send cancellation email with cancelToken link
+      },
+    },
+  },
+});
+```
+
+#### 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
+
+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`.
+
+### Protecting routes
+
+```ts
+import { userAuth, requireRole, requireVerifiedEmail } from "@lastshotlabs/bunshot";
+
+router.use("/my-route", userAuth);                              // returns 401 if not logged in
+router.use("/admin", userAuth, requireRole("admin"));           // returns 403 if user lacks role
+router.use("/content", userAuth, requireRole("admin", "editor")); // allow either role
+router.use("/dashboard", userAuth, requireVerifiedEmail);       // returns 403 if email not verified
+```
+
+### 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"`).
+
+The schema should include a `roles` column if you plan to use role-based access:
+
+```sql
+-- roles stored as a text array in Postgres
+ALTER TABLE users ADD COLUMN roles text[] NOT NULL DEFAULT '{}';
+```
+
+```ts
+import type { AuthAdapter } from "@lastshotlabs/bunshot";
+import { HttpError } from "@lastshotlabs/bunshot";
+import { db } from "./db";
+import { users } from "./schema";
+import { eq, sql } from "drizzle-orm";
+
+const pgAuthAdapter: AuthAdapter = {
+  async findByEmail(email) {
+    const user = await db.query.users.findFirst({ where: eq(users.email, email) });
+    return user ? { id: user.id, passwordHash: user.passwordHash } : null;
+  },
+  async create(email, passwordHash) {
+    try {
+      const [user] = await db.insert(users).values({ email, passwordHash }).returning({ id: users.id });
+      return { id: user.id };
+    } catch (err: any) {
+      if (/* unique constraint */ err.code === "23505") throw new HttpError(409, "Email already registered");
+      throw err;
+    }
+  },
+  // --- Role methods (optional — only needed if using roles / requireRole) ---
+  async getRoles(userId) {
+    const user = await db.query.users.findFirst({ where: eq(users.id, userId) });
+    return user?.roles ?? [];
+  },
+  async setRoles(userId, roles) { // required if using defaultRole
+    await db.update(users).set({ roles }).where(eq(users.id, userId));
+  },
+  async addRole(userId, role) {
+    await db.update(users)
+      .set({ roles: sql`array_append(roles, ${role})` })
+      .where(eq(users.id, userId));
+  },
+  async removeRole(userId, role) {
+    await db.update(users)
+      .set({ roles: sql`array_remove(roles, ${role})` })
+      .where(eq(users.id, userId));
+  },
+};
+
+await createServer({
+  routesDir: import.meta.dir + "/routes",
+  app: { name: "My App", version: "1.0.0" },
+  auth: {
+    roles: ["admin", "editor", "user"],
+    defaultRole: "user",
+    adapter: pgAuthAdapter,
+  },
+});
+```
+
+The adapter is responsible for:
+- `findByEmail` — return `{ id, passwordHash }` or `null` if not found
+- `create` — insert the user and return `{ id }`, throw `HttpError(409, ...)` on duplicate email
+- `setPassword` _(optional)_ — update the stored password hash for `userId`; implement to enable `POST /auth/set-password`
+- `findOrCreateByProvider` _(optional)_ — required for OAuth social login
+- `linkProvider` _(optional)_ — add a provider identity to an existing user; implement to enable `GET /auth/{provider}/link`
+- `unlinkProvider` _(optional)_ — remove all identities for a provider from a user; implement to enable `DELETE /auth/{provider}/link`
+- `getRoles` _(optional)_ — return the roles assigned to `userId`; implement to enable `requireRole` middleware
+- `setRoles` _(optional)_ — replace all roles; required if using `defaultRole`
+- `addRole` _(optional)_ — add a single role; implement to use `addUserRole`
+- `removeRole` _(optional)_ — remove a single role; implement to use `removeUserRole`
+- `getUser` _(optional)_ — return `{ email?, providerIds?, emailVerified? }` for `userId`; implement to populate `GET /auth/me` (including `googleLinked` and `emailVerified`)
+- `findByIdentifier` _(optional)_ — look up a user by the configured `primaryField` value; implement for non-email primary fields. Falls back to `findByEmail` if absent.
+- `setEmailVerified` _(optional)_ — mark a user as email-verified; implement to support `POST /auth/verify-email`
+- `getEmailVerified` _(optional)_ — return whether a user is email-verified; implement to support the `emailVerification.required` gate and `POST /auth/resend-verification`
+
+Everything else (password hashing, JWT signing, Redis sessions) is handled by the package.
+
+### 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:
+
+| Endpoint | Key | Counts | Default limit |
+|---|---|---|---|
+| `POST /auth/login` | identifier (email/username/phone) | **Failures only** — reset on success | 10 failures / 15 min |
+| `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/reset-password` | IP address | Every attempt | 10 / 15 min |
+
+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
+
+```ts
+await createServer({
+  auth: {
+    rateLimit: {
+      login:              { windowMs: 10 * 60 * 1000, max: 5 }, // stricter: 5 failures / 10 min
+      register:           { windowMs: 60 * 60 * 1000, max: 3 },
+      verifyEmail:        { windowMs: 15 * 60 * 1000, max: 10 }, // leave at default
+      resendVerification: { windowMs: 60 * 60 * 1000, max: 2 },
+      store: "redis",   // default when Redis is enabled — shared across all server instances
+    },
+  },
+});
+```
+
+#### Manually clearing a limit (admin unlock)
+
+If a legitimate user gets locked out, call `bustAuthLimit` with the same key format the limiter uses:
+
+```ts
+import { bustAuthLimit } from "@lastshotlabs/bunshot";
+
+// Admin route: POST /admin/unblock-login
+router.post("/admin/unblock-login", userAuth, requireRole("admin"), async (c) => {
+  const { identifier } = await c.req.json();
+  await bustAuthLimit(`login:${identifier}`);
+  return c.json({ message: "Login limit cleared" });
+});
+```
+
+Key formats: `login:{identifier}`, `register:{ip}`, `verify:{ip}`, `resend:{userId}`.
+
+#### 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`.
+
+```ts
+import { trackAttempt, isLimited, bustAuthLimit } from "@lastshotlabs/bunshot";
+
+// trackAttempt — increments the counter and returns true if now over the limit
+// isLimited    — checks without incrementing (read-only)
+// bustAuthLimit — resets a key (e.g. on success or admin unlock)
+
+router.post("/api/submit", async (c) => {
+  const ip = c.req.header("x-forwarded-for") ?? "unknown";
+  const key = `submit:${ip}`;
+
+  if (await trackAttempt(key, { windowMs: 60 * 1000, max: 5 })) {
+    return c.json({ error: "Too many requests" }, 429);
+  }
+
+  // ... handle request
+  return c.json({ ok: true });
+});
+```
+
+Use `isLimited` when you want to check the current state without counting the request itself — for example, to gate an expensive pre-check before the attempt is registered:
+
+```ts
+if (await isLimited(key, opts)) {
+  return c.json({ error: "Too many requests" }, 429);
+}
+```
+
+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
+
+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
+
+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
+
+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.).
+
+Bots that rotate IPs but use the same HTTP client (e.g. Python `requests`, `curl`, a headless browser) produce the same fingerprint and share a rate-limit bucket regardless of their source IP. Real browser sessions produce a different fingerprint from CLI tools, so they don't interfere with each other.
+
+```ts
+await createServer({
+  security: {
+    rateLimit: { windowMs: 60_000, max: 100 }, // applies to both IP and fingerprint buckets
+    botProtection: {
+      fingerprintRateLimit: true,
+    },
+  },
+});
+```
+
+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
+
+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.
+
+```ts
+await createServer({
+  security: {
+    botProtection: {
+      blockList: [
+        "198.51.100.0/24",   // IPv4 CIDR
+        "203.0.113.42",      // exact IPv4
+        "2001:db8::1",       // exact IPv6
+      ],
+    },
+  },
+});
+```
+
+Both options can be combined. The middleware order is: blocklist → IP rate limit → fingerprint rate limit.
+
+#### Apply `botProtection` to individual routes
+
+`botProtection` is also exported for per-route use:
+
+```ts
+import { botProtection } from "@lastshotlabs/bunshot";
+
+router.use("/api/submit", botProtection({ blockList: ["198.51.100.0/24"] }));
+```
+
+---
+
+### 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)
+await fetch("/auth/set-password", {
+  method: "POST",
+  headers: { "Content-Type": "application/json", "x-user-token": token },
+  body: JSON.stringify({ password: "mynewpassword" }),
+});
+```
+
+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`.
+
+To support it with a custom adapter:
+
+```ts
+const myAdapter: AuthAdapter = {
+  findByEmail: ...,
+  create: ...,
+  async setPassword(userId, passwordHash) {
+    await db.update(users).set({ passwordHash }).where(eq(users.id, userId));
+  },
+};
+```

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

@@ -0,0 +1,10 @@
+## 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.
+
+Protect routes with `userAuth`, `requireRole("admin")`, and `requireVerifiedEmail` middleware.