@lastshotlabs/bunshot 0.0.27 → 0.0.28

package/dist/services/auth.js

@@ -1,238 +0,0 @@
-import { getAuthAdapter } from "../lib/authAdapter";
-import { HttpError } from "../lib/HttpError";
-import { signToken, verifyToken } from "../lib/jwt";
-import { createSession, deleteSession, getActiveSessionCount, evictOldestSession, deleteUserSessions, setRefreshToken, getSessionByRefreshToken, rotateRefreshToken } from "../lib/session";
-import { getDefaultRole, getPrimaryField, getEmailVerificationConfig, getMaxSessions, getRefreshTokenConfig, getAccessTokenExpiry, getMfaConfig, getMfaEmailOtpConfig, getMfaWebAuthnConfig, getMfaWebAuthnPasskeyMfaBypass } from "../lib/appConfig";
-import { getSuspended } from "../lib/suspension";
-import { createVerificationToken } from "../lib/emailVerification";
-import { createMfaChallenge } from "../lib/mfaChallenge";
-import { generateEmailOtpCode, generateWebAuthnAuthenticationOptions } from "./mfa";
-import { emitSecurityEvent } from "../lib/securityEvents";
-async function createSessionWithRefreshToken(userId, sessionId, metadata) {
-    const rtConfig = getRefreshTokenConfig();
-    const expirySeconds = rtConfig ? getAccessTokenExpiry() : undefined;
-    const token = await signToken({ sub: userId, sid: sessionId }, expirySeconds);
-    while (await getActiveSessionCount(userId) >= getMaxSessions()) {
-        await evictOldestSession(userId);
-    }
-    await createSession(userId, token, sessionId, metadata);
-    let refreshToken;
-    if (rtConfig) {
-        refreshToken = crypto.randomUUID();
-        await setRefreshToken(sessionId, refreshToken);
-    }
-    return { token, refreshToken, sessionId };
-}
-/** Create a session for a user (used internally and by MFA verify). */
-export const createSessionForUser = async (userId, metadata) => {
-    const sessionId = crypto.randomUUID();
-    return createSessionWithRefreshToken(userId, sessionId, metadata);
-};
-export const register = async (identifier, password, metadata) => {
-    try {
-        const hashed = await Bun.password.hash(password);
-        const adapter = getAuthAdapter();
-        const user = await adapter.create(identifier, hashed);
-        const role = getDefaultRole();
-        if (role)
-            await adapter.setRoles(user.id, [role]);
-        const sessionId = crypto.randomUUID();
-        const { token, refreshToken } = await createSessionWithRefreshToken(user.id, sessionId, metadata);
-        const evConfig = getEmailVerificationConfig();
-        if (evConfig && getPrimaryField() === "email") {
-            try {
-                const verificationToken = await createVerificationToken(user.id, identifier);
-                await evConfig.onSend(identifier, verificationToken);
-            }
-            catch (e) {
-                console.error("[email-verification] Failed to send verification email:", e);
-            }
-        }
-        emitSecurityEvent({ eventType: "auth.register.success", severity: "info", timestamp: new Date().toISOString(), userId: user.id });
-        return { token, userId: user.id, email: identifier, refreshToken };
-    }
-    catch (err) {
-        emitSecurityEvent({ eventType: "auth.register.failure", severity: "warn", timestamp: new Date().toISOString() });
-        throw err;
-    }
-};
-// Pre-computed dummy hash so non-existent-user login takes the same time as wrong-password login
-const DUMMY_HASH = await Bun.password.hash("dummy-timing-safe-placeholder");
-export const login = async (identifier, password, metadata) => {
-    const adapter = getAuthAdapter();
-    const findFn = adapter.findByIdentifier ?? adapter.findByEmail.bind(adapter);
-    const user = await findFn(identifier);
-    // Always verify against a hash to prevent timing-based user enumeration
-    const hashToVerify = user?.passwordHash ?? DUMMY_HASH;
-    const passwordValid = await Bun.password.verify(password, hashToVerify);
-    if (!user || !passwordValid) {
-        emitSecurityEvent({ eventType: "auth.login.failure", severity: "warn", timestamp: new Date().toISOString(), meta: { identifier } });
-        throw new HttpError(401, "Invalid credentials");
-    }
-    // Check suspension
-    const suspensionStatus = await getSuspended(user.id);
-    if (suspensionStatus.suspended) {
-        emitSecurityEvent({ eventType: "auth.login.blocked", severity: "critical", timestamp: new Date().toISOString(), meta: { reason: "suspended" } });
-        throw new HttpError(403, "Account suspended", "ACCOUNT_SUSPENDED");
-    }
-    // Check email verification before MFA to avoid leaking MFA status to unverified users
-    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);
-        if (evConfig.required && !verified) {
-            throw new HttpError(403, "Email not verified");
-        }
-    }
-    // Check MFA — if enabled, return challenge token instead of session
-    if (getMfaConfig() && adapter.isMfaEnabled && await adapter.isMfaEnabled(user.id)) {
-        const methods = adapter.getMfaMethods
-            ? await adapter.getMfaMethods(user.id)
-            : ["totp"];
-        // Auto-send email OTP if enabled
-        let emailOtpHash;
-        const emailOtpConfig = getMfaEmailOtpConfig();
-        if (methods.includes("emailOtp") && emailOtpConfig) {
-            const { code, hash } = generateEmailOtpCode();
-            emailOtpHash = hash;
-            const email = fullUser?.email;
-            if (email)
-                await emailOtpConfig.onSend(email, code);
-        }
-        // Generate WebAuthn authentication options if enabled
-        let webauthnChallenge;
-        let webauthnOptions;
-        const webauthnConfig = getMfaWebAuthnConfig();
-        if (methods.includes("webauthn") && webauthnConfig && adapter.getWebAuthnCredentials) {
-            const result = await generateWebAuthnAuthenticationOptions(user.id);
-            if (result) {
-                webauthnChallenge = result.challenge;
-                webauthnOptions = result.options;
-            }
-        }
-        const mfaToken = await createMfaChallenge(user.id, { emailOtpHash, webauthnChallenge });
-        return { token: "", userId: user.id, mfaRequired: true, mfaToken, mfaMethods: methods, webauthnOptions };
-    }
-    const sessionId = crypto.randomUUID();
-    const { token, refreshToken } = await createSessionWithRefreshToken(user.id, sessionId, metadata);
-    emitSecurityEvent({ eventType: "auth.login.success", severity: "info", timestamp: new Date().toISOString(), userId: user.id });
-    if (evConfig && getPrimaryField() === "email" && adapter.getEmailVerified) {
-        const verified = await adapter.getEmailVerified(user.id);
-        return { token, userId: user.id, email: fullUser?.email, emailVerified: verified, googleLinked, refreshToken };
-    }
-    return { token, userId: user.id, email: fullUser?.email, googleLinked, refreshToken };
-};
-export const refresh = async (refreshTokenValue) => {
-    const result = await getSessionByRefreshToken(refreshTokenValue);
-    if (!result) {
-        throw new HttpError(401, "Invalid or expired refresh token");
-    }
-    const { sessionId, userId, newRefreshToken } = result;
-    // If the returned newRefreshToken differs from what was sent, we're in a grace window replay.
-    // Return the current tokens without rotating again.
-    if (newRefreshToken !== refreshTokenValue) {
-        const accessToken = await signToken({ sub: userId, sid: sessionId }, getAccessTokenExpiry());
-        return { token: accessToken, refreshToken: newRefreshToken, userId };
-    }
-    // Normal rotation: generate new refresh + access tokens
-    const newRT = crypto.randomUUID();
-    const newAccessToken = await signToken({ sub: userId, sid: sessionId }, getAccessTokenExpiry());
-    await rotateRefreshToken(sessionId, newRT, newAccessToken);
-    return { token: newAccessToken, refreshToken: newRT, userId };
-};
-export const deleteAccount = async (userId, password) => {
-    const adapter = getAuthAdapter();
-    if (!adapter.deleteUser) {
-        throw new HttpError(501, "Auth adapter does not support deleteUser");
-    }
-    // Verify password for credential accounts
-    if (password) {
-        const user = adapter.getUser ? await adapter.getUser(userId) : null;
-        const email = user?.email;
-        if (email) {
-            const findFn = adapter.findByIdentifier ?? adapter.findByEmail.bind(adapter);
-            const found = await findFn(email);
-            if (found && !(await Bun.password.verify(password, found.passwordHash))) {
-                throw new HttpError(401, "Invalid password");
-            }
-        }
-    }
-    else if (adapter.hasPassword && await adapter.hasPassword(userId)) {
-        throw new HttpError(400, "Password is required to delete a credential account");
-    }
-    // Revoke all sessions
-    await deleteUserSessions(userId);
-    // Delete the user
-    await adapter.deleteUser(userId);
-    emitSecurityEvent({ eventType: "auth.account.deleted", severity: "warn", timestamp: new Date().toISOString(), userId });
-};
-export const logout = async (token) => {
-    if (token) {
-        const payload = await verifyToken(token);
-        const sessionId = payload.sid;
-        if (sessionId) {
-            await deleteSession(sessionId);
-            emitSecurityEvent({ eventType: "auth.logout", severity: "info", timestamp: new Date().toISOString(), sessionId });
-        }
-    }
-};
-export const passkeyLogin = async (passkeyToken, assertionResponse, metadata) => {
-    const adapter = getAuthAdapter();
-    if (!adapter.findUserByWebAuthnCredentialId || !adapter.getWebAuthnCredentials) {
-        throw new HttpError(501, "Auth adapter does not support passkey login");
-    }
-    const { consumePasskeyLoginChallenge } = await import("../lib/mfaChallenge");
-    const challengeData = await consumePasskeyLoginChallenge(passkeyToken);
-    if (!challengeData) {
-        throw new HttpError(401, "Invalid or expired passkey token");
-    }
-    const credentialId = assertionResponse?.id;
-    if (!credentialId) {
-        throw new HttpError(401, "Invalid assertion response");
-    }
-    const userId = await adapter.findUserByWebAuthnCredentialId(credentialId);
-    if (!userId) {
-        throw new HttpError(401, "Invalid credentials");
-    }
-    const { verifyWebAuthn } = await import("./mfa");
-    const verified = await verifyWebAuthn(userId, assertionResponse, challengeData.webauthnChallenge);
-    if (!verified) {
-        throw new HttpError(401, "WebAuthn verification failed");
-    }
-    // Check suspension
-    const suspensionStatus = await getSuspended(userId);
-    if (suspensionStatus.suspended) {
-        throw new HttpError(403, "Account suspended", "ACCOUNT_SUSPENDED");
-    }
-    // passkeyMfaBypass=true (default): passkey with userVerification=required satisfies both factors
-    const mfaBypass = getMfaWebAuthnPasskeyMfaBypass();
-    if (!mfaBypass && getMfaConfig() && adapter.isMfaEnabled && await adapter.isMfaEnabled(userId)) {
-        const methods = adapter.getMfaMethods ? await adapter.getMfaMethods(userId) : ["totp"];
-        let emailOtpHash;
-        const emailOtpConfig = getMfaEmailOtpConfig();
-        if (methods.includes("emailOtp") && emailOtpConfig) {
-            const { generateEmailOtpCode } = await import("./mfa");
-            const { code, hash } = generateEmailOtpCode();
-            emailOtpHash = hash;
-            const fullUser = adapter.getUser ? await adapter.getUser(userId) : null;
-            if (fullUser?.email)
-                await emailOtpConfig.onSend(fullUser.email, code);
-        }
-        let webauthnChallenge2;
-        let webauthnOptions;
-        if (methods.includes("webauthn") && getMfaWebAuthnConfig()) {
-            const { generateWebAuthnAuthenticationOptions } = await import("./mfa");
-            const result = await generateWebAuthnAuthenticationOptions(userId);
-            if (result) {
-                webauthnChallenge2 = result.challenge;
-                webauthnOptions = result.options;
-            }
-        }
-        const mfaToken = await createMfaChallenge(userId, { emailOtpHash, webauthnChallenge: webauthnChallenge2 });
-        return { token: "", userId, mfaRequired: true, mfaToken, mfaMethods: methods, webauthnOptions };
-    }
-    const { token, refreshToken } = await createSessionForUser(userId, metadata);
-    const fullUser = adapter.getUser ? await adapter.getUser(userId) : null;
-    return { token, userId, email: fullUser?.email, refreshToken };
-};

package/dist/ws/index.d.ts

@@ -1,10 +0,0 @@
-import type { Server, WebSocketHandler } from "bun";
-export type SocketData<T extends object = object> = {
-    id: string;
-    userId: string | null;
-    rooms: Set<string>;
-} & T;
-type BaseSocketData = SocketData<object>;
-export declare const createWsUpgradeHandler: (server: Server<BaseSocketData>) => (req: Request) => Promise<Response | undefined>;
-export declare const websocket: WebSocketHandler<BaseSocketData>;
-export {};

package/dist/ws/index.js

@@ -1,39 +0,0 @@
-import { verifyToken } from "../lib/jwt";
-import { getSession } from "../lib/session";
-import { COOKIE_TOKEN } from "../lib/constants";
-import { trackSocket, untrackSocket } from "../lib/wsPresence";
-import { timingSafeEqual } from "../lib/crypto";
-export const createWsUpgradeHandler = (server) => async (req) => {
-    let userId = null;
-    try {
-        const token = req.headers.get("cookie")
-            ?.match(new RegExp(`(?:^|;\\s*)${COOKIE_TOKEN}=([^;]+)`))?.[1] ?? null;
-        if (token) {
-            const payload = await verifyToken(token);
-            const sessionId = payload.sid;
-            if (sessionId) {
-                const stored = await getSession(sessionId);
-                if (timingSafeEqual(stored ?? "", token))
-                    userId = payload.sub;
-            }
-        }
-    }
-    catch { /* unauthenticated — userId stays null */ }
-    const upgraded = server.upgrade(req, { data: { id: crypto.randomUUID(), userId, rooms: new Set() } });
-    return upgraded ? undefined : Response.json({ error: "Upgrade failed" }, { status: 400 });
-};
-export const websocket = {
-    open(ws) {
-        trackSocket(ws.data.id, ws.data.userId);
-        console.log(`[ws] connected: ${ws.data.id}`);
-        ws.send(JSON.stringify({ event: "connected", id: ws.data.id }));
-    },
-    message(_ws, _message) {
-        // No-op: room actions are handled by server.ts via handleRoomActions.
-        // Override ws.handler.message in WsConfig for custom message handling.
-    },
-    close(ws) {
-        untrackSocket(ws.data.id);
-        console.log(`[ws] disconnected: ${ws.data.id}`);
-    },
-};

package/docs/sections/adding-middleware/full.md

@@ -1,35 +0,0 @@
-## Adding Middleware
-
-### Global (runs on every request)
-
-Pass via `middleware` config — injected after `identify`, before route matching:
-
-```ts
-await createServer({
-  routesDir: import.meta.dir + "/routes",
-  app: { name: "My App", version: "1.0.0" },
-  middleware: [myMiddleware],
-});
-```
-
-Write it using core's exported types:
-
-```ts
-// src/middleware/tenant.ts
-import type { MiddlewareHandler } from "hono";
-import type { AppEnv } from "@lastshotlabs/bunshot";
-
-export const tenantMiddleware: MiddlewareHandler<AppEnv> = async (c, next) => {
-  // c.get("userId") is available — identify has already run
-  await next();
-};
-```
-
-### Per-route
-
-```ts
-import { userAuth, rateLimit } from "@lastshotlabs/bunshot";
-
-router.use("/admin", userAuth);
-router.use("/admin", rateLimit({ windowMs: 60_000, max: 10 }));
-```

package/docs/sections/adding-models/full.md

@@ -1,125 +0,0 @@
-## Adding Models
-
-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 } from "@lastshotlabs/bunshot";
-import { Schema } from "mongoose";
-import type { HydratedDocument } from "mongoose";
-
-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<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.
-
-### Zod as Single Source of Truth
-
-If you use Zod schemas for your OpenAPI spec (via `createRoute` or `modelSchemas`), you can derive your Mongoose schemas and DTO mappers from those same Zod definitions — so each entity is defined **once**.
-
-#### `zodToMongoose` — Zod → Mongoose SchemaDefinition
-
-Converts a Zod object schema into a Mongoose field definition. Business fields are auto-converted; DB-specific concerns (ObjectId refs, type overrides, subdocuments) are declared via config. The `id` field is automatically excluded since Mongoose provides `_id`.
-
-```ts
-import { appConnection, zodToMongoose } from "@lastshotlabs/bunshot";
-import { Schema, type HydratedDocument } from "mongoose";
-import { ProductSchema } from "../schemas/product"; // your Zod schema
-import type { ProductDto } from "../schemas/product";
-
-// DB interface derives from Zod DTO type
-interface IProduct extends Omit<ProductDto, "id" | "categoryId"> {
-  user: Types.ObjectId;
-  category: Types.ObjectId;
-}
-
-const ProductMongoSchema = new Schema<IProduct>(
-  zodToMongoose(ProductSchema, {
-    dbFields: {
-      user: { type: Schema.Types.ObjectId, ref: "UserProfile", required: true },
-    },
-    refs: {
-      categoryId: { dbField: "category", ref: "Category" },
-    },
-    typeOverrides: {
-      createdAt: { type: Date, required: true },
-    },
-  }) as Record<string, unknown>,
-  { timestamps: true }
-);
-
-export type ProductDocument = HydratedDocument<IProduct>;
-export const Product = appConnection.model<IProduct>("Product", ProductMongoSchema);
-```
-
-**Config options:**
-
-| Option | Description |
-|---|---|
-| `dbFields` | Fields that exist only in the DB, not in the API schema (e.g., `user` ObjectId ref) |
-| `refs` | API fields that map to ObjectId refs: `{ accountId: { dbField: "account", ref: "Account" } }` |
-| `typeOverrides` | Override the auto-converted Mongoose type for a field (e.g., Zod `z.string()` for dates → Mongoose `Date`) |
-| `subdocSchemas` | Subdocument array fields: `{ items: mongooseSubSchema }` |
-
-**Auto-conversion mapping:**
-
-| Zod type | Mongoose type |
-|---|---|
-| `z.string()` | `String` |
-| `z.number()` | `Number` |
-| `z.boolean()` | `Boolean` |
-| `z.date()` | `Date` |
-| `z.enum([...])` | `String` with `enum` |
-| `.nullable()` / `.optional()` | `required: false` |
-
-#### `createDtoMapper` — Zod → toDto mapper
-
-Creates a generic `toDto` function from a Zod schema. The schema defines which fields exist in the DTO; the config declares how to transform DB-specific types.
-
-```ts
-import { createDtoMapper } from "@lastshotlabs/bunshot";
-import { ProductSchema, type ProductDto } from "../schemas/product";
-
-const toDto = createDtoMapper<ProductDto>(ProductSchema, {
-  refs: { category: "categoryId" },   // ObjectId ref → string, with rename
-  dates: ["createdAt"],               // Date → ISO string
-});
-
-// Use it
-const product = await Product.findOne({ _id: id });
-return product ? toDto(product) : null;
-```
-
-**Auto-handled transforms:**
-
-| Transform | Description |
-|---|---|
-| `_id` → `id` | Always converted via `.toString()` |
-| `refs` | ObjectId fields → string (`.toString()`), with DB→API field renaming |
-| `dates` | `Date` objects → ISO strings (`.toISOString()`) |
-| `subdocs` | Array fields mapped with a sub-mapper (for nested documents) |
-| nullable/optional | `undefined` → `null` coercion (based on Zod schema) |
-| everything else | Passthrough |
-
-**Subdocument example:**
-
-```ts
-const itemToDto = createDtoMapper<TemplateItemDto>(TemplateItemSchema);
-const toDto = createDtoMapper<TemplateDto>(TemplateSchema, {
-  subdocs: { items: itemToDto },
-});
-```

package/docs/sections/adding-models/overview.md

@@ -1,13 +0,0 @@
-## Adding Models
-
-Import `appConnection` and register Mongoose models on it. `appConnection` is a lazy proxy — `.model()` works before `connectMongo()` has been called.
-
-```ts
-import { appConnection } from "@lastshotlabs/bunshot";
-import { Schema, type HydratedDocument } from "mongoose";
-
-const ProductSchema = new Schema({ name: String, price: Number }, { timestamps: true });
-export const Product = appConnection.model("Product", ProductSchema);
-```
-
-Bunshot also provides `zodToMongoose` (Zod -> Mongoose schema conversion) and `createDtoMapper` (DB document -> API DTO) to use Zod as the single source of truth for your models and OpenAPI spec.

package/docs/sections/adding-routes/full.md

@@ -1,182 +0,0 @@
-## Adding Routes
-
-Drop a file in your `routes/` directory that exports a `router` — see the [Quick Start](#quick-start) example above. Routes are auto-discovered via glob — no registration needed. Subdirectories are supported, so you can organise by feature:
-
-```
-routes/
-  products.ts
-  ingredients/
-    list.ts
-    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
-// routes/tenants.ts — must match before generic routes
-export const priority = 1;
-export const router = createRouter();
-// ...
-```

package/docs/sections/adding-routes/overview.md

@@ -1,23 +0,0 @@
-## Adding Routes
-
-Drop a file in your `routes/` directory that exports a `router` — routes are auto-discovered via glob. Subdirectories are supported.
-
-```ts
-import { z } from "zod";
-import { createRoute, createRouter } from "@lastshotlabs/bunshot";
-
-export const router = createRouter();
-
-router.openapi(
-  createRoute({
-    method: "get",
-    path: "/hello",
-    responses: {
-      200: { content: { "application/json": { schema: z.object({ message: z.string() }) } }, description: "Hello" },
-    },
-  }),
-  (c) => c.json({ message: "Hello world!" }, 200)
-);
-```
-
-Import `createRoute` from `@lastshotlabs/bunshot` (not `@hono/zod-openapi`) to get automatic OpenAPI schema registration. Four registration methods are available — route-level auto-registration, directory/glob auto-discovery via `modelSchemas`, batch explicit via `registerSchemas`, and single explicit via `registerSchema`. Use `withSecurity` to add auth requirements without breaking type inference.