@lastshotlabs/bunshot 0.0.21 → 0.0.27

package/docs/sections/auth-security-examples/full.md

@@ -0,0 +1,388 @@
+### Auth Security Examples
+
+Five reference configurations covering common security postures. Each is a real `createServer` call you can adapt — not a checklist of options to mix and match blindly, since the right combination depends on what you're building.
+
+---
+
+#### Fintech / Healthcare — maximum security
+
+Strict everything. MFA is mandatory for every user, sessions are short, passwords must be strong, and the app defends against distributed brute-force from day one.
+
+```ts
+await createServer({
+  auth: {
+    passwordPolicy: {
+      minLength: 12,
+      requireLetter: true,
+      requireDigit: true,
+      requireSpecial: true,    // forces non-alphanumeric character
+    },
+    mfa: {
+      issuer: "FinApp",
+      required: true,          // 403 MFA_SETUP_REQUIRED until user enrolls
+      recoveryCodes: 10,
+      challengeTtlSeconds: 180, // 3-minute window to complete MFA
+    },
+    emailVerification: {
+      required: true,           // can't log in until email is verified
+      onSend: async (email, token) => {
+        await mailer.send(email, `Verify your email: https://app.com/verify?t=${token}`);
+      },
+      tokenExpiry: 3600,        // 1-hour window to verify (not 24h)
+    },
+    passwordReset: {
+      tokenExpiry: 1800,        // 30-minute reset window (tighter than default 1h)
+      onSend: async (email, token) => {
+        await mailer.send(email, `Reset: https://app.com/reset?t=${token}`);
+      },
+    },
+    refreshTokens: {
+      accessTokenExpiry: 900,       // 15-minute access tokens
+      refreshTokenExpiry: 604_800,  // 7-day refresh (not 30 — re-auth weekly)
+      rotationGraceSeconds: 30,
+    },
+    sessionPolicy: {
+      maxSessions: 3,               // limit concurrent devices
+      trackLastActive: true,
+      persistSessionMetadata: true,
+      includeInactiveSessions: true, // full device history visible to user
+    },
+    rateLimit: {
+      login:    { windowMs: 15 * 60 * 1000, max: 5  },  // 5 failures / 15 min
+      register: { windowMs: 60 * 60 * 1000, max: 3  },  // 3 signups / hour per IP
+    },
+  },
+  security: {
+    cors: ["https://app.com"],
+    trustProxy: 1,               // one load balancer between internet and app
+    csrf: { enabled: true },     // cookie-based auth — CSRF protection required
+    rateLimit: { windowMs: 60_000, max: 60 }, // tighter global cap
+    botProtection: {
+      fingerprintRateLimit: true, // IP-rotators share a rate-limit bucket
+      blockList: [
+        "198.51.100.0/24",        // known datacenter / proxy ranges
+        "203.0.113.0/24",
+      ],
+    },
+    signing: {
+      // Session binding — ties each session to the IP + UA it was created with.
+      // A hijacked token presented from a different IP/UA is rejected outright.
+      sessionBinding: {
+        fields: ["ip", "ua"],
+        onMismatch: "reject",     // 401 FINGERPRINT_MISMATCH — strict is appropriate here
+      },
+      // Require server-to-server API clients to HMAC-sign requests.
+      // Covers internal microservice calls and any non-browser client.
+      requestSigning: {
+        tolerance: 60_000,        // 1-minute window (tighter than default 5 min)
+      },
+    },
+  },
+});
+```
+
+**Key decisions:**
+- `mfa.required: true` — unenrolled users are blocked from service endpoints until they complete setup. OAuth users are also affected.
+- 7-day refresh tokens instead of 30-day — users re-authenticate weekly, which limits the blast radius if a refresh token is stolen.
+- `includeInactiveSessions: true` — lets users see a full sign-in history and spot unauthorized access the way Google and Meta do.
+- `csrf.enabled` — this app uses cookie auth; CSRF is a real threat.
+- Dual-keyed forgot-password rate limiting (IP + email) is automatic — the config above just tightens the window.
+- `sessionBinding` with `onMismatch: "reject"` — a session token presented from a different IP or user-agent is refused, not just silently treated as unauthenticated. Appropriate here; use `"log-only"` first if rolling out to an existing user base with mobile users on dynamic IPs.
+- `requestSigning` — server-to-server calls from internal services must HMAC-sign the canonical request. Prevents replay attacks and body substitution in transit.
+
+---
+
+#### Consumer SaaS — social login with verification
+
+Google and GitHub OAuth alongside credential login. Email must be verified before users can access the app. Opt-in MFA (users choose whether to enable it). Long-lived refresh tokens for a smooth "stay logged in" experience.
+
+```ts
+await createServer({
+  auth: {
+    roles: ["admin", "member"],
+    defaultRole: "member",
+    emailVerification: {
+      required: true,
+      onSend: async (email, token) => {
+        await resend.emails.send({
+          to: email,
+          subject: "Confirm your email",
+          html: `<a href="https://myapp.com/verify?token=${token}">Verify</a>`,
+        });
+      },
+    },
+    passwordReset: {
+      onSend: async (email, token) => {
+        await resend.emails.send({
+          to: email,
+          subject: "Reset your password",
+          html: `<a href="https://myapp.com/reset?token=${token}">Reset password</a>`,
+        });
+      },
+    },
+    mfa: {
+      issuer: "MySaaS",
+      // required not set — users opt in via account settings
+    },
+    refreshTokens: {
+      accessTokenExpiry: 900,        // 15 min
+      refreshTokenExpiry: 2_592_000, // 30 days — "stay logged in"
+    },
+    sessionPolicy: {
+      trackLastActive: true,         // sliding sessions via refresh
+    },
+    oauth: {
+      postRedirect: "/dashboard",
+      allowedRedirectUrls: ["https://myapp.com"],
+      providers: {
+        google: {
+          clientId: process.env.GOOGLE_CLIENT_ID!,
+          clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+          redirectUri: "https://myapp.com/auth/google/callback",
+        },
+        github: {
+          clientId: process.env.GITHUB_CLIENT_ID!,
+          clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+          redirectUri: "https://myapp.com/auth/github/callback",
+        },
+      },
+    },
+  },
+  security: {
+    cors: ["https://myapp.com", "https://staging.myapp.com"],
+    trustProxy: 1,
+    csrf: { enabled: true },
+    botProtection: {
+      fingerprintRateLimit: true,
+    },
+    signing: {
+      // Signed cursors — prevents clients from forging pagination cursors to
+      // access arbitrary pages. Tampered cursors are rejected with invalidCursor.
+      cursors: true,
+      // Hash idempotency keys before storage so users can't enumerate each
+      // other's pending operations by guessing short numeric keys.
+      idempotencyKeys: true,
+      // Presigned download URLs — lets the browser download private files
+      // directly without routing bytes through the API server.
+      presignedUrls: { defaultExpiry: 3600 },
+    },
+  },
+});
+```
+
+**Key decisions:**
+- OAuth users who share an email with a credential account get a `409` on login with a redirect to `?error=...`. They must sign in with their password and explicitly link the OAuth provider — email matching is never done automatically to prevent account takeover.
+- `allowedRedirectUrls` prevents open-redirect abuse if a crafted `postRedirect` value is injected.
+- MFA is opt-in, so the `mfa` block is present to enable the setup routes even though `required` is false. Users can enable it from their account page via `POST /auth/mfa/setup`.
+- 30-day refresh tokens with `trackLastActive` give users a smooth experience without requiring them to log in every week.
+- `cursors: true` — cursor-based pagination is used for activity feeds and search results; signing prevents users from skipping to arbitrary offsets by hand-crafting cursor values.
+- `idempotencyKeys: true` + `idempotent()` middleware on payment/order routes — mount `idempotent()` on routes where duplicate submission is a real risk (checkout, subscription changes). The HMAC option prevents key enumeration if users pick short keys like `"order-1"`.
+- `presignedUrls` — `GET /uploads/presign/:key` returns a time-limited HMAC URL that the browser can use to download directly from S3 (or your storage backend) without a round-trip through the API on every byte.
+
+---
+
+#### Internal admin panel — re-authentication on expiry
+
+Staff tool with two roles, MFA enforced for everyone, and no refresh tokens. When the access token expires, the session ends and the user must authenticate again. Full device history is kept for auditing.
+
+```ts
+await createServer({
+  auth: {
+    roles: ["superadmin", "admin", "viewer"],
+    defaultRole: "viewer",
+    mfa: {
+      issuer: "Admin Panel",
+      required: true,
+      challengeTtlSeconds: 120, // 2-minute window for MFA code
+    },
+    passwordPolicy: {
+      minLength: 14,
+      requireLetter: true,
+      requireDigit: true,
+      requireSpecial: true,
+    },
+    sessionPolicy: {
+      maxSessions: 2,               // work machine + phone; third device evicts oldest
+      trackLastActive: true,
+      persistSessionMetadata: true,
+      includeInactiveSessions: true, // audit trail of all sign-ins
+    },
+    rateLimit: {
+      login: { windowMs: 15 * 60 * 1000, max: 5 },
+    },
+    // No refreshTokens — 7-day JWTs, then re-authenticate.
+    // For a stricter posture: add refreshTokens with a 4h refreshTokenExpiry.
+    //
+    // No oauth — staff use internal credentials only.
+    // No emailVerification — IT provisions accounts directly.
+  },
+  security: {
+    cors: ["https://admin.internal.myapp.com"],
+    trustProxy: 1,
+    csrf: { enabled: true },
+    rateLimit: { windowMs: 60_000, max: 30 }, // low — this is not a public endpoint
+  },
+});
+```
+
+**Key decisions:**
+- No `refreshTokens` — when the token expires, the user re-enters credentials. This matches the mental model of a work session and limits how long a compromised token stays valid.
+- `maxSessions: 2` — a staff member logging in from a third device quietly evicts the oldest session. Combined with `includeInactiveSessions: true` and email alerts in `onBeforeDelete`, this can surface unusual access.
+- `requireRole.global("admin")` or `requireRole.global("superadmin")` on sensitive routes — tenant-scoped roles never satisfy a global check.
+
+---
+
+#### Native mobile / server-to-server — no cookies, no CSRF
+
+For **native iOS/Android apps and server-to-server API clients** that pass the JWT in the `x-user-token` header and never touch cookies. CSRF is irrelevant here because the attack requires a browser to silently attach credentials — custom headers can't be forged that way. Phone numbers as the primary identifier.
+
+> **Not for browser SPAs.** If your client is a browser app (React, Vue, etc.), see the note after this example — even header-based browser clients need specific CORS origins.
+
+```ts
+await createServer({
+  auth: {
+    primaryField: "phone",     // body field is "phone" instead of "email"
+    passwordPolicy: {
+      minLength: 8,
+      requireDigit: true,
+    },
+    mfa: {
+      issuer: "MyApp",
+      emailOtp: {
+        onSend: async (email, code) => {
+          // or route to an SMS gateway keyed by the user's phone number
+          await mailer.send(email, `Your login code: ${code}`);
+        },
+        codeLength: 6,
+      },
+    },
+    refreshTokens: {
+      accessTokenExpiry: 900,        // 15 min
+      refreshTokenExpiry: 2_592_000, // 30 days
+      rotationGraceSeconds: 60,      // more generous — mobile networks are lossy
+    },
+    sessionPolicy: {
+      maxSessions: 5,  // phone, tablet, desktop, smart TV, etc.
+    },
+    // No emailVerification — phone is the primary field; email may not be present.
+    // No csrf — header-based auth is immune to CSRF.
+  },
+  security: {
+    cors: "*",        // safe: native apps don't run in a browser, CORS has no effect
+    trustProxy: 1,
+    botProtection: {
+      fingerprintRateLimit: true,
+      blockList: ["198.51.100.0/24"],
+    },
+    rateLimit: { windowMs: 60_000, max: 200 }, // higher cap for mobile traffic bursts
+  },
+});
+```
+
+**Key decisions:**
+- `primaryField: "phone"` — register/login bodies use `{ phone, password }`. Email verification and password reset routes are not mounted (they require `primaryField: "email"`).
+- `cors: "*"` is safe for native apps because CORS is a browser enforcement mechanism — it has no meaning outside of a browser context. A native app making HTTP requests ignores CORS entirely.
+- `rotationGraceSeconds: 60` — mobile connections drop mid-request more often than browser connections. A longer grace window prevents legitimate refresh retries from triggering theft detection.
+- No `csrf` block — CSRF attacks require the browser to automatically attach credentials (cookies). Since this API uses `x-user-token`, there's nothing to forge.
+
+**Adding session binding to mobile apps:** Mobile users frequently switch between Wi-Fi and LTE, so IP-based binding causes false rejections. If you want session binding, use UA only and start with `"log-only"` to measure false-positive rates before switching to `"reject"`:
+
+```ts
+signing: {
+  sessionBinding: {
+    fields: ["ua"],           // IP excluded — mobile IPs change too often
+    onMismatch: "log-only",   // measure first, then tighten to "unauthenticate"
+  },
+},
+```
+
+##### Browser SPA with header-based auth
+
+If your client is a browser app that uses `x-user-token` instead of cookies — common with React/Vue SPAs that manage tokens in memory — the auth config is the same but CORS must be locked down:
+
+```ts
+security: {
+  cors: ["https://myapp.com"],  // NOT "*" — browsers enforce CORS even for header auth
+  trustProxy: 1,
+  // No csrf — custom headers can't be forged cross-origin without a CORS allowlist,
+  // so CSRF protection is still not needed even in the browser.
+  botProtection: {
+    fingerprintRateLimit: true,
+  },
+},
+```
+
+The reason CSRF is still not needed: a malicious page can try to make a cross-origin `POST` to your API, but the browser blocks requests with custom headers (`x-user-token`) unless the server's CORS policy explicitly allows the origin. Since `cors` is locked to `["https://myapp.com"]`, any request from a different origin is rejected before it reaches your handler. The CSRF double-submit pattern defends against cookie theft specifically; `x-user-token` doesn't have that vulnerability.
+
+**What to avoid:** storing the token in `localStorage` is convenient but exposes it to XSS. Storing it in a `httpOnly` cookie eliminates XSS risk but brings CSRF back — at which point the [Consumer SaaS](#consumer-saas--social-login-with-verification) or [Fintech](#fintech--healthcare--maximum-security) example is the right template instead.
+
+---
+
+#### Local development — no external dependencies
+
+Everything in-memory. No Redis, no MongoDB, no Docker required. Spin up with `bun run dev` and iterate immediately. All data is lost on restart, which is fine for local work.
+
+```ts
+await createServer({
+  routesDir: import.meta.dir + "/routes",
+  db: {
+    mongo: false,
+    redis: false,
+    auth: "memory",
+    sessions: "memory",
+  },
+  auth: {
+    roles: ["admin", "user"],
+    defaultRole: "user",
+    passwordPolicy: {
+      minLength: 1,         // any password works — don't slow down local testing
+      requireLetter: false,
+      requireDigit: false,
+      requireSpecial: false,
+    },
+    rateLimit: {
+      login:    { windowMs: 60_000, max: 10_000 }, // effectively unlimited
+      register: { windowMs: 60_000, max: 10_000 },
+    },
+    // To test email flows locally, add emailVerification / passwordReset with
+    // an onSend that logs the token to the console instead of sending a real email:
+    //
+    // emailVerification: {
+    //   onSend: async (email, token) => console.log("[verify]", email, token),
+    // },
+  },
+  security: {
+    cors: "*",
+    bearerAuth: false, // no API key required
+  },
+});
+```
+
+**Key decisions:**
+- `db: { mongo: false, redis: false }` is the key line — it disables all auto-connect calls, so no connection errors on startup.
+- `auth: "memory"` and `sessions: "memory"` use in-memory Maps. Import `clearMemoryStore()` from the package in your tests to reset state between test runs.
+- Rate limits are set to 10 000 per minute rather than disabled entirely so the rate-limit code path is exercised (avoiding "works in dev, breaks in prod" surprises). The limit is just high enough that it never triggers during normal use.
+- If you want to test email flows locally without a real provider, the commented-out block shows how to log the token to the console — paste it into the browser or a `curl` call directly.
+
+---
+
+## JWT Claims (iss, aud, iat)
+
+By default Bunshot tokens include `sub`, `sid`, and `exp`. Enable standard JWT claims for multi-service deployments or compliance requirements:
+
+```ts
+createApp({
+  auth: {
+    jwt: {
+      issuer: "https://auth.yourapp.com",   // iss claim — who issued the token
+      audience: "your-api",                 // aud claim — who the token is for
+    },
+  },
+});
+```
+
+When configured:
+- **`iss`** and **`aud`** are included in every token and validated on every verification. Tokens from a different issuer or intended for a different audience are rejected.
+- **`iat`** (issued-at) is always included once JWT config is set. Use it to detect token reuse or implement absolute expiry windows.
+
+This is recommended for fintech and multi-tenant deployments where tokens from one service should not be accepted by another.

package/docs/sections/authentication/full.md

@@ -0,0 +1,130 @@
+## Authentication
+
+Bunshot ships a complete auth system: credential login, OAuth social providers (Google, Apple, Microsoft, GitHub), multi-factor authentication (TOTP, email OTP, WebAuthn), session management, roles, groups, and security hardening (CSRF, rate limiting, bot protection). Everything is opt-in — add only what your app needs.
+
+### How it works
+
+Auth has two independent layers you configure separately:
+
+| Layer | What it stores | Configured via | Default |
+|---|---|---|---|
+| **Auth adapter** | Users, passwords, roles | `auth.adapter` or `db.auth` | MongoDB (`mongoAuthAdapter`) |
+| **Session store** | Active sessions (JWT metadata) | `db.sessions` | Redis |
+
+When a user logs in, the auth adapter verifies their credentials and the session store creates a record for the new session. The JWT embeds a `sessionId` claim that ties the token to that record — revoking a session immediately invalidates its token even before the JWT expires.
+
+### Minimum working setup
+
+Enable auth by passing an `auth` block. The routes are mounted automatically.
+
+```ts
+await createServer({
+  routesDir: import.meta.dir + "/routes",
+  auth: {
+    roles: ["admin", "user"],
+    defaultRole: "user",
+  },
+});
+```
+
+This mounts `POST /auth/register`, `POST /auth/login`, `POST /auth/logout`, `GET /auth/me`, and the session management endpoints. Users are stored in MongoDB, sessions in Redis.
+
+**Environment variables required:**
+
+```bash
+MONGO_URI_DEV=mongodb://localhost:27017/myapp
+REDIS_URL_DEV=redis://localhost:6379
+JWT_SECRET_DEV=at-least-32-characters-long-secret
+```
+
+### Choosing a store
+
+| Setup | `db.auth` | `db.sessions` | When to use |
+|---|---|---|---|
+| Default (Mongo + Redis) | `"mongo"` | `"redis"` | Production with both services |
+| Mongo only | `"mongo"` | `"mongo"` | When Redis is unavailable |
+| SQLite | `"sqlite"` | `"sqlite"` | Lightweight deploys, embedded DBs |
+| Memory | `"memory"` | `"memory"` | Tests, local dev — lost on restart |
+
+```ts
+// MongoDB sessions instead of Redis
+await createServer({
+  db: { redis: false, sessions: "mongo" },
+  auth: { /* ... */ },
+});
+
+// SQLite — single file, no external services
+await createServer({
+  db: { mongo: false, redis: false, sqlite: import.meta.dir + "/data.db", auth: "sqlite", sessions: "sqlite" },
+  auth: { /* ... */ },
+});
+
+// In-memory — great for tests
+await createServer({
+  db: { mongo: false, redis: false, auth: "memory", sessions: "memory" },
+  auth: { /* ... */ },
+});
+```
+
+### Protecting routes
+
+```ts
+import { userAuth, requireRole, requireVerifiedEmail } from "@lastshotlabs/bunshot";
+
+router.use("/me",       userAuth);                               // 401 if not logged in
+router.use("/admin",    userAuth, requireRole("admin"));         // 403 if wrong role
+router.use("/content",  userAuth, requireRole("admin", "editor")); // either role passes
+router.use("/settings", userAuth, requireVerifiedEmail);         // 403 if email unverified
+```
+
+### Feature map
+
+Everything beyond basic credential login is opt-in:
+
+| Feature | How to enable | Docs |
+|---|---|---|
+| Email verification | `auth.emailVerification` | [Auth Flow](#auth-flow) |
+| Password reset | `auth.passwordReset` | [Auth Flow](#auth-flow) |
+| Refresh tokens | `auth.refreshTokens` | [Auth Flow](#auth-flow) |
+| MFA (TOTP, email OTP, WebAuthn) | `auth.mfa` | [Auth Flow](#auth-flow) |
+| Social login (OAuth) | `auth.oauth.providers` | [Social Login](#social-login-oauth) |
+| Roles & groups | `auth.roles`, `groups` | [Roles](#roles) |
+| CSRF protection | `security.csrf` | [Auth Flow](#auth-flow) |
+| Bot protection | `security.botProtection` | [Auth Flow](#auth-flow) |
+| Account deletion | `auth.accountDeletion` | [Auth Flow](#auth-flow) |
+| Custom user store | `auth.adapter` | [Auth Flow](#auth-flow) |
+
+### Custom auth adapter
+
+The default adapter stores users in MongoDB. Pass `auth.adapter` to use any other store — Postgres, SQLite, an external identity provider, etc. Only implement the methods your app uses:
+
+```ts
+import type { AuthAdapter } from "@lastshotlabs/bunshot";
+
+const myAdapter: AuthAdapter = {
+  async findByEmail(email) {
+    const user = await db.query("SELECT id, passwordHash FROM users WHERE email = $1", [email]);
+    return user ?? null;
+  },
+  async create(email, passwordHash) {
+    const [user] = await db.query(
+      "INSERT INTO users (email, passwordHash) VALUES ($1, $2) RETURNING id",
+      [email, passwordHash]
+    );
+    return { id: user.id };
+  },
+  async getRoles(userId) {
+    const user = await db.query("SELECT roles FROM users WHERE id = $1", [userId]);
+    return user?.roles ?? [];
+  },
+  async setRoles(userId, roles) {
+    await db.query("UPDATE users SET roles = $2 WHERE id = $1", [userId, roles]);
+  },
+};
+
+await createServer({
+  auth: { adapter: myAdapter, roles: ["admin", "user"], defaultRole: "user" },
+});
+```
+
+The full adapter interface and all optional methods (OAuth, MFA, tenant roles, groups, etc.) are covered in [Auth Flow](#auth-flow).

package/docs/sections/authentication/overview.md

@@ -0,0 +1,5 @@
+## Authentication
+
+Bunshot ships a complete auth system: credential login, OAuth social providers (Google, Apple, Microsoft, GitHub), MFA (TOTP, email OTP, WebAuthn), session management, roles & groups, and security hardening (CSRF, rate limiting, bot protection). Everything is opt-in and configurable.
+
+Auth has two independently configurable layers: the **auth adapter** (where users and passwords are stored — MongoDB by default, or SQLite/memory/custom) and the **session store** (where active sessions live — Redis by default, or MongoDB/SQLite/memory). Sessions are JWT-backed with a `sessionId` claim, so revoking a session invalidates the token immediately even before it expires. Protect routes with `userAuth`, `requireRole`, and `requireVerifiedEmail` middleware.

package/docs/sections/cli/full.md

@@ -27,4 +27,16 @@ my-app/
   .env                  # environment variables template
 ```
 
-Path aliases like `@config/*`, `@lib/*`, `@middleware/*`, `@models/*`, `@routes/*`, `@services/*`, and `@workers/*` are set up automatically in `tsconfig.json`.
+Path aliases like `@config/*`, `@lib/*`, `@middleware/*`, `@models/*`, `@routes/*`, `@services/*`, and `@workers/*` are set up automatically in `tsconfig.json`.
+
+After the database setup, the CLI prompts for an **auth security posture**. You can either pick a preset (one question) or configure features step by step:
+
+**Presets:**
+- **Web app / SaaS** — CSRF protection, refresh tokens, bot-fingerprint rate limiting. Includes commented-out stubs for email verification, password reset, and MFA.
+- **Internal / admin** — MFA required for all users, strict password policy (14+ chars), low login rate limits, tight session cap.
+- **Mobile / API only** — No CSRF, open CORS, long-lived refresh tokens with rotation grace window.
+- **Dev / prototype** — Permissive password policy, very high rate limits, no bearer auth guard.
+
+**Step by step** — choose individual features: password policy, email verification, password reset, refresh tokens, MFA (none / optional / required), CSRF, and OAuth providers (Google, GitHub, Apple, Microsoft).
+
+The selected posture is printed in the end-of-run summary and reflected directly in the generated `src/config/index.ts`.

package/docs/sections/configuration/full.md

@@ -125,6 +125,23 @@ await createServer({
     },
   },
 
+  // Validation error formatting
+  validation: {
+    // Custom formatter for Zod validation errors. Receives issues + requestId, returns JSON body.
+    // Default produces: { error: "msg1, msg2", details: [{ path, message }], requestId }
+    formatError: (issues, requestId) => ({
+      errors: issues.map((i) => ({ field: i.path.join("."), message: i.message })),
+      requestId,
+    }),
+  },
+
+  // API versioning — isolates routes into per-version OpenAPI specs
+  versioning: {
+    versions: ["v1", "v2"],    // subdirectories under routesDir (routes/v1/, routes/v2/)
+    defaultVersion: "v2",      // /docs and /openapi.json redirect here (default: last in array)
+    sharedDir: "shared",       // routes/shared/ — mounted on all versions, unprefixed schemas (default: "shared", false to disable)
+  },
+
   // Extra middleware injected after identify, before route matching
   middleware: [],
 

package/docs/sections/configuration/overview.md

@@ -13,5 +13,6 @@
 | `jobs` | Job status REST endpoint config |
 | `ws` | WebSocket handler and upgrade overrides |
 | `middleware` | Extra global middleware array |
+| `validation` | Zod validation error formatting (`formatError` callback) |
 | `modelSchemas` | Schema auto-discovery paths |
 | `port`, `workersDir`, `enableWorkers` | Server options |

package/docs/sections/exports/full.md

@@ -17,7 +17,21 @@ import {
   // WebSocket
   websocket, createWsUpgradeHandler, publish,
   subscribe, unsubscribe, getSubscriptions, handleRoomActions,
-  getRooms, getRoomSubscribers,
+  getRooms, getRoomSubscribers, setPresenceEnabled,
+
+  // WebSocket — Heartbeat
+  registerSocket, deregisterSocket, handlePong,
+  startHeartbeat, stopHeartbeat, clearHeartbeatState,
+  type HeartbeatConfig,
+
+  // WebSocket — Presence
+  trackSocket, untrackSocket, addPresence, removePresence, cleanupPresence,
+  getRoomPresence, getUserPresence, clearPresenceStore,
+
+  // WebSocket — Message Persistence
+  persistMessage, getMessageHistory, configureRoom,
+  setWsMessageStore, setWsMessageDefaults, clearWsMessageMemoryStore,
+  type StoredMessage, type WsMessageStore, type WsMessageDefaults, type RoomPersistenceConfig,
 
   // Auth utilities
   signToken, verifyToken,
@@ -51,17 +65,30 @@ import {
   requireRole,                                    // role-based access control (tenant-aware)
   requireVerifiedEmail,                           // blocks unverified email addresses
   cacheResponse, bustCache, bustCachePattern, setCacheStore,  // response caching (tenant-namespaced)
+  webhookAuth,                                    // HMAC signature verification for incoming webhooks
+  type WebhookAuthOptions, type WebhookTimestampOptions,
 
-  // Crypto utilities
+  // Crypto / HMAC utilities
   timingSafeEqual,                                  // constant-time string comparison for secrets/hashes
   sha256,                                           // SHA-256 hash helper
+  hmacSign, hmacVerify,                             // low-level HMAC-SHA256 primitives (key rotation supported)
+  signCookieValue, verifyCookieValue,               // signed cookie values (tamper-proof)
+  signCursor, verifyCursor,                         // signed pagination cursors
+  createPresignedUrl, verifyPresignedUrl,           // stateless HMAC presigned URLs
+  idempotent, setIdempotencyStore, clearIdempotencyMemoryStore, // idempotency deduplication
+  type IdempotencyOptions,
+  requireSignedRequest,                             // middleware: require HMAC-signed requests
+  type RequestSigningOptions,
+  maybeSignCursor,                                  // sign a cursor if signing.cursors is enabled
 
   // IP / proxy utilities
   getClientIp,                                      // centralized IP extraction — respects security.trustProxy setting
   setTrustProxy,                                    // configure trust level (called automatically by createApp)
 
   // Utilities
-  HttpError, log, validate, createRouter, createRoute,
+  HttpError, ValidationError,                     // ValidationError extends HttpError, carries ZodIssue[]
+  defaultValidationErrorFormatter,               // default { error, details, requestId } shape
+  log, validate, createRouter, createRoute,
   registerSchema, registerSchemas,                // named OpenAPI schema registration
   zodToMongoose,                                  // Zod → Mongoose schema conversion
   createDtoMapper,                                // DB document → API DTO mapper factory
@@ -71,9 +98,13 @@ import {
   // Constants
   COOKIE_TOKEN, HEADER_USER_TOKEN,
   COOKIE_REFRESH_TOKEN, HEADER_REFRESH_TOKEN,     // refresh token cookie/header names
+  HEADER_IDEMPOTENCY_KEY,                         // "idempotency-key"
+  HEADER_SIGNATURE, HEADER_TIMESTAMP,             // request signing header names
 
   // Types
   type AppEnv, type AppVariables,
+  type ValidationErrorFormatter, type DefaultValidationErrorBody, type ValidationErrorDetail,
+  type ValidationConfig,
   type CreateServerConfig, type CreateAppConfig, type ModelSchemasConfig,
   type DbConfig, type AppMeta, type AuthConfig, type OAuthConfig, type SecurityConfig,
   type PrimaryField, type EmailVerificationConfig, type PasswordResetConfig,