@lastshotlabs/bunshot 0.0.13 → 0.0.16

package/dist/middleware/requireRole.js

@@ -2,9 +2,11 @@ import { getAuthAdapter } from "../lib/authAdapter";
 /**
  * Middleware factory that enforces role-based access.
  * Requires `identify` to have run first (authUserId must be set).
- * Roles are fetched lazily on the first role-checked route and cached on the context.
  *
- * The adapter must implement `getRoles` for this to work.
+ * When tenant context exists (`tenantId` set on context), checks tenant-scoped roles.
+ * Falls back to app-wide roles when no tenant context is present.
+ *
+ * The adapter must implement `getRoles` (and `getTenantRoles` for tenant-scoped checks).
  *
  * @example
  * // Allow any authenticated user with the "admin" role
@@ -13,15 +15,25 @@ import { getAuthAdapter } from "../lib/authAdapter";
  * // Allow users with either "admin" or "moderator"
  * app.get("/mod", userAuth, requireRole("admin", "moderator"), handler)
  */
-export const requireRole = (...roles) => async (c, next) => {
+export const requireRole = Object.assign((...roles) => async (c, next) => {
     const userId = c.get("authUserId");
     if (!userId) {
         return c.json({ error: "Unauthorized" }, 401);
     }
-    // Lazy-fetch roles and cache on context so multiple requireRole calls in a chain only hit the adapter once
+    const adapter = getAuthAdapter();
+    const tenantId = c.get("tenantId");
+    // When tenant context exists and adapter supports tenant roles, check tenant-scoped roles
+    if (tenantId && adapter.getTenantRoles) {
+        const tenantRoles = await adapter.getTenantRoles(userId, tenantId);
+        const hasRole = roles.some((role) => tenantRoles.includes(role));
+        if (!hasRole) {
+            return c.json({ error: "Forbidden" }, 403);
+        }
+        return next();
+    }
+    // Fall back to app-wide roles
     let userRoles = c.get("roles");
     if (userRoles === null) {
-        const adapter = getAuthAdapter();
         if (!adapter.getRoles) {
             throw new Error("requireRole used but auth adapter does not implement getRoles");
         }
@@ -33,4 +45,32 @@ export const requireRole = (...roles) => async (c, next) => {
         return c.json({ error: "Forbidden" }, 403);
     }
     await next();
-};
+}, {
+    /**
+     * Always checks app-wide roles regardless of tenant context.
+     * Use for super-admin gates that should ignore tenant scoping.
+     *
+     * @example
+     * app.get("/super-admin", userAuth, requireRole.global("superadmin"), handler)
+     */
+    global: (...roles) => async (c, next) => {
+        const userId = c.get("authUserId");
+        if (!userId) {
+            return c.json({ error: "Unauthorized" }, 401);
+        }
+        let userRoles = c.get("roles");
+        if (userRoles === null) {
+            const adapter = getAuthAdapter();
+            if (!adapter.getRoles) {
+                throw new Error("requireRole.global used but auth adapter does not implement getRoles");
+            }
+            userRoles = await adapter.getRoles(userId);
+            c.set("roles", userRoles);
+        }
+        const hasRole = roles.some((role) => userRoles.includes(role));
+        if (!hasRole) {
+            return c.json({ error: "Forbidden" }, 403);
+        }
+        await next();
+    },
+});

package/dist/middleware/tenant.d.ts

@@ -0,0 +1,5 @@
+import type { MiddlewareHandler } from "hono";
+import type { AppEnv } from "../lib/context";
+import type { TenancyConfig } from "../app";
+export declare const invalidateTenantCache: (tenantId: string) => void;
+export declare const createTenantMiddleware: (config: TenancyConfig) => MiddlewareHandler<AppEnv>;

package/dist/middleware/tenant.js

@@ -0,0 +1,116 @@
+class LruCache {
+    _map = new Map();
+    _maxSize;
+    _ttlMs;
+    constructor(maxSize, ttlMs) {
+        this._maxSize = maxSize;
+        this._ttlMs = ttlMs;
+    }
+    get(key) {
+        const entry = this._map.get(key);
+        if (!entry)
+            return undefined; // cache miss
+        if (entry.expiresAt <= Date.now()) {
+            this._map.delete(key);
+            return undefined; // expired
+        }
+        // Move to end (most recently used)
+        this._map.delete(key);
+        this._map.set(key, entry);
+        return entry.value;
+    }
+    set(key, value) {
+        // Remove first if exists (for re-insertion at end)
+        this._map.delete(key);
+        // Evict oldest if at capacity
+        if (this._map.size >= this._maxSize) {
+            const oldest = this._map.keys().next().value;
+            if (oldest !== undefined)
+                this._map.delete(oldest);
+        }
+        this._map.set(key, { value, expiresAt: Date.now() + this._ttlMs });
+    }
+    delete(key) {
+        this._map.delete(key);
+    }
+}
+// ---------------------------------------------------------------------------
+// Exported cache invalidation (used by tenant provisioning helpers)
+// ---------------------------------------------------------------------------
+let _cache = null;
+export const invalidateTenantCache = (tenantId) => {
+    _cache?.delete(tenantId);
+};
+// ---------------------------------------------------------------------------
+// Tenant resolution middleware
+// ---------------------------------------------------------------------------
+const DEFAULT_EXEMPT = ["/health", "/docs", "/openapi.json", "/auth/"];
+function extractTenantId(c, config) {
+    if (config.resolution === "header") {
+        const headerName = config.headerName ?? "x-tenant-id";
+        return c.req.header(headerName) ?? null;
+    }
+    if (config.resolution === "subdomain") {
+        const host = c.req.header("host") ?? "";
+        // Extract first subdomain: "acme.myapp.com" → "acme"
+        const parts = host.split(".");
+        if (parts.length < 3)
+            return null; // no subdomain
+        return parts[0] || null;
+    }
+    if (config.resolution === "path") {
+        const segmentIndex = config.pathSegment ?? 0;
+        // Path: "/acme/api/users" → segments after split: ["", "acme", "api", "users"]
+        const segments = c.req.path.split("/").filter(Boolean);
+        return segments[segmentIndex] ?? null;
+    }
+    return null;
+}
+export const createTenantMiddleware = (config) => {
+    const exemptPaths = [...DEFAULT_EXEMPT, ...(config.exemptPaths ?? [])];
+    const rejectionStatus = config.rejectionStatus ?? 403;
+    const cacheTtlMs = config.cacheTtlMs ?? 60_000;
+    const cacheMaxSize = config.cacheMaxSize ?? 500;
+    // Initialize LRU cache if caching is enabled and onResolve is provided
+    if (config.onResolve && cacheTtlMs > 0) {
+        _cache = new LruCache(cacheMaxSize, cacheTtlMs);
+    }
+    return async (c, next) => {
+        const path = c.req.path;
+        // Check exempt paths using startsWith
+        for (const exempt of exemptPaths) {
+            if (path === exempt || path.startsWith(exempt)) {
+                c.set("tenantId", null);
+                c.set("tenantConfig", null);
+                return next();
+            }
+        }
+        const tenantId = extractTenantId(c, config);
+        if (!tenantId) {
+            return c.json({ error: "Tenant ID required" }, 400);
+        }
+        // Validate via onResolve (with caching)
+        if (config.onResolve) {
+            let tenantConfig;
+            if (_cache) {
+                tenantConfig = _cache.get(tenantId);
+            }
+            // undefined = cache miss, null = onResolve returned null (rejected)
+            if (tenantConfig === undefined) {
+                tenantConfig = await config.onResolve(tenantId);
+                _cache?.set(tenantId, tenantConfig);
+            }
+            if (tenantConfig === null) {
+                return c.json({ error: "Access denied" }, rejectionStatus);
+            }
+            c.set("tenantId", tenantId);
+            c.set("tenantConfig", tenantConfig);
+        }
+        else {
+            // No onResolve — trust the tenant ID
+            c.set("tenantId", tenantId);
+            c.set("tenantConfig", null);
+        }
+        return next();
+    };
+};

package/dist/models/AuthUser.d.ts

@@ -8,6 +8,14 @@ interface IAuthUser {
     roles: string[];
     /** Whether the user's email address has been verified. */
     emailVerified: boolean;
+    /** TOTP secret for MFA. Null when MFA is not set up. */
+    mfaSecret?: string | null;
+    /** Whether MFA is enabled (secret stored + confirmed via TOTP code). */
+    mfaEnabled?: boolean;
+    /** SHA-256 hashed recovery codes for MFA. */
+    recoveryCodes?: string[];
+    /** MFA methods enabled for this user (e.g., ["totp"], ["emailOtp"], ["totp", "emailOtp"]). */
+    mfaMethods?: string[];
 }
 type AuthUserDocument = IAuthUser & Document;
 export declare const AuthUser: Model<AuthUserDocument, {}, {}, {}, Document<unknown, {}, AuthUserDocument, {}, import("mongoose").DefaultSchemaOptions> & IAuthUser & Document<import("mongoose").Types.ObjectId, any, any, Record<string, any>, {}> & Required<{

package/dist/models/AuthUser.js

@@ -14,6 +14,14 @@ function getAuthUser() {
             roles: [{ type: String }],
             /** Whether the user's email address has been verified. */
             emailVerified: { type: Boolean, default: false },
+            /** TOTP secret for MFA. */
+            mfaSecret: { type: String, default: null },
+            /** Whether MFA is enabled. */
+            mfaEnabled: { type: Boolean, default: false },
+            /** SHA-256 hashed recovery codes for MFA. */
+            recoveryCodes: [{ type: String }],
+            /** MFA methods enabled for this user. */
+            mfaMethods: [{ type: String }],
         }, { timestamps: true });
         schema.index({ providerIds: 1 });
         _AuthUser = authConnection.model("AuthUser", schema);

package/dist/models/TenantRole.d.ts

@@ -0,0 +1,15 @@
+import type { Document, Model } from "mongoose";
+interface ITenantRole {
+    userId: string;
+    tenantId: string;
+    roles: string[];
+}
+type TenantRoleDocument = ITenantRole & Document;
+export declare const TenantRole: Model<TenantRoleDocument, {}, {}, {}, Document<unknown, {}, TenantRoleDocument, {}, import("mongoose").DefaultSchemaOptions> & ITenantRole & Document<import("mongoose").Types.ObjectId, any, any, Record<string, any>, {}> & Required<{
+    _id: import("mongoose").Types.ObjectId;
+}> & {
+    __v: number;
+} & {
+    id: string;
+}, any, TenantRoleDocument>;
+export {};

package/dist/models/TenantRole.js

@@ -0,0 +1,23 @@
+import { authConnection, mongoose } from "../lib/mongo";
+let _TenantRole = null;
+function getTenantRole() {
+    if (!_TenantRole) {
+        const { Schema } = mongoose;
+        const schema = new Schema({
+            userId: { type: String, required: true },
+            tenantId: { type: String, required: true },
+            roles: [{ type: String }],
+        }, { timestamps: true });
+        schema.index({ userId: 1, tenantId: 1 }, { unique: true });
+        schema.index({ tenantId: 1 });
+        _TenantRole = authConnection.model("TenantRole", schema);
+    }
+    return _TenantRole;
+}
+export const TenantRole = new Proxy({}, {
+    get(_, prop) {
+        const model = getTenantRole();
+        const val = model[prop];
+        return typeof val === "function" ? val.bind(model) : val;
+    },
+});

package/dist/routes/auth.d.ts

@@ -1,9 +1,11 @@
-import type { PrimaryField, EmailVerificationConfig, PasswordResetConfig } from "../lib/appConfig";
-import type { AuthRateLimitConfig } from "../app";
+import type { PrimaryField, EmailVerificationConfig, PasswordResetConfig, RefreshTokenConfig } from "../lib/appConfig";
+import type { AuthRateLimitConfig, AccountDeletionConfig } from "../app";
 export interface AuthRouterOptions {
     primaryField: PrimaryField;
     emailVerification?: EmailVerificationConfig;
     passwordReset?: PasswordResetConfig;
     rateLimit?: AuthRateLimitConfig;
+    accountDeletion?: AccountDeletionConfig;
+    refreshTokens?: RefreshTokenConfig;
 }
-export declare const createAuthRouter: ({ primaryField, emailVerification, passwordReset, rateLimit }: AuthRouterOptions) => import("@hono/zod-openapi").OpenAPIHono<import("../lib/context").AppEnv, {}, "/">;
+export declare const createAuthRouter: ({ primaryField, emailVerification, passwordReset, rateLimit, accountDeletion, refreshTokens }: AuthRouterOptions) => import("@hono/zod-openapi").OpenAPIHono<import("../lib/context").AppEnv, {}, "/">;

package/dist/routes/auth.js

@@ -3,33 +3,38 @@ import { z } from "zod";
 import { setCookie, getCookie, deleteCookie } from "hono/cookie";
 import * as AuthService from "../services/auth";
 import { makeRegisterSchema, makeLoginSchema } from "../schemas/auth";
-import { COOKIE_TOKEN, HEADER_USER_TOKEN } from "../lib/constants";
+import { COOKIE_TOKEN, HEADER_USER_TOKEN, COOKIE_REFRESH_TOKEN, HEADER_REFRESH_TOKEN } from "../lib/constants";
 import { userAuth } from "../middleware/userAuth";
 import { isLimited, trackAttempt, bustAuthLimit } from "../lib/authRateLimit";
 import { getAuthAdapter } from "../lib/authAdapter";
 import { createRouter } from "../lib/context";
 import { getVerificationToken, deleteVerificationToken, createVerificationToken } from "../lib/emailVerification";
 import { createResetToken, consumeResetToken } from "../lib/resetPassword";
-import { getUserSessions, deleteSession } from "../lib/session";
+import { getRefreshTokenExpiry, getAccessTokenExpiry } from "../lib/appConfig";
+import { getUserSessions, deleteSession, deleteUserSessions } from "../lib/session";
 const isProd = process.env.NODE_ENV === "production";
 const TokenResponse = z.object({
-    token: z.string().describe("JWT session token. Also set as an HttpOnly session cookie."),
+    token: z.string().describe("JWT session token. Also set as an HttpOnly session cookie. Empty string when mfaRequired is true."),
     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."),
+    refreshToken: z.string().optional().describe("Refresh token (present when refreshTokens is configured). Also set as an HttpOnly cookie."),
+    mfaRequired: z.boolean().optional().describe("When true, complete MFA via POST /auth/mfa/verify before accessing the API."),
+    mfaToken: z.string().optional().describe("MFA challenge token. Pass to POST /auth/mfa/verify with a TOTP or recovery code."),
+    mfaMethods: z.array(z.string()).optional().describe("Available MFA methods when mfaRequired is true (e.g., 'totp', 'emailOtp')."),
 }).openapi("TokenResponse");
 const ErrorResponse = z.object({ error: z.string().describe("Human-readable error message.") }).openapi("ErrorResponse");
 const tags = ["Auth"];
-const cookieOptions = {
+const cookieOptions = (maxAge) => ({
     httpOnly: true,
     secure: isProd,
     sameSite: "Lax",
     path: "/",
-    maxAge: 60 * 60 * 24 * 7, // 7 days
-};
+    maxAge: maxAge ?? 60 * 60 * 24 * 7, // 7 days
+});
 const clientIp = (xff, xri) => (xff ? xff.split(",")[0]?.trim() : undefined) ?? xri ?? undefined;
-export const createAuthRouter = ({ primaryField, emailVerification, passwordReset, rateLimit }) => {
+export const createAuthRouter = ({ primaryField, emailVerification, passwordReset, rateLimit, accountDeletion, refreshTokens }) => {
     const router = createRouter();
     const RegisterSchema = makeRegisterSchema(primaryField);
     const LoginSchema = makeLoginSchema(primaryField);
@@ -67,7 +72,10 @@ export const createAuthRouter = ({ primaryField, emailVerification, passwordRese
             userAgent: c.req.header("user-agent") ?? undefined,
         };
         const result = await AuthService.register(identifier, body.password, metadata);
-        setCookie(c, COOKIE_TOKEN, result.token, cookieOptions);
+        setCookie(c, COOKIE_TOKEN, result.token, cookieOptions(refreshTokens ? getAccessTokenExpiry() : undefined));
+        if (result.refreshToken) {
+            setCookie(c, COOKIE_REFRESH_TOKEN, result.refreshToken, cookieOptions(getRefreshTokenExpiry()));
+        }
         return c.json(result, 201);
     });
     router.openapi(createRoute({
@@ -97,7 +105,12 @@ export const createAuthRouter = ({ primaryField, emailVerification, passwordRese
         try {
             const result = await AuthService.login(identifier, body.password, metadata);
             await bustAuthLimit(limitKey); // success — clear failure count
-            setCookie(c, COOKIE_TOKEN, result.token, cookieOptions);
+            if (!result.mfaRequired) {
+                setCookie(c, COOKIE_TOKEN, result.token, cookieOptions(refreshTokens ? getAccessTokenExpiry() : undefined));
+                if (result.refreshToken) {
+                    setCookie(c, COOKIE_REFRESH_TOKEN, result.refreshToken, cookieOptions(getRefreshTokenExpiry()));
+                }
+            }
             return c.json(result, 200);
         }
         catch (err) {
@@ -135,6 +148,74 @@ export const createAuthRouter = ({ primaryField, emailVerification, passwordRese
         const googleLinked = user?.providerIds?.some((id) => id.startsWith("google:")) ?? false;
         return c.json({ userId: authUserId, email: user?.email, emailVerified: user?.emailVerified, googleLinked }, 200);
     });
+    // ---------------------------------------------------------------------------
+    // Account deletion
+    // ---------------------------------------------------------------------------
+    const deleteAccountOpts = { windowMs: rateLimit?.deleteAccount?.windowMs ?? 60 * 60 * 1000, max: rateLimit?.deleteAccount?.max ?? 3 };
+    router.openapi(withSecurity(createRoute({
+        method: "delete",
+        path: "/auth/me",
+        summary: "Delete account",
+        description: "Permanently deletes the authenticated user's account. Requires password confirmation for credential accounts. MFA is not required — the password serves as the identity check. Revokes all active sessions.",
+        tags,
+        request: {
+            body: {
+                content: {
+                    "application/json": {
+                        schema: z.object({
+                            password: z.string().optional().describe("Current password. Required for credential accounts, optional for OAuth-only accounts."),
+                        }),
+                    },
+                },
+                description: "Password confirmation.",
+            },
+        },
+        responses: {
+            200: { content: { "application/json": { schema: z.object({ message: z.string() }) } }, description: "Account deleted." },
+            202: { content: { "application/json": { schema: z.object({ message: z.string() }) } }, description: "Account deletion has been scheduled." },
+            400: { content: { "application/json": { schema: ErrorResponse } }, description: "Password is required for credential accounts." },
+            401: { content: { "application/json": { schema: ErrorResponse } }, description: "Invalid password or no valid session." },
+            429: { content: { "application/json": { schema: ErrorResponse } }, description: "Too many deletion attempts. Try again later." },
+            501: { content: { "application/json": { schema: ErrorResponse } }, description: "The configured auth adapter does not support deleteUser." },
+        },
+    }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
+        const authUserId = c.get("authUserId");
+        if (await trackAttempt(`deleteaccount:${authUserId}`, deleteAccountOpts)) {
+            return c.json({ error: "Too many deletion attempts. Try again later." }, 429);
+        }
+        const adapter = getAuthAdapter();
+        if (!adapter.deleteUser) {
+            return c.json({ error: "Auth adapter does not support deleteUser" }, 501);
+        }
+        const { password } = c.req.valid("json");
+        // Verify password for credential accounts
+        if (password) {
+            const user = adapter.getUser ? await adapter.getUser(authUserId) : 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))) {
+                    return c.json({ error: "Invalid password" }, 401);
+                }
+            }
+        }
+        else if (adapter.hasPassword && await adapter.hasPassword(authUserId)) {
+            return c.json({ error: "Password is required to delete a credential account" }, 400);
+        }
+        // Call onBeforeDelete hook
+        if (accountDeletion?.onBeforeDelete) {
+            await accountDeletion.onBeforeDelete(authUserId);
+        }
+        // Synchronous deletion (default)
+        await deleteUserSessions(authUserId);
+        await adapter.deleteUser(authUserId);
+        if (accountDeletion?.onAfterDelete) {
+            await accountDeletion.onAfterDelete(authUserId);
+        }
+        deleteCookie(c, COOKIE_TOKEN, { path: "/" });
+        return c.json({ message: "Account deleted" }, 200);
+    });
     router.use("/auth/set-password", userAuth);
     router.openapi(withSecurity(createRoute({
         method: "post",
@@ -173,6 +254,7 @@ export const createAuthRouter = ({ primaryField, emailVerification, passwordRese
         const token = getCookie(c, COOKIE_TOKEN) ?? c.req.header(HEADER_USER_TOKEN) ?? null;
         await AuthService.logout(token);
         deleteCookie(c, COOKIE_TOKEN, { path: "/" });
+        deleteCookie(c, COOKIE_REFRESH_TOKEN, { path: "/" });
         return c.json({ message: "Logged out" }, 200);
     });
     // Email verification routes — only mounted when emailVerification is configured and primaryField is "email"
@@ -204,37 +286,43 @@ export const createAuthRouter = ({ primaryField, emailVerification, passwordRese
             await deleteVerificationToken(token);
             return c.json({ message: "Email verified" }, 200);
         });
-        router.use("/auth/resend-verification", userAuth);
-        router.openapi(withSecurity(createRoute({
+        router.openapi(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.",
+            description: "Authenticates with credentials and sends a new verification email. Returns 400 if already verified. Rate-limited per identifier. Does not require a session.",
             tags,
+            request: { body: { content: { "application/json": { schema: LoginSchema } }, description: "Login credentials to identify the account." } },
             responses: {
                 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." },
+                401: { content: { "application/json": { schema: ErrorResponse } }, description: "Invalid credentials." },
+                429: { content: { "application/json": { schema: ErrorResponse } }, description: "Too many resend attempts for this identifier. Try again later." },
                 501: { content: { "application/json": { schema: ErrorResponse } }, description: "The configured auth adapter does not support email verification." },
             },
-        }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
+        }), async (c) => {
             const adapter = getAuthAdapter();
             if (!adapter.getEmailVerified || !adapter.getUser) {
                 return c.json({ error: "Auth adapter does not support email verification" }, 501);
             }
-            const authUserId = c.get("authUserId");
-            if (await trackAttempt(`resend:${authUserId}`, resendOpts)) {
+            const body = c.req.valid("json");
+            const identifier = body[primaryField];
+            if (await trackAttempt(`resend:${identifier}`, resendOpts)) {
                 return c.json({ error: "Too many resend attempts. Try again later." }, 429);
             }
-            const alreadyVerified = await adapter.getEmailVerified(authUserId);
+            const findFn = adapter.findByIdentifier ?? adapter.findByEmail.bind(adapter);
+            const user = await findFn(identifier);
+            if (!user || !(await Bun.password.verify(body.password, user.passwordHash))) {
+                return c.json({ error: "Invalid credentials" }, 401);
+            }
+            const alreadyVerified = await adapter.getEmailVerified(user.id);
             if (alreadyVerified)
                 return c.json({ error: "Email already verified" }, 400);
-            const user = await adapter.getUser(authUserId);
-            if (!user?.email)
+            const fullUser = await adapter.getUser(user.id);
+            if (!fullUser?.email)
                 return c.json({ error: "No email address on file" }, 400);
-            const verificationToken = await createVerificationToken(authUserId, user.email);
-            await emailVerification.onSend(user.email, verificationToken);
+            const verificationToken = await createVerificationToken(user.id, fullUser.email);
+            await emailVerification.onSend(fullUser.email, verificationToken);
             return c.json({ message: "Verification email sent" }, 200);
         });
     }
@@ -327,6 +415,49 @@ export const createAuthRouter = ({ primaryField, emailVerification, passwordRese
         });
     }
     // ---------------------------------------------------------------------------
+    // Refresh token route — only mounted when refreshTokens is configured
+    // ---------------------------------------------------------------------------
+    if (refreshTokens) {
+        const RefreshResponse = z.object({
+            token: z.string().describe("New short-lived JWT access token."),
+            refreshToken: z.string().describe("New refresh token (rotation). The previous token is valid for a short grace window."),
+            userId: z.string().describe("Unique user ID."),
+        }).openapi("RefreshResponse");
+        router.openapi(createRoute({
+            method: "post",
+            path: "/auth/refresh",
+            summary: "Refresh access token",
+            description: "Exchanges a valid refresh token for a new access token and rotated refresh token. The old refresh token remains valid for a short grace window to handle network drops. If a previously rotated token is reused after the grace window, the entire session is invalidated (token theft detection).",
+            tags,
+            request: {
+                body: {
+                    content: {
+                        "application/json": {
+                            schema: z.object({
+                                refreshToken: z.string().optional().describe("Refresh token. Can also be sent via the refresh_token cookie or x-refresh-token header."),
+                            }),
+                        },
+                    },
+                    description: "Refresh token (optional if sent via cookie or header).",
+                },
+            },
+            responses: {
+                200: { content: { "application/json": { schema: RefreshResponse } }, description: "New access and refresh tokens." },
+                401: { content: { "application/json": { schema: ErrorResponse } }, description: "Invalid or expired refresh token, or session invalidated due to token theft detection." },
+            },
+        }), async (c) => {
+            const body = c.req.valid("json");
+            const rt = body.refreshToken ?? getCookie(c, COOKIE_REFRESH_TOKEN) ?? c.req.header(HEADER_REFRESH_TOKEN) ?? null;
+            if (!rt) {
+                return c.json({ error: "Refresh token is required" }, 401);
+            }
+            const result = await AuthService.refresh(rt);
+            setCookie(c, COOKIE_TOKEN, result.token, cookieOptions(getAccessTokenExpiry()));
+            setCookie(c, COOKIE_REFRESH_TOKEN, result.refreshToken, cookieOptions(getRefreshTokenExpiry()));
+            return c.json(result, 200);
+        });
+    }
+    // ---------------------------------------------------------------------------
     // Session management
     // ---------------------------------------------------------------------------
     const SessionInfoSchema = z.object({

package/dist/routes/jobs.d.ts

@@ -0,0 +1,2 @@
+import type { JobsConfig } from "../app";
+export declare const createJobsRouter: (config: JobsConfig) => import("@hono/zod-openapi").OpenAPIHono<import("../lib/context").AppEnv, {}, "/">;