@lastshotlabs/bunshot 0.0.9 → 0.0.13

package/README.md

@@ -60,6 +60,48 @@ bun add @lastshotlabs/bunshot
 
 ---
 
+## Peer Dependencies
+
+Bunshot declares the following as peer dependencies so you control their versions and avoid duplicate installs in your app.
+
+### Required
+
+These must be installed in every consuming app:
+
+```bash
+bun add hono zod
+```
+
+| Package | Required version |
+|---|---|
+| `hono` | `>=4.12 <5` |
+| `zod` | `>=4.0 <5` |
+
+### Optional
+
+Install only what your app actually uses:
+
+```bash
+# MongoDB auth / sessions / cache
+bun add mongoose
+
+# Redis sessions, cache, rate limiting, or BullMQ
+bun add ioredis
+
+# Background job queues
+bun add bullmq
+```
+
+| Package | Required version | When you need it |
+|---|---|---|
+| `mongoose` | `>=9.0 <10` | `db.auth: "mongo"`, `db.sessions: "mongo"`, or `db.cache: "mongo"` |
+| `ioredis` | `>=5.0 <6` | `db.redis: true` (the default), or any store set to `"redis"` |
+| `bullmq` | `>=5.0 <6` | Workers / queues |
+
+If you're running fully on SQLite or memory (no Redis, no MongoDB), none of the optional peers are needed.
+
+---
+
 ## Quick Start
 
 ```ts
@@ -85,6 +127,8 @@ That's it. Your app gets:
 | `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 login, 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 |
@@ -98,9 +142,8 @@ Drop a file in your `routes/` directory. It must export a `router`:
 
 ```ts
 // src/routes/products.ts
-import { createRoute } from "@hono/zod-openapi";
 import { z } from "zod";
-import { createRouter, userAuth } from "@lastshotlabs/bunshot";
+import { createRoute, createRouter, userAuth } from "@lastshotlabs/bunshot";
 
 export const router = createRouter();
 
@@ -134,6 +177,168 @@ routes/
     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
@@ -197,18 +402,31 @@ await createServer({
 
 Import `appConnection` and register models on it. This ensures your models use the correct connection whether you're on a single DB or a separate tenant DB.
 
+`appConnection` is a lazy proxy — calling `.model()` at the top level works fine even before `connectMongo()` has been called. Mongoose buffers any queries until the connection is established.
+
 ```ts
 // src/models/Product.ts
-import { appConnection, mongoose } from "@lastshotlabs/bunshot";
+import { appConnection } from "@lastshotlabs/bunshot";
+import { Schema } from "mongoose";
+import type { HydratedDocument } from "mongoose";
 
-const ProductSchema = new mongoose.Schema({
+interface IProduct {
+  name: string;
+  price: number;
+}
+
+export type ProductDocument = HydratedDocument<IProduct>;
+
+const ProductSchema = new Schema<IProduct>({
   name: { type: String, required: true },
   price: { type: Number, required: true },
 }, { timestamps: true });
 
-export const Product = appConnection.model("Product", ProductSchema);
+export const Product = appConnection.model<IProduct>("Product", ProductSchema);
 ```
 
+> **Note:** Import types (`HydratedDocument`, `Schema`, etc.) directly from `"mongoose"` — the `appConnection` and `mongoose` exports from bunshot are runtime proxies and cannot be used as TypeScript namespaces.
+
 ---
 
 ## Jobs (BullMQ)
@@ -704,6 +922,11 @@ 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"
@@ -724,11 +947,19 @@ await createServer({
         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)
       store: "redis",                       // default: "redis" when Redis is enabled, else "memory"
     },
     sessionPolicy: {                        // optional — session concurrency and metadata
@@ -994,6 +1225,8 @@ All built-in auth endpoints are rate-limited out of the box with sensible defaul
 | `POST /auth/register` | IP address | Every attempt | 5 / hour |
 | `POST /auth/verify-email` | IP address | Every attempt | 10 / 15 min |
 | `POST /auth/resend-verification` | User ID (authenticated) | 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.
 
@@ -1497,7 +1730,8 @@ import {
   cacheResponse, bustCache, bustCachePattern, setCacheStore,  // response caching
 
   // Utilities
-  HttpError, log, validate, createRouter,
+  HttpError, log, validate, createRouter, createRoute,
+  registerSchema, registerSchemas,                // named OpenAPI schema registration
   getAppRoles,                                    // returns the valid roles list configured at startup
 
   // Constants
@@ -1505,7 +1739,7 @@ import {
 
   // Types
   type AppEnv, type AppVariables,
-  type CreateServerConfig, type CreateAppConfig,
+  type CreateServerConfig, type CreateAppConfig, type ModelSchemasConfig,
   type DbConfig, type AppMeta, type AuthConfig, type OAuthConfig, type SecurityConfig,
   type PrimaryField, type EmailVerificationConfig,
   type SocketData, type WsConfig,

package/dist/adapters/memoryAuth.d.ts

@@ -25,3 +25,8 @@ export declare const memoryGetVerificationToken: (token: string) => {
     email: string;
 } | null;
 export declare const memoryDeleteVerificationToken: (token: string) => void;
+export declare const memoryCreateResetToken: (token: string, userId: string, email: string, ttlSeconds: number) => void;
+export declare const memoryConsumeResetToken: (hash: string) => {
+    userId: string;
+    email: string;
+} | null;

package/dist/adapters/memoryAuth.js

@@ -7,6 +7,7 @@ const _userSessionIds = new Map(); // userId → Set<sessionId>
 const _oauthStates = new Map();
 const _cache = new Map();
 const _verificationTokens = new Map();
+const _resetTokens = new Map();
 /** Reset all in-memory state. Useful for test isolation. */
 export const clearMemoryStore = () => {
     _users.clear();
@@ -16,6 +17,7 @@ export const clearMemoryStore = () => {
     _oauthStates.clear();
     _cache.clear();
     _verificationTokens.clear();
+    _resetTokens.clear();
 };
 // ---------------------------------------------------------------------------
 // Auth adapter
@@ -290,3 +292,24 @@ export const memoryGetVerificationToken = (token) => {
 export const memoryDeleteVerificationToken = (token) => {
     _verificationTokens.delete(token);
 };
+// ---------------------------------------------------------------------------
+// Password reset token helpers (used by src/lib/resetPassword.ts)
+// ---------------------------------------------------------------------------
+export const memoryCreateResetToken = (token, userId, email, ttlSeconds) => {
+    const now = Date.now();
+    // Opportunistically purge expired entries to prevent unbounded memory growth
+    for (const [k, v] of _resetTokens) {
+        if (v.expiresAt <= now)
+            _resetTokens.delete(k);
+    }
+    _resetTokens.set(token, { userId, email, expiresAt: now + ttlSeconds * 1000 });
+};
+export const memoryConsumeResetToken = (hash) => {
+    const entry = _resetTokens.get(hash);
+    if (!entry || entry.expiresAt <= Date.now()) {
+        _resetTokens.delete(hash);
+        return null;
+    }
+    _resetTokens.delete(hash);
+    return { userId: entry.userId, email: entry.email };
+};

package/dist/adapters/sqliteAuth.d.ts

@@ -25,4 +25,9 @@ export declare const sqliteGetVerificationToken: (token: string) => {
     email: string;
 } | null;
 export declare const sqliteDeleteVerificationToken: (token: string) => void;
+export declare const sqliteCreateResetToken: (token: string, userId: string, email: string, ttlSeconds: number) => void;
+export declare const sqliteConsumeResetToken: (hash: string) => {
+    userId: string;
+    email: string;
+} | null;
 export declare const startSqliteCleanup: (intervalMs?: number) => ReturnType<typeof setInterval>;

package/dist/adapters/sqliteAuth.js

@@ -65,6 +65,12 @@ function initSchema(db) {
     email     TEXT NOT NULL,
     expiresAt INTEGER NOT NULL
   )`);
+    db.run(`CREATE TABLE IF NOT EXISTS password_resets (
+    token     TEXT PRIMARY KEY,
+    userId    TEXT NOT NULL,
+    email     TEXT NOT NULL,
+    expiresAt INTEGER NOT NULL
+  )`);
 }
 // ---------------------------------------------------------------------------
 // Auth adapter
@@ -282,6 +288,17 @@ export const sqliteDeleteVerificationToken = (token) => {
     getDb().run("DELETE FROM email_verifications WHERE token = ?", [token]);
 };
 // ---------------------------------------------------------------------------
+// Password reset token helpers (used by src/lib/resetPassword.ts)
+// ---------------------------------------------------------------------------
+export const sqliteCreateResetToken = (token, userId, email, ttlSeconds) => {
+    const expiresAt = Date.now() + ttlSeconds * 1000;
+    getDb().run("INSERT INTO password_resets (token, userId, email, expiresAt) VALUES (?, ?, ?, ?)", [token, userId, email, expiresAt]);
+};
+export const sqliteConsumeResetToken = (hash) => {
+    const row = getDb().query("DELETE FROM password_resets WHERE token = ? AND expiresAt > ? RETURNING userId, email").get(hash, Date.now());
+    return row ?? null;
+};
+// ---------------------------------------------------------------------------
 // Optional periodic cleanup of expired rows
 // ---------------------------------------------------------------------------
 export const startSqliteCleanup = (intervalMs = 3_600_000) => {
@@ -298,5 +315,6 @@ export const startSqliteCleanup = (intervalMs = 3_600_000) => {
         db.run("DELETE FROM oauth_states WHERE expiresAt <= ?", [now]);
         db.run("DELETE FROM cache_entries WHERE expiresAt IS NOT NULL AND expiresAt <= ?", [now]);
         db.run("DELETE FROM email_verifications WHERE expiresAt <= ?", [now]);
+        db.run("DELETE FROM password_resets WHERE expiresAt <= ?", [now]);
     }, intervalMs);
 };

package/dist/app.d.ts

@@ -1,7 +1,7 @@
 import { OpenAPIHono } from "@hono/zod-openapi";
 import type { MiddlewareHandler } from "hono";
 import type { AppEnv } from "./lib/context";
-import type { PrimaryField, EmailVerificationConfig } from "./lib/appConfig";
+import type { PrimaryField, EmailVerificationConfig, PasswordResetConfig } from "./lib/appConfig";
 import type { AuthAdapter } from "./lib/authAdapter";
 import type { OAuthProviderConfig } from "./lib/oauth";
 type StoreType = "redis" | "mongo" | "sqlite" | "memory";
@@ -82,6 +82,16 @@ export interface AuthRateLimitConfig {
         windowMs?: number;
         max?: number;
     };
+    /** Max forgot-password requests per IP per window. Default: 5 per 15 min. */
+    forgotPassword?: {
+        windowMs?: number;
+        max?: number;
+    };
+    /** Max reset-password attempts per IP per window. Default: 10 per 15 min. */
+    resetPassword?: {
+        windowMs?: number;
+        max?: number;
+    };
     /**
      * Store backend for auth rate limit counters.
      * Defaults to "redis" when Redis is enabled, otherwise "memory".
@@ -116,6 +126,12 @@ export interface AuthConfig {
      * Provide an onSend callback to send the verification email via any provider (Resend, SendGrid, etc.).
      */
     emailVerification?: EmailVerificationConfig;
+    /**
+     * Password reset configuration. Only active when primaryField is "email".
+     * Provide an onSend callback to send the reset email via any provider (Resend, SendGrid, etc.).
+     * Mounts POST /auth/forgot-password and POST /auth/reset-password.
+     */
+    passwordReset?: PasswordResetConfig;
     /** Rate limit configuration for built-in auth endpoints. */
     rateLimit?: AuthRateLimitConfig;
     /** Session concurrency and metadata persistence policy. */
@@ -140,7 +156,7 @@ export interface AuthSessionPolicyConfig {
      */
     trackLastActive?: boolean;
 }
-export type { PrimaryField, EmailVerificationConfig };
+export type { PrimaryField, EmailVerificationConfig, PasswordResetConfig };
 export interface BotProtectionConfig {
     /**
      * List of IPv4 CIDRs (e.g. "198.51.100.0/24"), IPv4 addresses, or IPv6 addresses to block outright.
@@ -178,9 +194,39 @@ export interface SecurityConfig {
      */
     botProtection?: BotProtectionConfig;
 }
+export interface ModelSchemasConfig {
+    /**
+     * One or more absolute directory paths or glob patterns containing shared Zod schemas.
+     * All matching .ts files are imported before routes so schemas are registered first.
+     * Optional when registration is "explicit" — in that case your registerSchema /
+     * registerSchemas calls run at the time each schema file is imported by a route.
+     * Examples:
+     *   import.meta.dir + "/schemas"
+     *   [import.meta.dir + "/schemas", import.meta.dir + "/models"]
+     *   import.meta.dir + "/models/**\/*.schema.ts"
+     */
+    paths?: string | string[];
+    /**
+     * How schemas found in the files are registered in `components/schemas`.
+     * - "auto" (default): exported Zod schemas are registered automatically. The export
+     *   name is used as the schema name, with a trailing "Schema" suffix stripped
+     *   (e.g. `LedgerItemSchema` → `"LedgerItem"`). Schemas already registered via
+     *   `registerSchema` or `registerSchemas` inside the file are never overwritten.
+     * - "explicit": files are imported but registration is entirely up to the user —
+     *   call `registerSchema` or `registerSchemas` inside each file.
+     */
+    registration?: "auto" | "explicit";
+}
 export interface CreateAppConfig {
     /** Absolute path to the service's routes directory (use import.meta.dir + "/routes") */
     routesDir: string;
+    /**
+     * Shared Zod schema sources. Files are imported before route discovery so schemas
+     * are registered before any route references them.
+     * Accepts a directory path, an array of paths/globs, or a full ModelSchemasConfig object.
+     * Shorthand string/array defaults to registration: "auto".
+     */
+    modelSchemas?: string | string[] | ModelSchemasConfig;
     /** App name and version for the root endpoint and OpenAPI docs */
     app?: AppMeta;
     /** Auth, roles, and OAuth configuration */

package/dist/app.js

@@ -8,8 +8,9 @@ import { rateLimit } from "./middleware/rateLimit";
 import { bearerAuth } from "./middleware/bearerAuth";
 import { identify } from "./middleware/identify";
 import { HEADER_USER_TOKEN } from "./lib/constants";
-import { setAppName, setAppRoles, setDefaultRole, setPrimaryField, setEmailVerificationConfig, setMaxSessions, setPersistSessionMetadata, setIncludeInactiveSessions, setTrackLastActive } from "./lib/appConfig";
+import { setAppName, setAppRoles, setDefaultRole, setPrimaryField, setEmailVerificationConfig, setPasswordResetConfig, setMaxSessions, setPersistSessionMetadata, setIncludeInactiveSessions, setTrackLastActive } from "./lib/appConfig";
 import { setEmailVerificationStore } from "./lib/emailVerification";
+import { setPasswordResetStore } from "./lib/resetPassword";
 import { setAuthRateLimitStore } from "./lib/authRateLimit";
 import { setAuthAdapter } from "./lib/authAdapter";
 import { mongoAuthAdapter } from "./adapters/mongoAuth";
@@ -20,6 +21,7 @@ import { connectMongo, connectAuthMongo, connectAppMongo } from "./lib/mongo";
 import { connectRedis } from "./lib/redis";
 import { setSessionStore } from "./lib/session";
 import { setCacheStore } from "./middleware/cacheResponse";
+import { maybeAutoRegister } from "./lib/createRoute";
 export const createApp = async (config) => {
     const { routesDir, app: appConfig = {}, auth: authConfig = {}, security: securityConfig = {}, middleware = [], db = {}, } = config;
     const appName = appConfig.name ?? "Bun Core API";
@@ -39,6 +41,7 @@ export const createApp = async (config) => {
     const defaultRole = authConfig.defaultRole;
     const primaryField = authConfig.primaryField ?? "email";
     const emailVerification = authConfig.emailVerification;
+    const passwordReset = authConfig.passwordReset;
     const authRateLimit = authConfig.rateLimit;
     const sessionPolicy = authConfig.sessionPolicy ?? {};
     const { sqlite, mongo = "single", redis: enableRedis = true } = db;
@@ -82,20 +85,31 @@ export const createApp = async (config) => {
     else {
         authAdapter = mongoAuthAdapter;
     }
+    if (defaultRole && !authAdapter.setRoles) {
+        throw new Error(`createApp: "defaultRole" is set to "${defaultRole}" but the auth adapter does not implement setRoles. Add setRoles to your adapter or remove defaultRole.`);
+    }
+    if (emailVerification && primaryField !== "email") {
+        throw new Error(`createApp: "emailVerification" is only supported when primaryField is "email". Either set primaryField to "email" or remove emailVerification.`);
+    }
+    if (passwordReset && primaryField !== "email") {
+        throw new Error(`createApp: "passwordReset" is only supported when primaryField is "email". Either set primaryField to "email" or remove passwordReset.`);
+    }
+    if (passwordReset && !authAdapter.setPassword) {
+        throw new Error(`createApp: "passwordReset" is configured but the auth adapter does not implement setPassword. Add setPassword to your adapter or remove passwordReset.`);
+    }
     setAuthAdapter(authAdapter);
     setAppRoles(roles);
     setDefaultRole(defaultRole ?? null);
     setPrimaryField(primaryField);
     setEmailVerificationConfig(emailVerification ?? null);
     setEmailVerificationStore(sessions);
+    setPasswordResetConfig(passwordReset ?? null);
+    setPasswordResetStore(sessions);
     setAuthRateLimitStore(authRateLimit?.store ?? (enableRedis ? "redis" : "memory"));
     setMaxSessions(sessionPolicy.maxSessions ?? 6);
     setPersistSessionMetadata(sessionPolicy.persistSessionMetadata ?? true);
     setIncludeInactiveSessions(sessionPolicy.includeInactiveSessions ?? false);
     setTrackLastActive(sessionPolicy.trackLastActive ?? false);
-    if (defaultRole && !authAdapter.setRoles) {
-        throw new Error(`createApp: "defaultRole" is set to "${defaultRole}" but the auth adapter does not implement setRoles. Add setRoles to your adapter or remove defaultRole.`);
-    }
     if (oauthProviders)
         initOAuthProviders(oauthProviders);
     const configuredOAuth = getConfiguredOAuthProviders();
@@ -130,6 +144,42 @@ export const createApp = async (config) => {
     for (const mw of middleware)
         app.use(mw);
     setAppName(appName);
+    // Schema pre-loading — import shared schema files before routes so registerSchema /
+    // registerSchemas calls run first, guaranteeing $ref instead of inline shapes.
+    const msConfig = config.modelSchemas;
+    if (msConfig) {
+        const { paths, registration = "auto" } = typeof msConfig === "string" || Array.isArray(msConfig)
+            ? { paths: msConfig, registration: "auto" }
+            : msConfig;
+        const pathArray = paths ? (Array.isArray(paths) ? paths : [paths]) : [];
+        for (const entry of pathArray) {
+            // Normalize to forward slashes so splitting works on both Windows and Unix.
+            const normalized = entry.replaceAll("\\", "/");
+            // Split glob patterns: everything before the first wildcard segment is the cwd.
+            let cwd;
+            let pattern;
+            if (!normalized.includes("*")) {
+                cwd = normalized;
+                pattern = "**/*.ts";
+            }
+            else {
+                const parts = normalized.split("/");
+                const starIdx = parts.findIndex((p) => p.includes("*"));
+                cwd = parts.slice(0, starIdx).join("/");
+                pattern = parts.slice(starIdx).join("/");
+            }
+            const schemaGlob = new Bun.Glob(pattern);
+            for await (const file of schemaGlob.scan({ cwd })) {
+                const mod = await import(`${cwd}/${file}`);
+                if (registration === "auto") {
+                    for (const [exportName, value] of Object.entries(mod)) {
+                        maybeAutoRegister(exportName, value);
+                    }
+                }
+                // "explicit": file imported; any registerSchema/registerSchemas calls inside already ran
+            }
+        }
+    }
     // Core routes (auth, etc.)
     const coreRoutesDir = import.meta.dir + "/routes";
     const coreGlob = new Bun.Glob("*.ts");
@@ -144,7 +194,7 @@ export const createApp = async (config) => {
     }
     if (enableAuthRoutes) {
         const { createAuthRouter } = await import(`${coreRoutesDir}/auth`);
-        app.route("/", createAuthRouter({ primaryField, emailVerification, rateLimit: authRateLimit }));
+        app.route("/", createAuthRouter({ primaryField, emailVerification, passwordReset, rateLimit: authRateLimit }));
     }
     if (configuredOAuth.length > 0) {
         app.route("/", createOAuthRouter(configuredOAuth, postOAuthRedirect));
@@ -173,6 +223,23 @@ export const createApp = async (config) => {
         return c.json({ error: "Internal Server Error" }, 500);
     });
     app.notFound((c) => c.json({ error: "Not Found" }, 404));
+    app.openAPIRegistry.registerComponent("securitySchemes", "cookieAuth", {
+        type: "apiKey",
+        in: "cookie",
+        name: "token",
+        description: "Session cookie set automatically on login/register.",
+    });
+    app.openAPIRegistry.registerComponent("securitySchemes", "userToken", {
+        type: "apiKey",
+        in: "header",
+        name: "x-user-token",
+        description: "JWT session token passed as the x-user-token request header (alternative to the session cookie).",
+    });
+    app.openAPIRegistry.registerComponent("securitySchemes", "bearerAuth", {
+        type: "http",
+        scheme: "bearer",
+        description: "API key passed as Authorization: Bearer <token>. Required on all endpoints unless bearer auth is disabled in CreateAppConfig or the path is in the bypass list.",
+    });
     app.doc("/openapi.json", { openapi: "3.0.0", info: { title: appName, version: openApiVersion } });
     app.get("/docs", Scalar({ url: "/openapi.json" }));
     app.get("/sw.js", (c) => c.body("", 200, { "Content-Type": "application/javascript" }));

package/dist/entrypoints/mongo.d.ts

@@ -0,0 +1,3 @@
+export { connectMongo, connectAuthMongo, connectAppMongo, disconnectMongo, authConnection, appConnection, mongoose } from "../lib/mongo";
+export { mongoAuthAdapter } from "../adapters/mongoAuth";
+export { AuthUser } from "../models/AuthUser";

package/dist/entrypoints/mongo.js

@@ -0,0 +1,3 @@
+export { connectMongo, connectAuthMongo, connectAppMongo, disconnectMongo, authConnection, appConnection, mongoose } from "../lib/mongo";
+export { mongoAuthAdapter } from "../adapters/mongoAuth";
+export { AuthUser } from "../models/AuthUser";

package/dist/entrypoints/queue.d.ts

@@ -0,0 +1,2 @@
+export { createQueue, createWorker } from "../lib/queue";
+export type { Job } from "../lib/queue";