@lastshotlabs/bunshot 0.0.27 → 0.1.0

package/docs/sections/exports/full.md

@@ -1,123 +0,0 @@
-## 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, 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,
-  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)
-  webhookAuth,                                    // HMAC signature verification for incoming webhooks
-  type WebhookAuthOptions, type WebhookTimestampOptions,
-
-  // 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, 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
-  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
-  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,
-  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";
-```

package/docs/sections/extending-context/full.md

@@ -1,59 +0,0 @@
-## Extending the Context (Custom Variables)
-
-When building a tenant app or any app that needs extra typed context variables (beyond the built-in), extend `AppEnv["Variables"]` and create a typed router factory.
-
-```ts
-// src/lib/context.ts
-import { createRouter as coreCreateRouter, type AppEnv } from "@lastshotlabs/bunshot";
-import type { OpenAPIHono } from "@hono/zod-openapi";
-
-export type MyVariables = AppEnv["Variables"] & {
-  tenantId: string;
-};
-
-export type MyEnv = { Variables: MyVariables };
-
-export const createRouter = () => coreCreateRouter() as unknown as OpenAPIHono<MyEnv>;
-```
-
-Use the local `createRouter` instead of the one from the package — your routes will then have full TypeScript access to the extra variables:
-
-```ts
-// src/routes/items.ts
-import { createRouter } from "../lib/context";
-import { userAuth } from "@lastshotlabs/bunshot";
-
-export const router = createRouter();
-
-router.use("/items", userAuth);
-
-router.get("/items", async (c) => {
-  const tenantId = c.get("tenantId"); // fully typed
-  const userId   = c.get("userId");   // still available from AppEnv
-  return c.json({ tenantId, userId });
-});
-```
-
-Populate the extra variables from a global middleware:
-
-```ts
-// src/middleware/tenant.ts
-import type { MiddlewareHandler } from "hono";
-import type { MyEnv } from "../lib/context";
-
-export const tenantMiddleware: MiddlewareHandler<MyEnv> = async (c, next) => {
-  const tenantId = c.req.header("x-tenant-id") ?? "default";
-  c.set("tenantId", tenantId);
-  await next();
-};
-```
-
-Then register it in `createServer`:
-
-```ts
-await createServer({
-  routesDir: import.meta.dir + "/routes",
-  app: { name: "My App", version: "1.0.0" },
-  middleware: [tenantMiddleware],
-});
-```

package/docs/sections/header.md

@@ -1,3 +0,0 @@
-# Bunshot by Last Shot Labs
-
-A personal Bun + Hono API framework. Install it in any app and get auth, sessions, rate limiting, WebSocket, queues, and OpenAPI docs out of the box — then add your own routes, workers, models, and services.

package/docs/sections/installation/full.md

@@ -1,6 +0,0 @@
-## Installation
-
-```bash
-# from npm
-bun add @lastshotlabs/bunshot
-```

package/docs/sections/jobs/full.md

@@ -1,140 +0,0 @@
-## Jobs (BullMQ)
-
-> **Redis requirement**: BullMQ requires `maxmemory-policy noeviction`. Set it in `redis.conf` or via Docker:
-> ```yaml
-> command: redis-server --maxmemory-policy noeviction
-> ```
-
-Queues and workers share the existing Redis connection automatically.
-
-### Define a queue
-
-```ts
-// src/queues/email.ts
-import { createQueue } from "@lastshotlabs/bunshot";
-
-export type EmailJob = { to: string; subject: string; body: string };
-
-export const emailQueue = createQueue<EmailJob>("email");
-```
-
-### Add jobs
-
-```ts
-import { emailQueue } from "../queues/email";
-
-await emailQueue.add("send-welcome", { to: "user@example.com", subject: "Welcome", body: "..." });
-
-// with options
-await emailQueue.add("send-reset", payload, { delay: 5000, attempts: 3 });
-```
-
-### Define a worker
-
-```ts
-// src/workers/email.ts
-import { createWorker } from "@lastshotlabs/bunshot";
-import type { EmailJob } from "../queues/email";
-
-export const emailWorker = createWorker<EmailJob>("email", async (job) => {
-  const { to, subject, body } = job.data;
-  // send email...
-});
-```
-
-Workers in `workersDir` are auto-discovered and registered after the server starts — no manual imports needed. Subdirectories are supported.
-
-### Broadcasting WebSocket messages from a worker
-
-Use `publish` to broadcast to all connected clients from inside a worker (or anywhere):
-
-```ts
-// src/workers/notify.ts
-import { createWorker, publish } from "@lastshotlabs/bunshot";
-import type { NotifyJob } from "../queues/notify";
-
-export const notifyWorker = createWorker<NotifyJob>("notify", async (job) => {
-  const { text, from } = job.data;
-  publish("broadcast", { text, from, timestamp: new Date().toISOString() });
-});
-```
-
-`publish` is available after `createServer` resolves. Workers are loaded after that point, so it's always safe to use inside a worker.
-
-### Cron / scheduled workers
-
-Use `createCronWorker` for recurring jobs. It creates both a queue and worker, and uses BullMQ's `upsertJobScheduler` for idempotent scheduling across restarts.
-
-```ts
-// src/workers/cleanup.ts
-import { createCronWorker } from "@lastshotlabs/bunshot/queue";
-
-export const { worker, queue } = createCronWorker(
-  "cleanup",
-  async (job) => {
-    // runs every hour
-    await deleteExpiredRecords();
-  },
-  { cron: "0 * * * *" }         // or { every: 3_600_000 } for interval-based
-);
-```
-
-**Ghost job cleanup**: When a cron worker is renamed or removed, the old scheduler persists in Redis. Bunshot handles this automatically — after all workers in `workersDir` are loaded, stale schedulers are pruned. For workers managed outside `workersDir`, call `cleanupStaleSchedulers(activeNames)` manually.
-
-### Job status endpoint
-
-Expose job state via REST for client-side polling (e.g., long-running uploads or exports):
-
-```ts
-import { userAuth, requireRole } from "@lastshotlabs/bunshot";
-
-await createServer({
-  jobs: {
-    statusEndpoint: true,                           // default: false
-    auth: "userAuth",                                // "userAuth" | "none" | MiddlewareHandler[]
-    roles: ["admin"],                                // require these roles (works with userAuth)
-    allowedQueues: ["export", "upload"],              // whitelist — empty = nothing exposed (secure by default)
-    scopeToUser: false,                              // when true with userAuth, users only see their own jobs
-  },
-});
-```
-
-**Auth options:**
-- `"userAuth"` — requires an authenticated user session. Combine with `roles` for RBAC.
-- `"none"` — no auth protection (not recommended for production).
-- `MiddlewareHandler[]` — pass a custom middleware stack for full control, e.g. `[userAuth, requireRole("admin")]`.
-
-#### Endpoints
-
-| Endpoint | Purpose |
-|---|---|
-| `GET /jobs` | List available queues |
-| `GET /jobs/:queue` | List jobs in a queue (paginated, filterable by state) |
-| `GET /jobs/:queue/:id` | Job state, progress, result, or failure reason |
-| `GET /jobs/:queue/:id/logs` | Job logs |
-| `GET /jobs/:queue/dead-letters` | Paginated list of DLQ jobs |
-
-The list endpoint (`GET /jobs/:queue`) accepts `?state=waiting|active|completed|failed|delayed|paused` and `?start=0&end=19` for pagination.
-
-### Dead Letter Queue (DLQ)
-
-Automatically move permanently failed jobs to a DLQ for inspection and retry:
-
-```ts
-import { createWorker, createDLQHandler } from "@lastshotlabs/bunshot/queue";
-
-const emailWorker = createWorker("email", async (job) => { ... });
-
-const { dlqQueue, retryJob } = createDLQHandler(emailWorker, "email", {
-  maxSize: 1000,                                    // default: 1000 — oldest trimmed when exceeded
-  onDeadLetter: async (job, error) => {              // optional alerting callback
-    await alertSlack(`Job ${job.id} failed: ${error.message}`);
-  },
-  preserveJobOptions: true,                          // default: true — retry with original delay/priority/attempts
-});
-
-// Retry a specific failed job
-await retryJob("job-id-123");
-```
-
-The DLQ queue is named `${sourceQueueName}-dlq` (e.g., `email-dlq`). It's automatically available via the job status endpoint if listed in `allowedQueues`.

package/docs/sections/jobs/overview.md

@@ -1,15 +0,0 @@
-## Jobs (BullMQ)
-
-Queue-based background jobs powered by BullMQ (requires Redis with `noeviction` policy).
-
-```ts
-// Define a queue
-import { createQueue } from "@lastshotlabs/bunshot";
-export const emailQueue = createQueue<{ to: string; subject: string }>("email");
-
-// Define a worker (auto-discovered from workersDir)
-import { createWorker } from "@lastshotlabs/bunshot";
-export const emailWorker = createWorker("email", async (job) => { /* send email */ });
-```
-
-Features include cron/scheduled workers via `createCronWorker`, dead letter queues via `createDLQHandler`, job status REST endpoints, and WebSocket broadcasting from workers via `publish`.

package/docs/sections/logging/full.md

@@ -1,83 +0,0 @@
-## Request Logging & Request IDs
-
-Every request gets a unique **request ID** — either read from the incoming `X-Request-Id` header or generated as a `crypto.randomUUID()`. The ID is:
-
-- Set on context: `c.get("requestId")`
-- Echoed back in the `X-Request-Id` response header
-- Included in error JSON responses (`{ error: "...", requestId: "..." }`)
-- Included in audit log entries (when audit logging is enabled)
-
-### Structured JSON Logging
-
-By default, every request/response is logged as structured JSON (replacing Hono's built-in text logger):
-
-```json
-{
-  "level": "info",
-  "time": 1710000000000,
-  "msg": "GET /api/users 200",
-  "requestId": "550e8400-e29b-41d4-a716-446655440000",
-  "method": "GET",
-  "path": "/api/users",
-  "statusCode": 200,
-  "responseTime": 12.34,
-  "ip": "203.0.113.42",
-  "userAgent": "Mozilla/5.0...",
-  "userId": "user-123",
-  "sessionId": "sess-456",
-  "tenantId": "tenant-789"
-}
-```
-
-Status codes map to log levels: 5xx → `"error"`, 4xx → `"warn"`, else `"info"`.
-
-Default excluded paths: `/health`, `/docs`, `/openapi.json` (prefix matching).
-
-### Configuration
-
-```ts
-await createServer({
-  routesDir: import.meta.dir + "/routes",
-  logging: {
-    // Default: true. Set false to disable logging entirely (no fallback to Hono's text logger)
-    enabled: true,
-    // Minimum level to emit — "info" (default), "warn", or "error"
-    level: "info",
-    // Custom log handler — plug in Pino, Datadog, etc.
-    onLog: (entry) => pino.info(entry),
-    // Paths to exclude (prefix matching for strings, .test() for RegExp)
-    excludePaths: ["/health", "/docs", "/openapi.json", /^\/internal\//],
-    // HTTP methods to exclude
-    excludeMethods: ["OPTIONS"],
-  },
-});
-```
-
-### Using Request IDs
-
-Access the request ID in any route or middleware:
-
-```ts
-router.get("/api/example", (c) => {
-  const requestId = c.get("requestId");
-  // Pass to downstream services, include in logs, etc.
-  return c.json({ requestId, data: "..." });
-});
-```
-
-### Exports
-
-```ts
-import {
-  requestId,         // middleware — generates/propagates X-Request-Id
-  requestLogger,     // middleware — structured JSON request logging
-  HEADER_REQUEST_ID, // "x-request-id" constant
-} from "@lastshotlabs/bunshot";
-
-import type {
-  RequestLogEntry,      // shape of each log entry
-  RequestLoggerOptions, // options for requestLogger()
-  LogLevel,             // "info" | "warn" | "error"
-  LoggingConfig,        // config shape for createApp/createServer
-} from "@lastshotlabs/bunshot";
-```

package/docs/sections/metrics/full.md

@@ -1,131 +0,0 @@
-## Prometheus Metrics
-
-Opt-in `/metrics` endpoint that Prometheus can scrape. Tracks request counts, latency distributions, and optionally BullMQ queue depths.
-
-### Quick Start
-
-```ts
-await createServer({
-  routesDir: import.meta.dir + "/routes",
-  metrics: {
-    enabled: true,
-  },
-});
-```
-
-`GET /metrics` now returns Prometheus text exposition format:
-
-```
-# HELP http_requests_total Total http requests total
-# TYPE http_requests_total counter
-http_requests_total{method="GET",path="/users",status="200"} 42
-
-# HELP http_request_duration_seconds http request duration seconds
-# TYPE http_request_duration_seconds histogram
-http_request_duration_seconds_bucket{method="GET",path="/users",le="0.005"} 10
-...
-http_request_duration_seconds_bucket{method="GET",path="/users",le="+Inf"} 42
-http_request_duration_seconds_sum{method="GET",path="/users"} 12.345
-http_request_duration_seconds_count{method="GET",path="/users"} 42
-```
-
-### Configuration
-
-```ts
-await createServer({
-  routesDir: import.meta.dir + "/routes",
-  metrics: {
-    enabled: true,
-    // Auth for /metrics — "none" (default), "userAuth", or custom middleware stack
-    auth: "userAuth",
-    // Paths excluded from collection (prefix matching for strings, .test() for RegExp)
-    excludePaths: ["/metrics", "/health", "/docs", "/openapi.json"], // defaults
-    // Custom path normalizer (default collapses UUIDs, ObjectIDs, numeric segments to :id)
-    normalizePath: (path) => path.replace(/\/[0-9]+/g, "/:id"),
-    // BullMQ queue names to report depth gauges for (requires Redis)
-    queues: ["email", "reports"],
-  },
-});
-```
-
-### Path Normalization
-
-To prevent high-cardinality labels, dynamic path segments are normalized by default:
-
-| Pattern | Example | Normalized |
-|---------|---------|------------|
-| UUID | `/users/550e8400-e29b-41d4-a716-446655440000` | `/users/:id` |
-| MongoDB ObjectID | `/items/507f1f77bcf86cd799439011` | `/items/:id` |
-| Numeric segment | `/posts/123/comments` | `/posts/:id/comments` |
-| Short slug | `/api/v2/users` | `/api/v2/users` (unchanged) |
-
-Override with `metrics.normalizePath` for custom normalization logic.
-
-### Multi-Tenancy
-
-When tenancy is configured, a `tenant` label is automatically added to all metrics:
-
-```
-http_requests_total{method="GET",path="/data",status="200",tenant="acme"} 15
-```
-
-### BullMQ Queue Depths
-
-When `metrics.queues` is set, a `bullmq_queue_depth` gauge is registered and queried on each scrape:
-
-```
-bullmq_queue_depth{queue="email",state="waiting"} 5
-bullmq_queue_depth{queue="email",state="active"} 2
-bullmq_queue_depth{queue="email",state="delayed"} 0
-bullmq_queue_depth{queue="email",state="failed"} 1
-```
-
-Queue instances are lazily cached and reused across scrapes. Call `closeMetricsQueues()` during graceful shutdown to clean up Redis connections.
-
-### Error Handling
-
-Gauge callback errors never cause a 500. If a gauge callback fails, the gauge is omitted from that scrape and an internal error counter is incremented:
-
-```
-bunshot_gauge_errors_total{gauge="bullmq_queue_depth"} 1
-```
-
-This counter is always present when metrics are enabled so you can alert on scrape failures.
-
-### Security
-
-Auth defaults to `"none"` for easy adoption. A production warning is logged when metrics are enabled without auth.
-
-**In production, `/metrics` returns `403` when `auth` is `"none"`** — the endpoint is hard-blocked to prevent accidental exposure of operational details (error rates, queue depths, tenant activity patterns). Configure `metrics.auth` before deploying:
-
-```ts
-metrics: {
-  enabled: true,
-  auth: "userAuth",                        // require a logged-in user
-  // or:
-  auth: [userAuth, requireRole("admin")],  // custom middleware stack
-}
-```
-
-### Self-Exclusion
-
-`/metrics` is excluded from its own collection and from request logging by default, so scraping doesn't inflate your metrics.
-
-### Exports
-
-```ts
-import {
-  metricsCollector,       // middleware — collects request metrics
-  incrementCounter,       // manually increment a counter
-  observeHistogram,       // manually observe a histogram value
-  registerGaugeCallback,  // register an async gauge callback
-  serializeMetrics,       // produce Prometheus text format
-  resetMetrics,           // clear all metrics (for tests)
-  closeMetricsQueues,     // close cached BullMQ queue instances
-} from "@lastshotlabs/bunshot";
-
-import type {
-  MetricsConfig,             // config shape for createApp/createServer
-  MetricsMiddlewareOptions,  // options for metricsCollector()
-} from "@lastshotlabs/bunshot";
-```

package/docs/sections/mongodb-connections/full.md

@@ -1,45 +0,0 @@
-## MongoDB Connections
-
-MongoDB and Redis connect automatically inside `createServer` / `createApp`. Control the behavior via the `db` config object:
-
-### Single database (default)
-
-Both auth and app data share one server. Uses `MONGO_*` env vars.
-
-```ts
-await createServer({
-  // ...
-  db: { mongo: "single", redis: true }, // these are the defaults — can omit db entirely
-  // app, auth, security are all optional with sensible defaults
-});
-```
-
-### Separate auth database
-
-Auth users live on a dedicated server (`MONGO_AUTH_*` env vars), app data on its own server (`MONGO_*` env vars). Useful when multiple tenant apps share one auth cluster.
-
-```ts
-await createServer({
-  // ...
-  db: { mongo: "separate" },
-});
-```
-
-### Manual connections
-
-Set `mongo: false` and/or `redis: false` to skip auto-connect and manage connections yourself:
-
-```ts
-import { connectAuthMongo, connectAppMongo, connectRedis, createServer } from "@lastshotlabs/bunshot";
-
-await connectAuthMongo();
-await connectAppMongo();
-await connectRedis();
-
-await createServer({
-  // ...
-  db: { mongo: false, redis: false },
-});
-```
-
-`AuthUser` and all built-in auth routes always use `authConnection`. Your app models use `appConnection` (see Adding Models below).

package/docs/sections/mongodb-connections/overview.md

@@ -1,7 +0,0 @@
-## MongoDB Connections
-
-MongoDB and Redis connect automatically inside `createServer` / `createApp`. Control via the `db` config:
-
-- **`mongo: "single"`** (default) — auth and app data share one server (`MONGO_*` env vars)
-- **`mongo: "separate"`** — auth on its own server (`MONGO_AUTH_*` env vars), app data on another
-- **`mongo: false`** — skip auto-connect, manage connections yourself via `connectAuthMongo()`, `connectAppMongo()`, `connectRedis()`