@lastshotlabs/bunshot 0.0.10 → 0.0.13

package/README.md

@@ -142,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();
 
@@ -178,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
@@ -761,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"
@@ -1564,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
@@ -1572,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/app.d.ts

@@ -194,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

@@ -21,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";
@@ -143,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");
@@ -186,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/index.d.ts

@@ -1,6 +1,6 @@
 export { createApp } from "./app";
 export { createServer } from "./server";
-export type { CreateAppConfig, DbConfig, AppMeta, AuthConfig, AuthRateLimitConfig, OAuthConfig, SecurityConfig, BotProtectionConfig, PrimaryField, EmailVerificationConfig, PasswordResetConfig } from "./app";
+export type { CreateAppConfig, ModelSchemasConfig, DbConfig, AppMeta, AuthConfig, AuthRateLimitConfig, OAuthConfig, SecurityConfig, BotProtectionConfig, PrimaryField, EmailVerificationConfig, PasswordResetConfig } from "./app";
 export type { CreateServerConfig, WsConfig } from "./server";
 export { appConnection, authConnection, mongoose, connectMongo, connectAuthMongo, connectAppMongo, disconnectMongo } from "./lib/mongo";
 export { connectRedis, disconnectRedis, getRedis } from "./lib/redis";
@@ -8,6 +8,7 @@ export { getAppRoles } from "./lib/appConfig";
 export { HttpError } from "./lib/HttpError";
 export { COOKIE_TOKEN, HEADER_USER_TOKEN } from "./lib/constants";
 export { createRouter } from "./lib/context";
+export { createRoute, withSecurity, registerSchema, registerSchemas } from "./lib/createRoute";
 export type { AppEnv, AppVariables } from "./lib/context";
 export { signToken, verifyToken } from "./lib/jwt";
 export { log } from "./lib/logger";

package/dist/index.js

@@ -9,6 +9,7 @@ export { getAppRoles } from "./lib/appConfig";
 export { HttpError } from "./lib/HttpError";
 export { COOKIE_TOKEN, HEADER_USER_TOKEN } from "./lib/constants";
 export { createRouter } from "./lib/context";
+export { createRoute, withSecurity, registerSchema, registerSchemas } from "./lib/createRoute";
 export { signToken, verifyToken } from "./lib/jwt";
 export { log } from "./lib/logger";
 export { createResetToken, consumeResetToken, setPasswordResetStore } from "./lib/resetPassword";

package/dist/lib/createRoute.d.ts

@@ -0,0 +1,61 @@
+import type { RouteConfig } from "@hono/zod-openapi";
+import type { ZodType } from "zod";
+/**
+ * Registers a Zod schema as a named entry in `components/schemas`.
+ *
+ * Use this for shared schemas (e.g. shared error types, reusable response shapes)
+ * that aren't directly attached to a specific route. Schemas already registered
+ * under the same name are silently skipped.
+ *
+ * @example
+ * export const MySchema = registerSchema("MySchema", z.object({ id: z.string() }));
+ */
+export declare const registerSchema: <T extends ZodType>(name: string, schema: T) => T;
+/**
+ * Registers multiple Zod schemas at once as named entries in `components/schemas`.
+ * Object keys become the schema names. Returns the same object so you can
+ * destructure or re-export the schemas normally.
+ *
+ * Schemas already registered (e.g. via a prior `registerSchema` call) are skipped.
+ *
+ * @example
+ * export const { LedgerItem, Product } = registerSchemas({
+ *   LedgerItem: z.object({ id: z.string(), amount: z.number() }),
+ *   Product:    z.object({ id: z.string(), price: z.number() }),
+ * });
+ */
+export declare const registerSchemas: <T extends Record<string, ZodType>>(schemas: T) => T;
+/**
+ * Auto-registers a module export as a named OpenAPI schema.
+ * Used internally by modelSchemas auto-discovery in createApp.
+ * Strips a trailing "Schema" suffix from the export name.
+ * Skips non-Zod values and already-registered schemas.
+ */
+export declare function maybeAutoRegister(exportName: string, value: unknown): void;
+/**
+ * Adds an OpenAPI `security` requirement to a route without affecting TypeScript
+ * type inference on the handler. Pass each security scheme as a separate object.
+ *
+ * Use this instead of inlining `security` in `createRoute(...)` — inlining a
+ * field typed as `{ [name: string]: string[] }` breaks `c.req.valid()` inference.
+ *
+ * @example
+ * router.openapi(
+ *   withSecurity(createRoute({ method: "get", path: "/me", ... }), { cookieAuth: [] }, { userToken: [] }),
+ *   async (c) => { ... }
+ * )
+ */
+export declare const withSecurity: <T extends RouteConfig>(route: T, ...schemes: Array<Record<string, string[]>>) => T;
+/**
+ * Drop-in replacement for `createRoute` from `@hono/zod-openapi`.
+ *
+ * Automatically registers unnamed request body and response schemas as named
+ * OpenAPI components so they appear in `components/schemas` instead of being
+ * inlined at every use site. Generated names follow the convention:
+ *
+ *   {Method}{PathSegments}Body         — request body
+ *   {Method}{PathSegments}{StatusCode} — response body
+ *
+ * Schemas already named via `.openapi("Name")` are never overwritten.
+ */
+export declare const createRoute: <T extends RouteConfig>(config: T) => T;

package/dist/lib/createRoute.js

@@ -0,0 +1,147 @@
+import { createRoute as _createRoute } from "@hono/zod-openapi";
+import { getRefId, zodToOpenAPIRegistry } from "@asteasolutions/zod-to-openapi";
+const STATUS_SUFFIX = {
+    "200": "Response",
+    "201": "Response",
+    "204": "Response",
+    "400": "BadRequestError",
+    "401": "UnauthorizedError",
+    "403": "ForbiddenError",
+    "404": "NotFoundError",
+    "409": "ConflictError",
+    "422": "ValidationError",
+    "429": "RateLimitError",
+    "500": "InternalError",
+    "501": "NotImplementedError",
+    "503": "UnavailableError",
+};
+const METHOD_VERB = {
+    get: "Get",
+    post: "Create",
+    put: "Replace",
+    patch: "Update",
+    delete: "Delete",
+};
+/**
+ * Converts a route method + path into a PascalCase base name for auto-generated schema names.
+ * Examples:
+ *   POST /ledger-items       → CreateLedgerItems
+ *   GET  /ledger-items/{id}  → GetLedgerItemsById
+ *   DELETE /auth/sessions/{sessionId} → DeleteAuthSessionsBySessionId
+ */
+function toBaseName(method, path) {
+    const m = METHOD_VERB[method.toLowerCase()] ?? (method.charAt(0).toUpperCase() + method.slice(1).toLowerCase());
+    const segments = path
+        .split("/")
+        .filter(Boolean)
+        .map((seg) => {
+        if (seg.startsWith("{") && seg.endsWith("}")) {
+            const param = seg.slice(1, -1);
+            return "By" + param.charAt(0).toUpperCase() + param.slice(1);
+        }
+        // kebab-case and plain segments → PascalCase
+        return seg.replace(/-([a-z])/g, (_, c) => c.toUpperCase()).replace(/^[a-z]/, (c) => c.toUpperCase());
+    });
+    return m + segments.join("");
+}
+function maybeRegister(schema, name) {
+    if (!schema || typeof schema !== "object" || !("_def" in schema))
+        return;
+    if (getRefId(schema))
+        return; // already named via .openapi()
+    // Write directly to the registry instead of calling schema.openapi(name) — the
+    // .openapi() method requires extendZodWithOpenApi() to have been called on the
+    // same zod instance that created the schema, which isn't guaranteed in tenant apps.
+    zodToOpenAPIRegistry.add(schema, { _internal: { refId: name } });
+}
+/**
+ * Registers a Zod schema as a named entry in `components/schemas`.
+ *
+ * Use this for shared schemas (e.g. shared error types, reusable response shapes)
+ * that aren't directly attached to a specific route. Schemas already registered
+ * under the same name are silently skipped.
+ *
+ * @example
+ * export const MySchema = registerSchema("MySchema", z.object({ id: z.string() }));
+ */
+export const registerSchema = (name, schema) => {
+    if (!getRefId(schema)) {
+        zodToOpenAPIRegistry.add(schema, { _internal: { refId: name } });
+    }
+    return schema;
+};
+/**
+ * Registers multiple Zod schemas at once as named entries in `components/schemas`.
+ * Object keys become the schema names. Returns the same object so you can
+ * destructure or re-export the schemas normally.
+ *
+ * Schemas already registered (e.g. via a prior `registerSchema` call) are skipped.
+ *
+ * @example
+ * export const { LedgerItem, Product } = registerSchemas({
+ *   LedgerItem: z.object({ id: z.string(), amount: z.number() }),
+ *   Product:    z.object({ id: z.string(), price: z.number() }),
+ * });
+ */
+export const registerSchemas = (schemas) => {
+    for (const [name, schema] of Object.entries(schemas)) {
+        if (!getRefId(schema)) {
+            zodToOpenAPIRegistry.add(schema, { _internal: { refId: name } });
+        }
+    }
+    return schemas;
+};
+/**
+ * Auto-registers a module export as a named OpenAPI schema.
+ * Used internally by modelSchemas auto-discovery in createApp.
+ * Strips a trailing "Schema" suffix from the export name.
+ * Skips non-Zod values and already-registered schemas.
+ */
+export function maybeAutoRegister(exportName, value) {
+    if (!value || typeof value !== "object" || !("_def" in value))
+        return;
+    if (getRefId(value))
+        return;
+    const name = exportName.endsWith("Schema")
+        ? exportName.slice(0, -"Schema".length)
+        : exportName;
+    zodToOpenAPIRegistry.add(value, { _internal: { refId: name } });
+}
+/**
+ * Adds an OpenAPI `security` requirement to a route without affecting TypeScript
+ * type inference on the handler. Pass each security scheme as a separate object.
+ *
+ * Use this instead of inlining `security` in `createRoute(...)` — inlining a
+ * field typed as `{ [name: string]: string[] }` breaks `c.req.valid()` inference.
+ *
+ * @example
+ * router.openapi(
+ *   withSecurity(createRoute({ method: "get", path: "/me", ... }), { cookieAuth: [] }, { userToken: [] }),
+ *   async (c) => { ... }
+ * )
+ */
+export const withSecurity = (route, ...schemes) => Object.assign(route, { security: schemes });
+/**
+ * Drop-in replacement for `createRoute` from `@hono/zod-openapi`.
+ *
+ * Automatically registers unnamed request body and response schemas as named
+ * OpenAPI components so they appear in `components/schemas` instead of being
+ * inlined at every use site. Generated names follow the convention:
+ *
+ *   {Method}{PathSegments}Body         — request body
+ *   {Method}{PathSegments}{StatusCode} — response body
+ *
+ * Schemas already named via `.openapi("Name")` are never overwritten.
+ */
+export const createRoute = (config) => {
+    const base = toBaseName(config.method, config.path);
+    // Auto-name the JSON request body schema if present and unnamed
+    const bodySchema = config.request?.body?.content?.["application/json"]?.schema;
+    maybeRegister(bodySchema, `${base}Request`);
+    // Auto-name each JSON response schema if present and unnamed
+    for (const [status, response] of Object.entries(config.responses ?? {})) {
+        const resSchema = response?.content?.["application/json"]?.schema;
+        maybeRegister(resSchema, `${base}${STATUS_SUFFIX[status] ?? status}`);
+    }
+    return _createRoute(config);
+};

package/dist/routes/auth.js

@@ -1,4 +1,4 @@
-import { createRoute } from "@hono/zod-openapi";
+import { createRoute, withSecurity } from "../lib/createRoute";
 import { z } from "zod";
 import { setCookie, getCookie, deleteCookie } from "hono/cookie";
 import * as AuthService from "../services/auth";
@@ -12,8 +12,14 @@ import { getVerificationToken, deleteVerificationToken, createVerificationToken
 import { createResetToken, consumeResetToken } from "../lib/resetPassword";
 import { getUserSessions, deleteSession } from "../lib/session";
 const isProd = process.env.NODE_ENV === "production";
-const TokenResponse = z.object({ token: z.string(), emailVerified: z.boolean().optional() });
-const ErrorResponse = z.object({ error: z.string() });
+const TokenResponse = z.object({
+    token: z.string().describe("JWT session token. Also set as an HttpOnly session cookie."),
+    userId: z.string().describe("Unique user ID."),
+    email: z.string().optional().describe("User's email address (present when primaryField is 'email')."),
+    emailVerified: z.boolean().optional().describe("Whether the email address has been verified (present when emailVerification is configured)."),
+    googleLinked: z.boolean().optional().describe("Whether a Google OAuth account is linked to this user."),
+}).openapi("TokenResponse");
+const ErrorResponse = z.object({ error: z.string().describe("Human-readable error message.") }).openapi("ErrorResponse");
 const tags = ["Auth"];
 const cookieOptions = {
     httpOnly: true,
@@ -39,13 +45,15 @@ export const createAuthRouter = ({ primaryField, emailVerification, passwordRese
     router.openapi(createRoute({
         method: "post",
         path: "/auth/register",
+        summary: "Register a new account",
+        description: "Creates a new user account and returns a JWT session token. The token is also set as an HttpOnly session cookie. Rate-limited by IP.",
         tags,
-        request: { body: { content: { "application/json": { schema: RegisterSchema } } } },
+        request: { body: { content: { "application/json": { schema: RegisterSchema } }, description: "Registration credentials." } },
         responses: {
-            201: { content: { "application/json": { schema: TokenResponse } }, description: "Registered" },
-            400: { content: { "application/json": { schema: ErrorResponse } }, description: "Validation error" },
+            201: { content: { "application/json": { schema: TokenResponse } }, description: "Account created. Returns a session token." },
+            400: { content: { "application/json": { schema: ErrorResponse } }, description: "Validation error (e.g. missing field, password too short)." },
             409: { content: { "application/json": { schema: ErrorResponse } }, description: alreadyRegisteredMsg },
-            429: { content: { "application/json": { schema: ErrorResponse } }, description: "Too many attempts" },
+            429: { content: { "application/json": { schema: ErrorResponse } }, description: "Too many registration attempts from this IP. Try again later." },
         },
     }), async (c) => {
         const ip = clientIp(c.req.header("x-forwarded-for"), c.req.header("x-real-ip")) ?? "unknown";
@@ -58,20 +66,22 @@ export const createAuthRouter = ({ primaryField, emailVerification, passwordRese
             ipAddress: ip !== "unknown" ? ip : undefined,
             userAgent: c.req.header("user-agent") ?? undefined,
         };
-        const token = await AuthService.register(identifier, body.password, metadata);
-        setCookie(c, COOKIE_TOKEN, token, cookieOptions);
-        return c.json({ token }, 201);
+        const result = await AuthService.register(identifier, body.password, metadata);
+        setCookie(c, COOKIE_TOKEN, result.token, cookieOptions);
+        return c.json(result, 201);
     });
     router.openapi(createRoute({
         method: "post",
         path: "/auth/login",
+        summary: "Log in",
+        description: "Authenticates with credentials and returns a JWT session token. The token is also set as an HttpOnly session cookie. Failed attempts are rate-limited per identifier.",
         tags,
-        request: { body: { content: { "application/json": { schema: LoginSchema } } } },
+        request: { body: { content: { "application/json": { schema: LoginSchema } }, description: "Login credentials." } },
         responses: {
-            200: { content: { "application/json": { schema: TokenResponse } }, description: "Logged in" },
-            401: { content: { "application/json": { schema: ErrorResponse } }, description: "Invalid credentials" },
-            403: { content: { "application/json": { schema: ErrorResponse } }, description: "Email not verified" },
-            429: { content: { "application/json": { schema: ErrorResponse } }, description: "Too many attempts" },
+            200: { content: { "application/json": { schema: TokenResponse } }, description: "Authenticated. Returns a session token." },
+            401: { content: { "application/json": { schema: ErrorResponse } }, description: "Invalid credentials." },
+            403: { content: { "application/json": { schema: ErrorResponse } }, description: "Email not verified. Verification is required before login." },
+            429: { content: { "application/json": { schema: ErrorResponse } }, description: "Too many failed login attempts for this identifier. Try again later." },
         },
     }), async (c) => {
         const body = c.req.valid("json");
@@ -96,27 +106,29 @@ export const createAuthRouter = ({ primaryField, emailVerification, passwordRese
         }
     });
     router.use("/auth/me", userAuth);
-    router.openapi(createRoute({
+    router.openapi(withSecurity(createRoute({
         method: "get",
         path: "/auth/me",
+        summary: "Get current user",
+        description: "Returns the authenticated user's profile. Requires a valid session via cookie or x-user-token header.",
         tags,
         responses: {
             200: {
                 content: {
                     "application/json": {
                         schema: z.object({
-                            userId: z.string(),
-                            email: z.string().optional(),
-                            emailVerified: z.boolean().optional(),
-                            googleLinked: z.boolean().optional(),
+                            userId: z.string().describe("Unique user ID."),
+                            email: z.string().optional().describe("User's email address."),
+                            emailVerified: z.boolean().optional().describe("Whether the email address has been verified."),
+                            googleLinked: z.boolean().optional().describe("Whether a Google OAuth account is linked."),
                         }),
                     },
                 },
-                description: "Current user",
+                description: "Authenticated user's profile.",
             },
-            401: { content: { "application/json": { schema: ErrorResponse } }, description: "Unauthorized" },
+            401: { content: { "application/json": { schema: ErrorResponse } }, description: "No valid session." },
         },
-    }), async (c) => {
+    }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
         const authUserId = c.get("authUserId");
         const adapter = getAuthAdapter();
         const user = adapter.getUser ? await adapter.getUser(authUserId) : null;
@@ -124,17 +136,20 @@ export const createAuthRouter = ({ primaryField, emailVerification, passwordRese
         return c.json({ userId: authUserId, email: user?.email, emailVerified: user?.emailVerified, googleLinked }, 200);
     });
     router.use("/auth/set-password", userAuth);
-    router.openapi(createRoute({
+    router.openapi(withSecurity(createRoute({
         method: "post",
         path: "/auth/set-password",
+        summary: "Set or update password",
+        description: "Sets or updates the password for the authenticated user. Useful for OAuth-only users who want to add a password. Requires a valid session.",
         tags,
-        request: { body: { content: { "application/json": { schema: z.object({ password: z.string().min(8) }) } } } },
+        request: { body: { content: { "application/json": { schema: z.object({ password: z.string().min(8).describe("New password. Minimum 8 characters.") }) } }, description: "New password." } },
         responses: {
-            200: { content: { "application/json": { schema: z.object({ message: z.string() }) } }, description: "Password set" },
-            400: { content: { "application/json": { schema: ErrorResponse } }, description: "Validation error" },
-            501: { content: { "application/json": { schema: ErrorResponse } }, description: "Not supported by adapter" },
+            200: { content: { "application/json": { schema: z.object({ message: z.string() }) } }, description: "Password updated successfully." },
+            400: { content: { "application/json": { schema: ErrorResponse } }, description: "Validation error (e.g. password too short)." },
+            401: { content: { "application/json": { schema: ErrorResponse } }, description: "No valid session." },
+            501: { content: { "application/json": { schema: ErrorResponse } }, description: "The configured auth adapter does not support setPassword." },
         },
-    }), async (c) => {
+    }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
         const adapter = getAuthAdapter();
         if (!adapter.setPassword) {
             return c.json({ error: "Auth adapter does not support setPassword" }, 501);
@@ -148,9 +163,11 @@ export const createAuthRouter = ({ primaryField, emailVerification, passwordRese
     router.openapi(createRoute({
         method: "post",
         path: "/auth/logout",
+        summary: "Log out",
+        description: "Invalidates the current session and clears the session cookie. Safe to call even without an active session.",
         tags,
         responses: {
-            200: { content: { "application/json": { schema: z.object({ message: z.string() }) } }, description: "Logged out" },
+            200: { content: { "application/json": { schema: z.object({ message: z.string() }) } }, description: "Logged out. Session is invalidated and cookie is cleared." },
         },
     }), async (c) => {
         const token = getCookie(c, COOKIE_TOKEN) ?? c.req.header(HEADER_USER_TOKEN) ?? null;
@@ -163,12 +180,14 @@ export const createAuthRouter = ({ primaryField, emailVerification, passwordRese
         router.openapi(createRoute({
             method: "post",
             path: "/auth/verify-email",
+            summary: "Verify email address",
+            description: "Consumes a single-use email verification token and marks the account as verified. The token is delivered by the `emailVerification.onSend` callback configured in CreateAppConfig. Rate-limited by IP.",
             tags,
-            request: { body: { content: { "application/json": { schema: z.object({ token: z.string() }) } } } },
+            request: { body: { content: { "application/json": { schema: z.object({ token: z.string().describe("Single-use verification token received via email.") }) } }, description: "Verification token." } },
             responses: {
-                200: { content: { "application/json": { schema: z.object({ message: z.string() }) } }, description: "Email verified" },
-                400: { content: { "application/json": { schema: ErrorResponse } }, description: "Invalid or expired token" },
-                429: { content: { "application/json": { schema: ErrorResponse } }, description: "Too many attempts" },
+                200: { content: { "application/json": { schema: z.object({ message: z.string() }) } }, description: "Email verified successfully." },
+                400: { content: { "application/json": { schema: ErrorResponse } }, description: "Invalid or expired verification token." },
+                429: { content: { "application/json": { schema: ErrorResponse } }, description: "Too many verification attempts from this IP. Try again later." },
             },
         }), async (c) => {
             const ip = c.req.header("x-forwarded-for") ?? "unknown";
@@ -186,17 +205,20 @@ export const createAuthRouter = ({ primaryField, emailVerification, passwordRese
             return c.json({ message: "Email verified" }, 200);
         });
         router.use("/auth/resend-verification", userAuth);
-        router.openapi(createRoute({
+        router.openapi(withSecurity(createRoute({
             method: "post",
             path: "/auth/resend-verification",
+            summary: "Resend verification email",
+            description: "Sends a new verification email to the authenticated user's address. Returns 400 if already verified. Rate-limited per user. Requires a valid session.",
             tags,
             responses: {
-                200: { content: { "application/json": { schema: z.object({ message: z.string() }) } }, description: "Verification email sent" },
-                400: { content: { "application/json": { schema: ErrorResponse } }, description: "Already verified" },
-                429: { content: { "application/json": { schema: ErrorResponse } }, description: "Too many attempts" },
-                501: { content: { "application/json": { schema: ErrorResponse } }, description: "Not supported by adapter" },
+                200: { content: { "application/json": { schema: z.object({ message: z.string() }) } }, description: "Verification email sent." },
+                400: { content: { "application/json": { schema: ErrorResponse } }, description: "Email is already verified, or no email address on file." },
+                401: { content: { "application/json": { schema: ErrorResponse } }, description: "No valid session." },
+                429: { content: { "application/json": { schema: ErrorResponse } }, description: "Too many resend attempts for this user. Try again later." },
+                501: { content: { "application/json": { schema: ErrorResponse } }, description: "The configured auth adapter does not support email verification." },
             },
-        }), async (c) => {
+        }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
             const adapter = getAuthAdapter();
             if (!adapter.getEmailVerified || !adapter.getUser) {
                 return c.json({ error: "Auth adapter does not support email verification" }, 501);
@@ -221,12 +243,14 @@ export const createAuthRouter = ({ primaryField, emailVerification, passwordRese
         router.openapi(createRoute({
             method: "post",
             path: "/auth/forgot-password",
+            summary: "Request password reset",
+            description: "Sends a password reset email if the address is registered. Always returns 200 regardless of whether the address exists, to prevent email enumeration. Rate-limited by both IP and email address.",
             tags,
-            request: { body: { content: { "application/json": { schema: z.object({ email: z.string().email() }) } } } },
+            request: { body: { content: { "application/json": { schema: z.object({ email: z.string().email().describe("Email address to send the reset link to.") }) } }, description: "Email address for the account to reset." } },
             responses: {
-                200: { content: { "application/json": { schema: z.object({ message: z.string() }) } }, description: "Reset email sent if address is registered" },
-                400: { content: { "application/json": { schema: ErrorResponse } }, description: "Validation error" },
-                429: { content: { "application/json": { schema: ErrorResponse } }, description: "Too many attempts" },
+                200: { content: { "application/json": { schema: z.object({ message: z.string() }) } }, description: "Request received. A reset email will be sent if the address is registered." },
+                400: { content: { "application/json": { schema: ErrorResponse } }, description: "Validation error (e.g. not a valid email address)." },
+                429: { content: { "application/json": { schema: ErrorResponse } }, description: "Too many attempts from this IP or for this email address. Try again later." },
             },
         }), async (c) => {
             const ip = clientIp(c.req.header("x-forwarded-for"), c.req.header("x-real-ip")) ?? "unknown";
@@ -258,13 +282,27 @@ export const createAuthRouter = ({ primaryField, emailVerification, passwordRese
         router.openapi(createRoute({
             method: "post",
             path: "/auth/reset-password",
+            summary: "Reset password",
+            description: "Consumes a single-use reset token and sets a new password. All active sessions are revoked after a successful reset to invalidate any stolen JWTs. Rate-limited by IP.",
             tags,
-            request: { body: { content: { "application/json": { schema: z.object({ token: z.string(), password: z.string().min(8) }) } } } },
+            request: {
+                body: {
+                    content: {
+                        "application/json": {
+                            schema: z.object({
+                                token: z.string().describe("Single-use reset token received via email."),
+                                password: z.string().min(8).describe("New password. Minimum 8 characters."),
+                            }),
+                        },
+                    },
+                    description: "Reset token and new password.",
+                },
+            },
             responses: {
-                200: { content: { "application/json": { schema: z.object({ message: z.string() }) } }, description: "Password reset successfully" },
-                400: { content: { "application/json": { schema: ErrorResponse } }, description: "Validation error or invalid/expired token" },
-                429: { content: { "application/json": { schema: ErrorResponse } }, description: "Too many attempts" },
-                501: { content: { "application/json": { schema: ErrorResponse } }, description: "Not supported by adapter" },
+                200: { content: { "application/json": { schema: z.object({ message: z.string() }) } }, description: "Password reset. All sessions have been revoked." },
+                400: { content: { "application/json": { schema: ErrorResponse } }, description: "Validation error, or the reset token is invalid or expired." },
+                429: { content: { "application/json": { schema: ErrorResponse } }, description: "Too many reset attempts from this IP. Try again later." },
+                501: { content: { "application/json": { schema: ErrorResponse } }, description: "The configured auth adapter does not support setPassword." },
             },
         }), async (c) => {
             const ip = clientIp(c.req.header("x-forwarded-for"), c.req.header("x-real-ip")) ?? "unknown";
@@ -292,43 +330,47 @@ export const createAuthRouter = ({ primaryField, emailVerification, passwordRese
     // Session management
     // ---------------------------------------------------------------------------
     const SessionInfoSchema = z.object({
-        sessionId: z.string(),
-        createdAt: z.number(),
-        lastActiveAt: z.number(),
-        expiresAt: z.number(),
-        ipAddress: z.string().optional(),
-        userAgent: z.string().optional(),
-        isActive: z.boolean(),
-    });
+        sessionId: z.string().describe("Unique session identifier (UUID)."),
+        createdAt: z.number().describe("Unix timestamp (ms) when the session was created."),
+        lastActiveAt: z.number().describe("Unix timestamp (ms) of the most recent authenticated request (updated when trackLastActive is enabled)."),
+        expiresAt: z.number().describe("Unix timestamp (ms) when the session expires."),
+        ipAddress: z.string().optional().describe("IP address of the client at session creation."),
+        userAgent: z.string().optional().describe("User-agent string of the client at session creation."),
+        isActive: z.boolean().describe("Whether the session is currently valid and unexpired."),
+    }).openapi("SessionInfo");
     router.use("/auth/sessions", userAuth);
     router.use("/auth/sessions/*", userAuth);
-    router.openapi(createRoute({
+    router.openapi(withSecurity(createRoute({
         method: "get",
         path: "/auth/sessions",
+        summary: "List sessions",
+        description: "Returns all sessions for the authenticated user. Includes inactive sessions when `sessionPolicy.includeInactiveSessions` is enabled. Requires a valid session.",
         tags,
         responses: {
             200: {
                 content: { "application/json": { schema: z.object({ sessions: z.array(SessionInfoSchema) }) } },
-                description: "List of sessions for the current user",
+                description: "Sessions belonging to the authenticated user.",
             },
-            401: { content: { "application/json": { schema: ErrorResponse } }, description: "Unauthorized" },
+            401: { content: { "application/json": { schema: ErrorResponse } }, description: "No valid session." },
         },
-    }), async (c) => {
+    }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
         const userId = c.get("authUserId");
         const sessions = await getUserSessions(userId);
         return c.json({ sessions }, 200);
     });
-    router.openapi(createRoute({
+    router.openapi(withSecurity(createRoute({
         method: "delete",
         path: "/auth/sessions/{sessionId}",
+        summary: "Revoke a session",
+        description: "Revokes a specific session by ID. Users can only revoke their own sessions. Useful for 'sign out of other devices' flows. Requires a valid session.",
         tags,
-        request: { params: z.object({ sessionId: z.string() }) },
+        request: { params: z.object({ sessionId: z.string().describe("UUID of the session to revoke.") }) },
         responses: {
-            200: { content: { "application/json": { schema: z.object({ message: z.string() }) } }, description: "Session revoked" },
-            401: { content: { "application/json": { schema: ErrorResponse } }, description: "Unauthorized" },
-            404: { content: { "application/json": { schema: ErrorResponse } }, description: "Session not found" },
+            200: { content: { "application/json": { schema: z.object({ message: z.string() }) } }, description: "Session revoked successfully." },
+            401: { content: { "application/json": { schema: ErrorResponse } }, description: "No valid session." },
+            404: { content: { "application/json": { schema: ErrorResponse } }, description: "Session not found or does not belong to the authenticated user." },
         },
-    }), async (c) => {
+    }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
         const userId = c.get("authUserId");
         const { sessionId } = c.req.valid("param");
         const sessions = await getUserSessions(userId);

package/dist/services/auth.d.ts

@@ -1,7 +1,14 @@
 import type { SessionMetadata } from "../lib/session";
-export declare const register: (identifier: string, password: string, metadata?: SessionMetadata) => Promise<string>;
+export declare const register: (identifier: string, password: string, metadata?: SessionMetadata) => Promise<{
+    token: string;
+    userId: string;
+    email?: string;
+}>;
 export declare const login: (identifier: string, password: string, metadata?: SessionMetadata) => Promise<{
     token: string;
+    userId: string;
+    email?: string;
     emailVerified?: boolean;
+    googleLinked?: boolean;
 }>;
 export declare const logout: (token: string | null) => Promise<void>;

package/dist/services/auth.js

@@ -27,7 +27,7 @@ export const register = async (identifier, password, metadata) => {
             console.error("[email-verification] Failed to send verification email:", e);
         }
     }
-    return token;
+    return { token, userId: user.id, email: identifier };
 };
 export const login = async (identifier, password, metadata) => {
     const adapter = getAuthAdapter();
@@ -41,6 +41,8 @@ export const login = async (identifier, password, metadata) => {
     while (await getActiveSessionCount(user.id) >= getMaxSessions()) {
         await evictOldestSession(user.id);
     }
+    const fullUser = adapter.getUser ? await adapter.getUser(user.id) : null;
+    const googleLinked = fullUser?.providerIds?.some((id) => id.startsWith("google:")) ?? false;
     const evConfig = getEmailVerificationConfig();
     if (evConfig && getPrimaryField() === "email" && adapter.getEmailVerified) {
         const verified = await adapter.getEmailVerified(user.id);
@@ -48,10 +50,10 @@ export const login = async (identifier, password, metadata) => {
             throw new HttpError(403, "Email not verified");
         }
         await createSession(user.id, token, sessionId, metadata);
-        return { token, emailVerified: verified };
+        return { token, userId: user.id, email: fullUser?.email, emailVerified: verified, googleLinked };
     }
     await createSession(user.id, token, sessionId, metadata);
-    return { token };
+    return { token, userId: user.id, email: fullUser?.email, googleLinked };
 };
 export const logout = async (token) => {
     if (token) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lastshotlabs/bunshot",
-  "version": "0.0.10",
+  "version": "0.0.13",
   "description": "Batteries-included Bun + Hono API framework — auth, sessions, rate limiting, WebSocket, queues, and OpenAPI docs out of the box",
   "repository": {
     "type": "git",