@lastshotlabs/bunshot 0.0.13 → 0.0.18

package/docs/sections/configuration/full.md

@@ -0,0 +1,155 @@
+## Configuration
+
+```ts
+await createServer({
+  // Required
+  routesDir: import.meta.dir + "/routes",
+
+  // Shared schemas (imported before routes; see "Shared schemas across routes" above)
+  modelSchemas: import.meta.dir + "/schemas",   // string shorthand — registration: "auto"
+  // modelSchemas: [dir + "/schemas", dir + "/models"],              // multiple dirs
+  // modelSchemas: { paths: dir + "/schemas", registration: "explicit" }, // full object
+
+  // App metadata (shown in root endpoint + OpenAPI docs)
+  app: {
+    name: "My App",      // default: "Bun Core API"
+    version: "1.0.0",   // default: "1.0.0"
+  },
+
+  // Auth, roles, and OAuth
+  auth: {
+    enabled: true,                          // default: true — set false to disable /auth/* routes
+    adapter: pgAuthAdapter,                 // custom adapter — overrides db.auth (use for Postgres etc.)
+    roles: ["admin", "editor", "user"],     // valid roles — required to use requireRole
+    defaultRole: "user",                    // assigned to every new user on /auth/register
+    primaryField: "email",                  // default: "email" — use "username" or "phone" to change the login identifier
+    emailVerification: {                    // optional — only active when primaryField is "email"
+      required: true,                       // default: false (soft gate) — set true to block login until verified
+      tokenExpiry: 60 * 60,                 // default: 86400 (24 hours) — token TTL in seconds
+      onSend: async (email, token) => {     // called after registration and resend — use any email provider
+        await resend.emails.send({ to: email, subject: "Verify your email", text: `Token: ${token}` });
+      },
+    },
+    passwordReset: {                        // optional — only active when primaryField is "email"
+      tokenExpiry: 60 * 60,                 // default: 3600 (1 hour) — token TTL in seconds
+      onSend: async (email, token) => {     // called by POST /auth/forgot-password — use any email provider
+        await resend.emails.send({ to: email, subject: "Reset your password", text: `Token: ${token}` });
+      },
+    },
+    rateLimit: {                            // optional — built-in auth endpoint rate limiting
+      login:              { windowMs: 15 * 60 * 1000, max: 10 }, // default: 10 failures / 15 min
+      register:           { windowMs: 60 * 60 * 1000, max: 5  }, // default: 5 attempts / hour (per IP)
+      verifyEmail:        { windowMs: 15 * 60 * 1000, max: 10 }, // default: 10 attempts / 15 min (per IP)
+      resendVerification: { windowMs: 60 * 60 * 1000, max: 3  }, // default: 3 attempts / hour (per user)
+      forgotPassword:     { windowMs: 15 * 60 * 1000, max: 5  }, // default: 5 attempts / 15 min (per IP)
+      resetPassword:      { windowMs: 15 * 60 * 1000, max: 10 }, // default: 10 attempts / 15 min (per IP)
+      mfaVerify:          { windowMs: 15 * 60 * 1000, max: 10 }, // default: 10 attempts / 15 min (per IP)
+      mfaResend:          { windowMs: 60 * 1000,      max: 5  }, // default: 5 attempts / minute (per IP)
+      store: "redis",                       // default: "redis" when Redis is enabled, else "memory"
+    },
+    sessionPolicy: {                        // optional — session concurrency and metadata
+      maxSessions: 6,                       // default: 6 — max simultaneous sessions per user; oldest evicted when exceeded
+      persistSessionMetadata: true,         // default: true — keep IP/UA/timestamp row after session expires (for device detection)
+      includeInactiveSessions: false,       // default: false — include expired/deleted sessions in GET /auth/sessions
+      trackLastActive: false,               // default: false — update lastActiveAt on every auth'd request (adds one DB write)
+    },
+    passwordPolicy: {                        // optional — password complexity rules (applies to register + reset, not login)
+      minLength: 8,                         // default: 8
+      requireLetter: true,                  // default: true — at least one a–z or A–Z
+      requireDigit: true,                   // default: true — at least one 0–9
+      requireSpecial: false,                // default: false — at least one non-alphanumeric character
+    },
+    oauth: {
+      providers: { google: { ... }, apple: { ... } }, // omit a provider to disable it
+      postRedirect: "/dashboard",           // default: "/"
+      allowedRedirectUrls: ["https://myapp.com"], // optional — validate postRedirect against allowlist at startup
+    },
+    refreshTokens: {                        // optional — short-lived access + long-lived refresh tokens
+      accessTokenExpiry: 900,               // default: 900 (15 min)
+      refreshTokenExpiry: 2_592_000,        // default: 2_592_000 (30 days)
+      rotationGraceSeconds: 30,             // default: 30 — old token still works briefly after rotation
+    },
+    mfa: {                                  // optional — TOTP/MFA support (requires otpauth peer dep)
+      issuer: "My App",                     // shown in authenticator apps (default: app name)
+      recoveryCodes: 10,                    // default: 10
+      challengeTtlSeconds: 300,             // default: 300 (5 min)
+      emailOtp: {                           // optional — email OTP as alternative MFA method
+        onSend: async (email, code) => {},  // called to deliver the OTP code — use any email provider
+        codeLength: 6,                      // default: 6
+      },
+    },
+    accountDeletion: {                      // optional — enables DELETE /auth/me
+      onBeforeDelete: async (userId) => {}, // throw to abort
+      onAfterDelete: async (userId) => {},  // cleanup callback
+    },
+  },
+
+  // Multi-tenancy
+  tenancy: {
+    resolution: "header",                   // "header" | "subdomain" | "path"
+    headerName: "x-tenant-id",             // header name (when resolution is "header")
+    onResolve: async (tenantId) => ({}),    // validate/load tenant — return null to reject
+    cacheTtlMs: 60_000,                    // LRU cache TTL (default: 60s, 0 to disable)
+    cacheMaxSize: 500,                     // max cached entries (default: 500)
+    exemptPaths: [],                       // extra paths that skip tenant resolution
+    rejectionStatus: 403,                  // 403 (default) or 404
+  },
+
+  // Job status endpoint
+  jobs: {
+    statusEndpoint: true,                  // default: false
+    auth: "userAuth",                      // "userAuth" | "none" | MiddlewareHandler[]
+    roles: ["admin"],                      // require roles (works with userAuth)
+    allowedQueues: ["export"],             // whitelist — empty = nothing exposed
+    scopeToUser: false,                    // when true with userAuth, users see only their own jobs
+  },
+
+  // Security
+  security: {
+    cors: ["https://myapp.com"],            // default: "*"
+    rateLimit: { windowMs: 60_000, max: 100 }, // default: 100 req/min
+    bearerAuth: true,                       // default: true — set false to disable, or { bypass: ["/my-public-route"] }
+    botProtection: {
+      fingerprintRateLimit: true,           // rate-limit by HTTP fingerprint (IP-rotation resistant). default: false
+      blockList: ["198.51.100.0/24"],       // IPv4 CIDRs or exact IPs to block with 403. default: []
+    },
+    headers: {                              // optional — additional security headers via Hono secureHeaders
+      contentSecurityPolicy: "default-src 'self'",  // CSP header value
+      permissionsPolicy: "camera=(), microphone=()", // Permissions-Policy header value
+    },
+    trustProxy: 1,                          // default: false — see "Trusted Proxy" section below
+    csrf: {                                 // opt-in CSRF protection for cookie-based auth
+      enabled: true,                        // default: false
+      exemptPaths: ["/webhooks/*"],         // additional exempt paths (OAuth callbacks auto-exempt)
+      checkOrigin: true,                    // validate Origin header against CORS origins (default: true)
+    },
+  },
+
+  // Extra middleware injected after identify, before route matching
+  middleware: [],
+
+  // Connections & store routing (all optional — shown with defaults)
+  db: {
+    mongo: "single",        // "single" | "separate" | false
+    redis: true,            // false to skip auto-connect
+    sqlite: undefined,      // absolute path to .db file — required when any store is "sqlite"
+    auth: "mongo",          // "mongo" | "sqlite" | "memory" — which built-in auth adapter to use
+    sessions: "redis",      // "redis" | "mongo" | "sqlite" | "memory"
+    oauthState: "redis",    // default: follows sessions
+    cache: "redis",         // global default for cacheResponse (overridable per-route)
+  },
+
+  // Server
+  port: 3000,                                    // default: process.env.PORT ?? 3000
+  workersDir: import.meta.dir + "/workers",      // auto-imports all .ts files after server starts
+  enableWorkers: true,                           // default: true — set false to disable auto-loading
+
+  // WebSocket (see WebSocket section for full examples)
+  ws: {
+    handler: { ... },                                  // override open/message/close/drain handlers
+    upgradeHandler: async (req, server) => { ... },    // replace default cookie-JWT upgrade logic
+    onRoomSubscribe(ws, room) { return true; },        // gate room subscriptions; can be async
+    maxMessageSize: 65_536,                            // default: 65536 (64 KB) — close connection on oversized messages
+  },
+});
+```

package/docs/sections/configuration/overview.md

@@ -0,0 +1,17 @@
+## Configuration
+
+`createServer` / `createApp` accept a config object with these top-level keys:
+
+| Key | Purpose |
+|-----|---------|
+| `routesDir` | **(required)** Path to auto-discovered route files |
+| `app` | App name and version (shown in docs) |
+| `auth` | Roles, OAuth, email verification, MFA, refresh tokens, rate limiting, account deletion |
+| `db` | Connection and store routing — mongo, redis, sqlite, sessions, cache, auth adapter |
+| `security` | CORS, bearer auth, rate limiting, bot protection, CSRF |
+| `tenancy` | Multi-tenant resolution (header/subdomain/path) |
+| `jobs` | Job status REST endpoint config |
+| `ws` | WebSocket handler and upgrade overrides |
+| `middleware` | Extra global middleware array |
+| `modelSchemas` | Schema auto-discovery paths |
+| `port`, `workersDir`, `enableWorkers` | Server options |

package/docs/sections/configuration-example/full.md

@@ -0,0 +1,117 @@
+## Full Configuration Example
+
+For production apps, break config into its own file. Here's a real-world setup with MongoDB, Redis, OAuth, and email verification:
+
+```ts
+// src/config/index.ts
+import path from "path";
+import {
+  type CreateServerConfig,
+  type AppMeta,
+  type AuthConfig,
+  type DbConfig,
+  type SecurityConfig,
+  type ModelSchemasConfig,
+} from "@lastshotlabs/bunshot";
+
+const app: AppMeta = {
+  name: "My App",
+  version: "1.0.0",
+};
+
+const db: DbConfig = {
+  mongo: "single",       // "single" | "separate" | false
+  redis: true,           // false to skip Redis
+  sessions: "redis",     // "redis" | "mongo" | "sqlite" | "memory"
+  cache: "memory",       // default store for cacheResponse
+  auth: "mongo",         // "mongo" | "sqlite" | "memory"
+  oauthState: "memory",  // where to store OAuth state tokens
+};
+
+const auth: AuthConfig = {
+  roles: ["admin", "user"],
+  defaultRole: "user",
+  primaryField: "email",
+  rateLimit: { store: "redis" },
+  emailVerification: {
+    required: true,
+    tokenExpiry: 60 * 60, // 1 hour
+    onSend: async (email, token) => {
+      // send verification email using any provider (Resend, SES, etc.)
+    },
+  },
+  oauth: {
+    postRedirect: "http://localhost:5175/oauth/callback",
+    providers: {
+      google: {
+        clientId: process.env.GOOGLE_CLIENT_ID!,
+        clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+        redirectUri: `http://localhost:${process.env.PORT ?? 3000}/auth/google/callback`,
+      },
+      apple: {
+        clientId: process.env.APPLE_CLIENT_ID!,
+        teamId: process.env.APPLE_TEAM_ID!,
+        keyId: process.env.APPLE_KEY_ID!,
+        privateKey: process.env.APPLE_PRIVATE_KEY!,
+        redirectUri: `http://localhost:${process.env.PORT ?? 3000}/auth/apple/callback`,
+      },
+      microsoft: {
+        tenantId: process.env.MICROSOFT_TENANT_ID!,
+        clientId: process.env.MICROSOFT_CLIENT_ID!,
+        clientSecret: process.env.MICROSOFT_CLIENT_SECRET!,
+        redirectUri: `http://localhost:${process.env.PORT ?? 3000}/auth/microsoft/callback`,
+      },
+      github: {
+        clientId: process.env.GITHUB_CLIENT_ID!,
+        clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+        redirectUri: `http://localhost:${process.env.PORT ?? 3000}/auth/github/callback`,
+      },
+    },
+  },
+};
+
+const security: SecurityConfig = {
+  bearerAuth: true,
+  cors: ["*", "http://localhost:5173"],
+  botProtection: { fingerprintRateLimit: true },
+};
+
+const modelSchemas: ModelSchemasConfig = {
+  registration: "auto",
+  paths: [path.join(import.meta.dir, "../schemas/*.ts")],
+};
+
+export const appConfig: CreateServerConfig = {
+  app,
+  routesDir: path.join(import.meta.dir, "../routes"),
+  workersDir: path.join(import.meta.dir, "../workers"),
+  port: process.env.PORT ? parseInt(process.env.PORT) : 3000,
+  db,
+  auth,
+  security,
+  modelSchemas,
+  middleware: [/* your global middleware here */],
+};
+```
+
+Every field above is optional except `routesDir`. See the [Configuration](#configuration) section for the full reference.
+
+### Built-in endpoints
+
+| Endpoint | Description |
+|---|---|
+| `POST /auth/register` | Create account, returns JWT |
+| `POST /auth/login` | Login, returns JWT (includes `emailVerified` when verification is configured) |
+| `POST /auth/logout` | Invalidates the current session only |
+| `GET /auth/me` | Returns current user's `userId`, `email`, `emailVerified`, and `googleLinked` (requires login) |
+| `POST /auth/set-password` | Set or update password (requires login) |
+| `GET /auth/sessions` | List active sessions with metadata — IP, user-agent, timestamps (requires login) |
+| `DELETE /auth/sessions/:sessionId` | Revoke a specific session by ID (requires login) |
+| `POST /auth/verify-email` | Verify email with token (when `emailVerification` is configured) |
+| `POST /auth/resend-verification` | Resend verification email (requires credentials, when `emailVerification` is configured) |
+| `POST /auth/forgot-password` | Request a password reset email (when `passwordReset` is configured) |
+| `POST /auth/reset-password` | Reset password using a token from the reset email (when `passwordReset` is configured) |
+| `GET /health` | Health check |
+| `GET /docs` | Scalar API docs UI |
+| `GET /openapi.json` | OpenAPI spec |
+| `WS /ws` | WebSocket endpoint (cookie-JWT auth) |

package/docs/sections/configuration-example/overview.md

@@ -0,0 +1,30 @@
+## Full Configuration Example
+
+For production apps, break config into its own file with MongoDB, Redis, OAuth, and email verification. See the [Configuration](#configuration) section for the full reference.
+
+```ts
+// src/config/index.ts
+import { type CreateServerConfig } from "@lastshotlabs/bunshot";
+
+export const appConfig: CreateServerConfig = {
+  app: { name: "My App", version: "1.0.0" },
+  routesDir: import.meta.dir + "/routes",
+  workersDir: import.meta.dir + "/workers",
+  db: { mongo: "single", redis: true, sessions: "redis", cache: "memory", auth: "mongo" },
+  auth: { roles: ["admin", "user"], defaultRole: "user", primaryField: "email" },
+  security: { bearerAuth: true, cors: ["*"] },
+};
+```
+
+### Built-in endpoints
+
+| Endpoint | Description |
+|---|---|
+| `POST /auth/register` | Create account, returns JWT |
+| `POST /auth/login` | Login, returns JWT |
+| `POST /auth/logout` | Invalidates the current session |
+| `GET /auth/me` | Current user profile |
+| `GET /health` | Health check |
+| `GET /docs` | Scalar API docs UI |
+| `GET /openapi.json` | OpenAPI spec |
+| `WS /ws` | WebSocket endpoint |

package/docs/sections/documentation/full.md

@@ -0,0 +1,171 @@
+## Documentation Generation
+
+Bunshot ships its documentation as modular markdown sections that you can pull into your own project's README.
+
+### Setup
+
+Create a `docs/` directory in your project with a config and build script:
+
+```
+my-app/
+  docs/
+    readme.config.json
+    build-readme.ts
+    sections/
+      intro/
+        full.md
+      my-api/
+        full.md
+        overview.md
+```
+
+### Config — `docs/readme.config.json`
+
+```json
+{
+  "output": "../README.md",
+  "separator": "---",
+  "sections": [
+    { "topic": "intro", "default": "full", "separator": false },
+    { "topic": "my-api", "default": "full" },
+    { "topic": "bunshot-auth", "file": "@lastshotlabs/bunshot/docs/auth-flow/overview.md" },
+    { "topic": "bunshot-config", "file": "@lastshotlabs/bunshot/docs/configuration/full.md" }
+  ],
+  "profiles": {
+    "short": {
+      "my-api": "overview"
+    }
+  }
+}
+```
+
+**Section entries:**
+
+| Field | Description |
+|-------|-------------|
+| `topic` | Section identifier. Maps to `sections/{topic}/` directory when no `file` is specified. |
+| `default` | Variant to use: `"full"` or `"overview"`. Falls back to `"full"` if the requested variant doesn't exist. |
+| `file` | Explicit file path. Supports relative paths (`sections/header.md`) and package paths (`@lastshotlabs/bunshot/docs/auth-flow/overview.md`). |
+| `separator` | `true`/`false` — whether to insert `---` before this section. Defaults to `true` (except the first section). |
+
+**Profiles** override specific sections' variants. Only list sections you want to change:
+
+```json
+"profiles": {
+  "short": { "my-api": "overview", "bunshot-auth": "overview" }
+}
+```
+
+### Build script — `docs/build-readme.ts`
+
+Copy this into your project:
+
+```ts
+const configPath = import.meta.dir + "/readme.config.json";
+const config = await Bun.file(configPath).json();
+const profile = Bun.argv[2];
+const overrides: Record<string, string> = profile
+  ? config.profiles?.[profile] ?? {}
+  : {};
+const separator: string = config.separator ?? "---";
+
+if (profile && !config.profiles?.[profile]) {
+  console.error(`Unknown profile: "${profile}". Available: ${Object.keys(config.profiles ?? {}).join(", ")}`);
+  process.exit(1);
+}
+
+function resolveFilePath(file: string): string {
+  if (file.startsWith("./") || file.startsWith("/") || file.startsWith("../")) {
+    return import.meta.dir + "/" + file;
+  }
+  if (file.includes("/") && !file.startsWith("sections")) {
+    const resolved = import.meta.resolve(file);
+    return resolved.replace(/^file:\/\/\//, "");
+  }
+  return import.meta.dir + "/" + file;
+}
+
+const parts: string[] = [
+  "<!-- AUTO-GENERATED — edit docs/sections/, not this file. Run: bun run readme -->",
+];
+
+for (let i = 0; i < config.sections.length; i++) {
+  const section = config.sections[i];
+
+  let filePath: string;
+  if (section.file) {
+    filePath = resolveFilePath(section.file);
+  } else {
+    const variant = overrides[section.topic] ?? section.default ?? "full";
+    const candidate = `${import.meta.dir}/sections/${section.topic}/${variant}.md`;
+    filePath = (await Bun.file(candidate).exists())
+      ? candidate
+      : `${import.meta.dir}/sections/${section.topic}/full.md`;
+  }
+
+  const content = (await Bun.file(filePath).text()).replace(/\r\n/g, "\n");
+
+  const useSeparator = section.separator !== undefined ? section.separator : i > 0;
+  if (useSeparator) parts.push(separator);
+
+  parts.push(content.trimEnd());
+}
+
+const outputPath = import.meta.dir + "/" + (config.output ?? "../README.md");
+await Bun.write(outputPath, parts.join("\n\n") + "\n");
+console.log(
+  `README.md compiled (${config.sections.length} sections${profile ? `, profile: ${profile}` : ""})`
+);
+```
+
+### Add to package.json
+
+```json
+"scripts": {
+  "readme": "bun docs/build-readme.ts",
+  "readme:short": "bun docs/build-readme.ts short"
+}
+```
+
+### Available bunshot sections
+
+Pull any of these into your project's README via `"file": "@lastshotlabs/bunshot/docs/{section}/{variant}.md"`:
+
+| Section | Variants |
+|---------|----------|
+| `quick-start` | `full` |
+| `stack` | `full` |
+| `cli` | `full` |
+| `installation` | `full` |
+| `configuration-example` | `full`, `overview` |
+| `adding-routes` | `full`, `overview` |
+| `mongodb-connections` | `full`, `overview` |
+| `adding-models` | `full`, `overview` |
+| `jobs` | `full`, `overview` |
+| `websocket` | `full`, `overview` |
+| `websocket-rooms` | `full`, `overview` |
+| `adding-middleware` | `full` |
+| `response-caching` | `full`, `overview` |
+| `extending-context` | `full` |
+| `configuration` | `full`, `overview` |
+| `running-without-redis` | `full` |
+| `running-without-redis-or-mongodb` | `full` |
+| `auth-flow` | `full`, `overview` |
+| `roles` | `full`, `overview` |
+| `multi-tenancy` | `full`, `overview` |
+| `oauth` | `full`, `overview` |
+| `peer-dependencies` | `full` |
+| `environment-variables` | `full` |
+| `exports` | `full` |
+
+### Writing your own sections
+
+Each section file is self-contained markdown starting with a `## Heading`. Create `docs/sections/{topic}/full.md` and optionally `overview.md`:
+
+```markdown
+## My Feature
+
+Description and code examples here...
+```
+
+The `---` separators between sections are inserted by the build script — don't include them in section files.

package/docs/sections/environment-variables/full.md

@@ -0,0 +1,55 @@
+## Environment Variables
+
+```env
+NODE_ENV=development
+PORT=...
+
+# MongoDB (single connection — used by connectMongo())
+MONGO_USER_DEV=...
+MONGO_PW_DEV=...
+MONGO_HOST_DEV=...
+MONGO_DB_DEV=...
+MONGO_USER_PROD=...
+MONGO_PW_PROD=...
+MONGO_HOST_PROD=...
+MONGO_DB_PROD=...
+
+# MongoDB auth connection (separate server — used by connectAuthMongo())
+# Only needed when running auth on a different cluster from app data
+MONGO_AUTH_USER_DEV=...
+MONGO_AUTH_PW_DEV=...
+MONGO_AUTH_HOST_DEV=...
+MONGO_AUTH_DB_DEV=...
+MONGO_AUTH_USER_PROD=...
+MONGO_AUTH_PW_PROD=...
+MONGO_AUTH_HOST_PROD=...
+MONGO_AUTH_DB_PROD=...
+
+# Redis
+REDIS_HOST_DEV=host:port
+REDIS_USER_DEV=...
+REDIS_PW_DEV=...
+REDIS_HOST_PROD=host:port
+REDIS_USER_PROD=...
+REDIS_PW_PROD=...
+
+# JWT
+JWT_SECRET_DEV=...
+JWT_SECRET_PROD=...
+
+# Bearer API key (required on every non-bypassed request)
+BEARER_TOKEN_DEV=...
+BEARER_TOKEN_PROD=...
+
+# Logging (optional — defaults to on in dev)
+LOGGING_VERBOSE=true
+
+# OAuth (only needed if using oauthProviders)
+GOOGLE_CLIENT_ID=...
+GOOGLE_CLIENT_SECRET=...
+
+APPLE_CLIENT_ID=...
+APPLE_TEAM_ID=...
+APPLE_KEY_ID=...
+APPLE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n..."
+```

package/docs/sections/exports/full.md

@@ -0,0 +1,92 @@
+## Exports
+
+```ts
+import {
+  // Server factory
+  createServer, createApp,
+
+  // DB
+  connectMongo, connectAuthMongo, connectAppMongo, disconnectMongo,
+  authConnection, appConnection, mongoose,
+  connectRedis, disconnectRedis, getRedis,
+
+  // Jobs
+  createQueue, createWorker,
+  type Job,
+
+  // WebSocket
+  websocket, createWsUpgradeHandler, publish,
+  subscribe, unsubscribe, getSubscriptions, handleRoomActions,
+  getRooms, getRoomSubscribers,
+
+  // Auth utilities
+  signToken, verifyToken,
+  createSession, getSession, deleteSession, getUserSessions, getActiveSessionCount,
+  evictOldestSession, updateSessionLastActive, setSessionStore, deleteUserSessions,
+  setRefreshToken, getSessionByRefreshToken, rotateRefreshToken,  // refresh token management
+  createVerificationToken, getVerificationToken, deleteVerificationToken,  // email verification tokens
+  createResetToken, consumeResetToken, setPasswordResetStore,              // password reset tokens
+  createMfaChallenge, consumeMfaChallenge, replaceMfaChallengeOtp, setMfaChallengeStore, // MFA challenge tokens
+  storeOAuthCode, consumeOAuthCode, setOAuthCodeStore,               // OAuth one-time authorization codes
+  bustAuthLimit, trackAttempt, isLimited, clearMemoryRateLimitStore, // auth rate limiting — use in custom routes or admin unlocks
+  buildFingerprint,                                // HTTP fingerprint hash (IP-independent) — use in custom bot detection logic
+  sqliteAuthAdapter, setSqliteDb, startSqliteCleanup,  // SQLite backend (persisted)
+  memoryAuthAdapter, clearMemoryStore,                 // in-memory backend (ephemeral)
+  setUserRoles, addUserRole, removeUserRole,       // app-wide role management
+  getTenantRoles, setTenantRoles, addTenantRole, removeTenantRole, // tenant-scoped role management
+  type AuthAdapter, type OAuthProfile, type OAuthProviderConfig, type MfaChallengeData,
+  type AuthRateLimitConfig, type BotProtectionConfig, type BotProtectionOptions,
+  type LimitOpts, type RateLimitOptions,
+  type SessionMetadata, type SessionInfo, type RefreshResult,
+
+  // Tenancy
+  createTenant, deleteTenant, getTenant, listTenants,  // tenant provisioning (MongoDB)
+  invalidateTenantCache,                               // invalidate LRU cache entry
+  type TenantInfo, type CreateTenantOptions,
+  type TenancyConfig, type TenantConfig,
+
+  // Middleware
+  bearerAuth, identify, userAuth, rateLimit,
+  botProtection,                                  // CIDR blocklist + per-route bot protection
+  requireRole,                                    // role-based access control (tenant-aware)
+  requireVerifiedEmail,                           // blocks unverified email addresses
+  cacheResponse, bustCache, bustCachePattern, setCacheStore,  // response caching (tenant-namespaced)
+
+  // Crypto utilities
+  timingSafeEqual,                                  // constant-time string comparison for secrets/hashes
+  sha256,                                           // SHA-256 hash helper
+
+  // 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,
+  registerSchema, registerSchemas,                // named OpenAPI schema registration
+  zodToMongoose,                                  // Zod → Mongoose schema conversion
+  createDtoMapper,                                // DB document → API DTO mapper factory
+  type ZodToMongooseConfig, type ZodToMongooseRefConfig, type DtoMapperConfig,
+  getAppRoles,                                    // returns the valid roles list configured at startup
+
+  // Constants
+  COOKIE_TOKEN, HEADER_USER_TOKEN,
+  COOKIE_REFRESH_TOKEN, HEADER_REFRESH_TOKEN,     // refresh token cookie/header names
+
+  // Types
+  type AppEnv, type AppVariables,
+  type CreateServerConfig, type CreateAppConfig, type ModelSchemasConfig,
+  type DbConfig, type AppMeta, type AuthConfig, type OAuthConfig, type SecurityConfig,
+  type PrimaryField, type EmailVerificationConfig, type PasswordResetConfig,
+  type RefreshTokenConfig, type MfaConfig, type MfaEmailOtpConfig, type JobsConfig,
+  type AccountDeletionConfig, type PasswordPolicyConfig, type OAuthCodePayload,
+  type SocketData, type WsConfig,
+} from "@lastshotlabs/bunshot";
+
+// Jobs (separate entrypoint)
+import {
+  createQueue, createWorker,
+  createCronWorker, cleanupStaleSchedulers, getRegisteredCronNames,
+  createDLQHandler,
+  type Job,
+} from "@lastshotlabs/bunshot/queue";
+```