@lastshotlabs/bunshot 0.0.13 → 0.0.16

package/dist/services/auth.js

@@ -1,9 +1,31 @@
 import { getAuthAdapter } from "../lib/authAdapter";
 import { HttpError } from "../lib/HttpError";
 import { signToken, verifyToken } from "../lib/jwt";
-import { createSession, deleteSession, getActiveSessionCount, evictOldestSession } from "../lib/session";
-import { getDefaultRole, getPrimaryField, getEmailVerificationConfig, getMaxSessions } from "../lib/appConfig";
+import { createSession, deleteSession, getActiveSessionCount, evictOldestSession, deleteUserSessions, setRefreshToken, getSessionByRefreshToken, rotateRefreshToken } from "../lib/session";
+import { getDefaultRole, getPrimaryField, getEmailVerificationConfig, getMaxSessions, getRefreshTokenConfig, getAccessTokenExpiry, getMfaConfig, getMfaEmailOtpConfig } from "../lib/appConfig";
 import { createVerificationToken } from "../lib/emailVerification";
+import { createMfaChallenge } from "../lib/mfaChallenge";
+import { generateEmailOtpCode } from "./mfa";
+async function createSessionWithRefreshToken(userId, sessionId, metadata) {
+    const rtConfig = getRefreshTokenConfig();
+    const expirySeconds = rtConfig ? getAccessTokenExpiry() : undefined;
+    const token = await signToken(userId, 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) => {
     const hashed = await Bun.password.hash(password);
     const adapter = getAuthAdapter();
@@ -12,11 +34,7 @@ export const register = async (identifier, password, metadata) => {
     if (role)
         await adapter.setRoles(user.id, [role]);
     const sessionId = crypto.randomUUID();
-    const token = await signToken(user.id, sessionId);
-    while (await getActiveSessionCount(user.id) >= getMaxSessions()) {
-        await evictOldestSession(user.id);
-    }
-    await createSession(user.id, token, sessionId, metadata);
+    const { token, refreshToken } = await createSessionWithRefreshToken(user.id, sessionId, metadata);
     const evConfig = getEmailVerificationConfig();
     if (evConfig && getPrimaryField() === "email") {
         try {
@@ -27,7 +45,7 @@ export const register = async (identifier, password, metadata) => {
             console.error("[email-verification] Failed to send verification email:", e);
         }
     }
-    return { token, userId: user.id, email: identifier };
+    return { token, userId: user.id, email: identifier, refreshToken };
 };
 export const login = async (identifier, password, metadata) => {
     const adapter = getAuthAdapter();
@@ -36,11 +54,7 @@ export const login = async (identifier, password, metadata) => {
     if (!user || !(await Bun.password.verify(password, user.passwordHash))) {
         throw new HttpError(401, "Invalid credentials");
     }
-    const sessionId = crypto.randomUUID();
-    const token = await signToken(user.id, sessionId);
-    while (await getActiveSessionCount(user.id) >= getMaxSessions()) {
-        await evictOldestSession(user.id);
-    }
+    // 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();
@@ -49,11 +63,75 @@ export const login = async (identifier, password, metadata) => {
         if (evConfig.required && !verified) {
             throw new HttpError(403, "Email not verified");
         }
-        await createSession(user.id, token, sessionId, metadata);
-        return { token, userId: user.id, email: fullUser?.email, emailVerified: verified, googleLinked };
     }
-    await createSession(user.id, token, sessionId, metadata);
-    return { token, userId: user.id, email: fullUser?.email, googleLinked };
+    // 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);
+        }
+        const mfaToken = await createMfaChallenge(user.id, emailOtpHash);
+        return { token: "", userId: user.id, mfaRequired: true, mfaToken, mfaMethods: methods };
+    }
+    const sessionId = crypto.randomUUID();
+    const { token, refreshToken } = await createSessionWithRefreshToken(user.id, sessionId, metadata);
+    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(userId, sessionId, getAccessTokenExpiry());
+        return { token: accessToken, refreshToken: newRefreshToken, userId };
+    }
+    // Normal rotation: generate new refresh + access tokens
+    const newRT = crypto.randomUUID();
+    const newAccessToken = await signToken(userId, 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);
 };
 export const logout = async (token) => {
     if (token) {

package/dist/services/mfa.d.ts

@@ -0,0 +1,37 @@
+export interface MfaSetupResult {
+    secret: string;
+    uri: string;
+}
+export declare const setupMfa: (userId: string) => Promise<MfaSetupResult>;
+export declare const verifySetup: (userId: string, code: string) => Promise<string[]>;
+export declare const verifyTotp: (userId: string, code: string) => Promise<boolean>;
+export declare const verifyRecoveryCode: (userId: string, code: string) => Promise<boolean>;
+export declare const disableMfa: (userId: string, code: string) => Promise<void>;
+export declare const regenerateRecoveryCodes: (userId: string, code: string) => Promise<string[]>;
+/** Generate a cryptographically random numeric OTP code. Returns { code, hash }. */
+export declare const generateEmailOtpCode: (length?: number) => {
+    code: string;
+    hash: string;
+};
+/** Verify an email OTP code against a stored hash. */
+export declare const verifyEmailOtp: (emailOtpHash: string, code: string) => boolean;
+/**
+ * Initiate email OTP setup: sends a verification code to the user's email.
+ * Returns a setup challenge token that must be confirmed via confirmEmailOtp.
+ */
+export declare const initiateEmailOtp: (userId: string) => Promise<string>;
+/**
+ * Confirm email OTP setup: verifies the code sent during initiateEmailOtp.
+ * Enables email OTP as an MFA method. Returns recovery codes if MFA was not previously active.
+ */
+export declare const confirmEmailOtp: (userId: string, setupToken: string, code: string) => Promise<string[] | null>;
+/**
+ * Disable email OTP for a user.
+ * If TOTP is also enabled, requires a TOTP code. Otherwise requires password.
+ */
+export declare const disableEmailOtp: (userId: string, params: {
+    code?: string;
+    password?: string;
+}) => Promise<void>;
+/** Get the MFA methods enabled for a user. */
+export declare const getMfaMethods: (userId: string) => Promise<string[]>;

package/dist/services/mfa.js

@@ -0,0 +1,276 @@
+import { getAuthAdapter } from "../lib/authAdapter";
+import { HttpError } from "../lib/HttpError";
+import { getMfaIssuer, getMfaAlgorithm, getMfaDigits, getMfaPeriod, getMfaRecoveryCodeCount, getMfaEmailOtpConfig, getMfaEmailOtpCodeLength } from "../lib/appConfig";
+import { createMfaChallenge } from "../lib/mfaChallenge";
+// Lazy-load otpauth to keep it as an optional peer dependency
+let _otpauth = null;
+async function getOtpAuth() {
+    if (!_otpauth)
+        _otpauth = await import("otpauth");
+    return _otpauth;
+}
+function sha256(input) {
+    const hash = new Bun.CryptoHasher("sha256");
+    hash.update(input);
+    return hash.digest("hex");
+}
+function generateRandomCode(length) {
+    const chars = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789"; // no ambiguous chars: I/1/O/0
+    let code = "";
+    const bytes = crypto.getRandomValues(new Uint8Array(length));
+    for (let i = 0; i < length; i++) {
+        code += chars[bytes[i] % chars.length];
+    }
+    return code;
+}
+function generateRecoveryCodes() {
+    const count = getMfaRecoveryCodeCount();
+    const plainCodes = [];
+    const hashedCodes = [];
+    for (let i = 0; i < count; i++) {
+        const plain = generateRandomCode(8);
+        plainCodes.push(plain);
+        hashedCodes.push(sha256(plain));
+    }
+    return { plainCodes, hashedCodes };
+}
+export const setupMfa = async (userId) => {
+    const adapter = getAuthAdapter();
+    if (!adapter.setMfaSecret)
+        throw new HttpError(501, "Auth adapter does not support MFA");
+    const otpauth = await getOtpAuth();
+    const secret = new otpauth.Secret();
+    const totp = new otpauth.TOTP({
+        issuer: getMfaIssuer(),
+        label: userId,
+        algorithm: getMfaAlgorithm(),
+        digits: getMfaDigits(),
+        period: getMfaPeriod(),
+        secret,
+    });
+    // Store the secret but don't enable MFA yet — user must confirm with a code
+    await adapter.setMfaSecret(userId, secret.base32);
+    return {
+        secret: secret.base32,
+        uri: totp.toString(),
+    };
+};
+export const verifySetup = async (userId, code) => {
+    const adapter = getAuthAdapter();
+    if (!adapter.getMfaSecret || !adapter.setMfaEnabled || !adapter.setRecoveryCodes) {
+        throw new HttpError(501, "Auth adapter does not support MFA");
+    }
+    const secretStr = await adapter.getMfaSecret(userId);
+    if (!secretStr)
+        throw new HttpError(400, "MFA setup not initiated. Call POST /auth/mfa/setup first.");
+    const otpauth = await getOtpAuth();
+    const totp = new otpauth.TOTP({
+        issuer: getMfaIssuer(),
+        algorithm: getMfaAlgorithm(),
+        digits: getMfaDigits(),
+        period: getMfaPeriod(),
+        secret: otpauth.Secret.fromBase32(secretStr),
+    });
+    const delta = totp.validate({ token: code, window: 1 });
+    if (delta === null)
+        throw new HttpError(401, "Invalid TOTP code");
+    // Generate recovery codes (regenerates if enabling a second method)
+    const { plainCodes, hashedCodes } = generateRecoveryCodes();
+    await adapter.setRecoveryCodes(userId, hashedCodes);
+    await adapter.setMfaEnabled(userId, true);
+    // Add "totp" to mfaMethods
+    if (adapter.getMfaMethods && adapter.setMfaMethods) {
+        const methods = await adapter.getMfaMethods(userId);
+        if (!methods.includes("totp")) {
+            await adapter.setMfaMethods(userId, [...methods, "totp"]);
+        }
+    }
+    return plainCodes;
+};
+export const verifyTotp = async (userId, code) => {
+    const adapter = getAuthAdapter();
+    if (!adapter.getMfaSecret)
+        throw new HttpError(501, "Auth adapter does not support MFA");
+    const secretStr = await adapter.getMfaSecret(userId);
+    if (!secretStr)
+        return false;
+    const otpauth = await getOtpAuth();
+    const totp = new otpauth.TOTP({
+        issuer: getMfaIssuer(),
+        algorithm: getMfaAlgorithm(),
+        digits: getMfaDigits(),
+        period: getMfaPeriod(),
+        secret: otpauth.Secret.fromBase32(secretStr),
+    });
+    return totp.validate({ token: code, window: 1 }) !== null;
+};
+export const verifyRecoveryCode = async (userId, code) => {
+    const adapter = getAuthAdapter();
+    if (!adapter.getRecoveryCodes || !adapter.removeRecoveryCode)
+        return false;
+    const hashedCodes = await adapter.getRecoveryCodes(userId);
+    const hashedInput = sha256(code.toUpperCase());
+    const match = hashedCodes.find((h) => h === hashedInput);
+    if (!match)
+        return false;
+    await adapter.removeRecoveryCode(userId, match);
+    return true;
+};
+export const disableMfa = async (userId, code) => {
+    const adapter = getAuthAdapter();
+    if (!adapter.setMfaEnabled || !adapter.setMfaSecret || !adapter.setRecoveryCodes) {
+        throw new HttpError(501, "Auth adapter does not support MFA");
+    }
+    const valid = await verifyTotp(userId, code);
+    if (!valid)
+        throw new HttpError(401, "Invalid TOTP code");
+    await adapter.setMfaEnabled(userId, false);
+    await adapter.setMfaSecret(userId, null);
+    await adapter.setRecoveryCodes(userId, []);
+    // Clear all mfaMethods
+    if (adapter.setMfaMethods) {
+        await adapter.setMfaMethods(userId, []);
+    }
+};
+export const regenerateRecoveryCodes = async (userId, code) => {
+    const adapter = getAuthAdapter();
+    if (!adapter.setRecoveryCodes)
+        throw new HttpError(501, "Auth adapter does not support MFA");
+    const valid = await verifyTotp(userId, code);
+    if (!valid)
+        throw new HttpError(401, "Invalid TOTP code");
+    const { plainCodes, hashedCodes } = generateRecoveryCodes();
+    await adapter.setRecoveryCodes(userId, hashedCodes);
+    return plainCodes;
+};
+// ---------------------------------------------------------------------------
+// Email OTP
+// ---------------------------------------------------------------------------
+/** Generate a cryptographically random numeric OTP code. Returns { code, hash }. */
+export const generateEmailOtpCode = (length) => {
+    const len = length ?? getMfaEmailOtpCodeLength();
+    const bytes = crypto.getRandomValues(new Uint8Array(len));
+    let code = "";
+    for (let i = 0; i < len; i++) {
+        code += (bytes[i] % 10).toString();
+    }
+    return { code, hash: sha256(code) };
+};
+/** Verify an email OTP code against a stored hash. */
+export const verifyEmailOtp = (emailOtpHash, code) => {
+    return sha256(code) === emailOtpHash;
+};
+/**
+ * Initiate email OTP setup: sends a verification code to the user's email.
+ * Returns a setup challenge token that must be confirmed via confirmEmailOtp.
+ */
+export const initiateEmailOtp = async (userId) => {
+    const adapter = getAuthAdapter();
+    const emailOtpConfig = getMfaEmailOtpConfig();
+    if (!emailOtpConfig)
+        throw new HttpError(501, "Email OTP is not configured");
+    const user = adapter.getUser ? await adapter.getUser(userId) : null;
+    if (!user?.email)
+        throw new HttpError(400, "No email address on account");
+    const { code, hash } = generateEmailOtpCode();
+    await emailOtpConfig.onSend(user.email, code);
+    // Store the hash in a challenge token for verification
+    const setupToken = await createMfaChallenge(userId, hash);
+    return setupToken;
+};
+/**
+ * Confirm email OTP setup: verifies the code sent during initiateEmailOtp.
+ * Enables email OTP as an MFA method. Returns recovery codes if MFA was not previously active.
+ */
+export const confirmEmailOtp = async (userId, setupToken, code) => {
+    const adapter = getAuthAdapter();
+    if (!adapter.setMfaEnabled || !adapter.setRecoveryCodes) {
+        throw new HttpError(501, "Auth adapter does not support MFA");
+    }
+    // Import consumeMfaChallenge here to avoid circular dependency issues at module level
+    const { consumeMfaChallenge } = await import("../lib/mfaChallenge");
+    const challenge = await consumeMfaChallenge(setupToken);
+    if (!challenge)
+        throw new HttpError(401, "Invalid or expired setup token");
+    if (challenge.userId !== userId)
+        throw new HttpError(401, "Token does not match user");
+    if (!challenge.emailOtpHash)
+        throw new HttpError(400, "Invalid setup token — no OTP hash");
+    if (!verifyEmailOtp(challenge.emailOtpHash, code)) {
+        throw new HttpError(401, "Invalid verification code");
+    }
+    // Check if MFA was already active
+    const wasEnabled = adapter.isMfaEnabled ? await adapter.isMfaEnabled(userId) : false;
+    // Add "emailOtp" to mfaMethods
+    if (adapter.getMfaMethods && adapter.setMfaMethods) {
+        const methods = await adapter.getMfaMethods(userId);
+        if (!methods.includes("emailOtp")) {
+            await adapter.setMfaMethods(userId, [...methods, "emailOtp"]);
+        }
+    }
+    await adapter.setMfaEnabled(userId, true);
+    // Generate recovery codes if MFA was not previously active
+    if (!wasEnabled) {
+        const { plainCodes, hashedCodes } = generateRecoveryCodes();
+        await adapter.setRecoveryCodes(userId, hashedCodes);
+        return plainCodes;
+    }
+    // Regenerate recovery codes when adding a second method
+    const { plainCodes, hashedCodes } = generateRecoveryCodes();
+    await adapter.setRecoveryCodes(userId, hashedCodes);
+    return plainCodes;
+};
+/**
+ * Disable email OTP for a user.
+ * If TOTP is also enabled, requires a TOTP code. Otherwise requires password.
+ */
+export const disableEmailOtp = async (userId, params) => {
+    const adapter = getAuthAdapter();
+    if (!adapter.setMfaEnabled)
+        throw new HttpError(501, "Auth adapter does not support MFA");
+    // Get current methods
+    const methods = adapter.getMfaMethods ? await adapter.getMfaMethods(userId) : [];
+    const hasTotpEnabled = methods.includes("totp");
+    // Verify identity
+    if (hasTotpEnabled) {
+        if (!params.code)
+            throw new HttpError(400, "TOTP code required to disable email OTP");
+        const valid = await verifyTotp(userId, params.code);
+        if (!valid)
+            throw new HttpError(401, "Invalid TOTP code");
+    }
+    else {
+        if (!params.password)
+            throw new HttpError(400, "Password required to disable email OTP");
+        // Verify password — look up the user's hash and compare
+        const user = adapter.findByIdentifier
+            ? await adapter.findByIdentifier((await adapter.getUser?.(userId))?.email ?? "")
+            : await adapter.findByEmail((await adapter.getUser?.(userId))?.email ?? "");
+        if (!user)
+            throw new HttpError(404, "User not found");
+        const valid = await Bun.password.verify(params.password, user.passwordHash);
+        if (!valid)
+            throw new HttpError(401, "Invalid password");
+    }
+    // Remove "emailOtp" from methods
+    if (adapter.setMfaMethods) {
+        const updated = methods.filter((m) => m !== "emailOtp");
+        await adapter.setMfaMethods(userId, updated);
+        // If no methods remain, disable MFA entirely
+        if (updated.length === 0) {
+            await adapter.setMfaEnabled(userId, false);
+            if (adapter.setRecoveryCodes)
+                await adapter.setRecoveryCodes(userId, []);
+        }
+    }
+};
+/** Get the MFA methods enabled for a user. */
+export const getMfaMethods = async (userId) => {
+    const adapter = getAuthAdapter();
+    if (adapter.getMfaMethods)
+        return adapter.getMfaMethods(userId);
+    // Backward compat
+    if (adapter.isMfaEnabled && await adapter.isMfaEnabled(userId))
+        return ["totp"];
+    return [];
+};

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

@@ -0,0 +1,35 @@
+## 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

@@ -0,0 +1,125 @@
+## 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

@@ -0,0 +1,13 @@
+## 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.