@lastshotlabs/bunshot 0.0.13 → 0.0.18

package/dist/routes/auth.js

@@ -2,34 +2,40 @@ import { createRoute, withSecurity } from "../lib/createRoute";
 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 { makeRegisterSchema, makeLoginSchema, resetPasswordSchema } from "../schemas/auth";
+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, getCsrfEnabled } from "../lib/appConfig";
+import { refreshCsrfToken, clearCsrfToken } from "../middleware/csrf";
+import { getUserSessions, deleteSession, deleteUserSessions } from "../lib/session";
+import { getClientIp } from "../lib/clientIp";
 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
-};
-const clientIp = (xff, xri) => (xff ? xff.split(",")[0]?.trim() : undefined) ?? xri ?? undefined;
-export const createAuthRouter = ({ primaryField, emailVerification, passwordReset, rateLimit }) => {
+    maxAge: maxAge ?? 60 * 60 * 24 * 7, // 7 days
+});
+export const createAuthRouter = ({ primaryField, emailVerification, passwordReset, rateLimit, accountDeletion, refreshTokens }) => {
     const router = createRouter();
     const RegisterSchema = makeRegisterSchema(primaryField);
     const LoginSchema = makeLoginSchema(primaryField);
@@ -56,7 +62,7 @@ export const createAuthRouter = ({ primaryField, emailVerification, passwordRese
             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";
+        const ip = getClientIp(c);
         if (await trackAttempt(`register:${ip}`, registerOpts)) {
             return c.json({ error: "Too many registration attempts. Try again later." }, 429);
         }
@@ -67,7 +73,12 @@ 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()));
+        }
+        if (getCsrfEnabled())
+            refreshCsrfToken(c);
         return c.json(result, 201);
     });
     router.openapi(createRoute({
@@ -91,13 +102,20 @@ export const createAuthRouter = ({ primaryField, emailVerification, passwordRese
             return c.json({ error: "Too many failed login attempts. Try again later." }, 429);
         }
         const metadata = {
-            ipAddress: clientIp(c.req.header("x-forwarded-for"), c.req.header("x-real-ip")),
+            ipAddress: getClientIp(c),
             userAgent: c.req.header("user-agent") ?? undefined,
         };
         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()));
+                }
+                if (getCsrfEnabled())
+                    refreshCsrfToken(c);
+            }
             return c.json(result, 200);
         }
         catch (err) {
@@ -135,6 +153,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 +259,9 @@ 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: "/" });
+        if (getCsrfEnabled())
+            clearCsrfToken(c);
         return c.json({ message: "Logged out" }, 200);
     });
     // Email verification routes — only mounted when emailVerification is configured and primaryField is "email"
@@ -190,7 +279,7 @@ export const createAuthRouter = ({ primaryField, emailVerification, passwordRese
                 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";
+            const ip = getClientIp(c);
             if (await trackAttempt(`verify:${ip}`, verifyOpts)) {
                 return c.json({ error: "Too many verification attempts. Try again later." }, 429);
             }
@@ -204,37 +293,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);
         });
     }
@@ -253,7 +348,7 @@ export const createAuthRouter = ({ primaryField, emailVerification, passwordRese
                 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";
+            const ip = getClientIp(c);
             const { email } = c.req.valid("json");
             // Rate-limit by both IP and email to prevent distributed email-bombing
             const ipLimited = await trackAttempt(`forgot:ip:${ip}`, forgotOpts);
@@ -291,7 +386,7 @@ export const createAuthRouter = ({ primaryField, emailVerification, passwordRese
                         "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."),
+                                password: resetPasswordSchema().describe("New password."),
                             }),
                         },
                     },
@@ -305,7 +400,7 @@ export const createAuthRouter = ({ primaryField, emailVerification, passwordRese
                 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";
+            const ip = getClientIp(c);
             if (await trackAttempt(`reset:${ip}`, resetOpts)) {
                 return c.json({ error: "Too many attempts. Try again later." }, 429);
             }
@@ -327,6 +422,54 @@ 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." },
+                429: { content: { "application/json": { schema: ErrorResponse } }, description: "Too many refresh attempts. Try again later." },
+            },
+        }), async (c) => {
+            const ip = getClientIp(c);
+            if (await trackAttempt(`refresh:ip:${ip}`, { max: 30, windowMs: 60_000 })) {
+                return c.json({ error: "Too many refresh attempts. Try again later." }, 429);
+            }
+            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, {}, "/">;

package/dist/routes/jobs.js

@@ -0,0 +1,270 @@
+import { createRoute, withSecurity } from "../lib/createRoute";
+import { z } from "zod";
+import { createRouter } from "../lib/context";
+import { userAuth } from "../middleware/userAuth";
+import { requireRole } from "../middleware/requireRole";
+import { createQueue } from "../lib/queue";
+const tags = ["Jobs"];
+const ErrorResponse = z.object({ error: z.string() });
+const JobStatusResponse = z.object({
+    id: z.string().describe("Job ID."),
+    state: z.string().describe("Job state: waiting, active, completed, failed, delayed, paused."),
+    progress: z.union([z.number(), z.record(z.string(), z.unknown())]).describe("Job progress."),
+    result: z.unknown().optional().describe("Job result (when completed)."),
+    failedReason: z.string().optional().describe("Failure reason (when failed)."),
+    attemptsMade: z.number().describe("Number of attempts made."),
+    timestamp: z.number().describe("Unix timestamp (ms) when the job was created."),
+    finishedOn: z.number().optional().describe("Unix timestamp (ms) when the job finished."),
+}).openapi("JobStatus");
+export const createJobsRouter = (config) => {
+    const router = createRouter();
+    const allowedQueues = new Set(config.allowedQueues ?? []);
+    const authConfig = config.auth ?? "none";
+    const scopeToUser = config.scopeToUser ?? false;
+    // Determine if userAuth is involved (for scopeToUser and OpenAPI security schemes)
+    const hasUserAuth = authConfig === "userAuth" || Array.isArray(authConfig);
+    // Apply middleware based on config
+    if (authConfig === "userAuth") {
+        router.use("/jobs/*", userAuth);
+        if (config.roles?.length) {
+            router.use("/jobs/*", requireRole(...config.roles));
+        }
+    }
+    else if (Array.isArray(authConfig)) {
+        for (const mw of authConfig) {
+            router.use("/jobs/*", mw);
+        }
+    }
+    // "none" requires no middleware
+    function isQueueAllowed(queueName) {
+        return allowedQueues.has(queueName);
+    }
+    /** Determine OpenAPI security for a route */
+    function applyRouteSecurity(route) {
+        if (authConfig === "userAuth") {
+            return withSecurity(route, { cookieAuth: [] }, { userToken: [] });
+        }
+        if (Array.isArray(authConfig)) {
+            // Custom middleware — mark as cookieAuth/userToken if it likely includes userAuth
+            return withSecurity(route, { cookieAuth: [] }, { userToken: [] });
+        }
+        return route;
+    }
+    /** Map a BullMQ job to the response shape */
+    async function jobToResponse(job) {
+        const state = await job.getState();
+        return {
+            id: job.id,
+            state,
+            progress: job.progress,
+            result: job.returnvalue,
+            failedReason: job.failedReason ?? undefined,
+            attemptsMade: job.attemptsMade,
+            timestamp: job.timestamp,
+            finishedOn: job.finishedOn ?? undefined,
+        };
+    }
+    // ─── List available queues ──────────────────────────────────────────────
+    const listQueuesRoute = createRoute({
+        method: "get",
+        path: "/jobs",
+        summary: "List available queues",
+        description: "Returns the list of queue names exposed via the API.",
+        tags,
+        responses: {
+            200: {
+                content: {
+                    "application/json": {
+                        schema: z.object({
+                            queues: z.array(z.string()).describe("Available queue names."),
+                        }),
+                    },
+                },
+                description: "Available queues.",
+            },
+        },
+    });
+    router.openapi(applyRouteSecurity(listQueuesRoute), async (c) => {
+        return c.json({ queues: [...allowedQueues] }, 200);
+    });
+    // ─── List jobs in a queue ─────────────────────────────────────────────
+    const listJobsRoute = createRoute({
+        method: "get",
+        path: "/jobs/{queue}",
+        summary: "List jobs in a queue",
+        description: "Returns a paginated list of jobs in a queue, optionally filtered by state.",
+        tags,
+        request: {
+            params: z.object({
+                queue: z.string().describe("Queue name."),
+            }),
+            query: z.object({
+                state: z.enum(["waiting", "active", "completed", "failed", "delayed", "paused"]).optional().describe("Filter by job state."),
+                start: z.string().optional().describe("Start index. Default: 0."),
+                end: z.string().optional().describe("End index. Default: 19."),
+            }),
+        },
+        responses: {
+            200: {
+                content: {
+                    "application/json": {
+                        schema: z.object({
+                            jobs: z.array(JobStatusResponse),
+                            total: z.number().describe("Total jobs matching the filter."),
+                        }),
+                    },
+                },
+                description: "Jobs list.",
+            },
+            403: { content: { "application/json": { schema: ErrorResponse } }, description: "Queue not allowed." },
+        },
+    });
+    router.openapi(applyRouteSecurity(listJobsRoute), async (c) => {
+        const { queue: queueName } = c.req.valid("param");
+        if (!isQueueAllowed(queueName)) {
+            return c.json({ error: "Queue not allowed" }, 403);
+        }
+        const { state, start: startStr, end: endStr } = c.req.valid("query");
+        const start = startStr ? parseInt(startStr) : 0;
+        const end = endStr ? parseInt(endStr) : 19;
+        const queue = createQueue(queueName);
+        // Get jobs by state or all jobs
+        const stateFilter = state ?? "waiting";
+        const jobs = await queue.getJobs([stateFilter], start, end);
+        // Get total count for the filtered state
+        const counts = await queue.getJobCounts(stateFilter);
+        const total = counts[stateFilter] ?? 0;
+        // Optionally filter by userId
+        let filteredJobs = jobs;
+        if (scopeToUser && hasUserAuth) {
+            const userId = c.get("authUserId");
+            filteredJobs = jobs.filter((job) => job.data?.userId === userId);
+        }
+        const result = await Promise.all(filteredJobs.map(jobToResponse));
+        return c.json({ jobs: result, total }, 200);
+    });
+    // ─── Get job status ─────────────────────────────────────────────────────
+    const getJobRoute = createRoute({
+        method: "get",
+        path: "/jobs/{queue}/{id}",
+        summary: "Get job status",
+        description: "Returns the current state, progress, result, or failure reason for a job.",
+        tags,
+        request: {
+            params: z.object({
+                queue: z.string().describe("Queue name."),
+                id: z.string().describe("Job ID."),
+            }),
+        },
+        responses: {
+            200: { content: { "application/json": { schema: JobStatusResponse } }, description: "Job status." },
+            403: { content: { "application/json": { schema: ErrorResponse } }, description: "Queue not in allowedQueues." },
+            404: { content: { "application/json": { schema: ErrorResponse } }, description: "Job not found." },
+        },
+    });
+    router.openapi(applyRouteSecurity(getJobRoute), async (c) => {
+        const { queue: queueName, id } = c.req.valid("param");
+        if (!isQueueAllowed(queueName)) {
+            return c.json({ error: "Queue not allowed" }, 403);
+        }
+        const queue = createQueue(queueName);
+        const job = await queue.getJob(id);
+        if (!job)
+            return c.json({ error: "Job not found" }, 404);
+        // Scope to user if configured
+        if (scopeToUser && hasUserAuth) {
+            const userId = c.get("authUserId");
+            if (job.data?.userId !== userId) {
+                return c.json({ error: "Job not found" }, 404);
+            }
+        }
+        return c.json(await jobToResponse(job), 200);
+    });
+    // ─── Get job logs ───────────────────────────────────────────────────────
+    const getJobLogsRoute = createRoute({
+        method: "get",
+        path: "/jobs/{queue}/{id}/logs",
+        summary: "Get job logs",
+        description: "Returns logs for a specific job.",
+        tags,
+        request: {
+            params: z.object({
+                queue: z.string().describe("Queue name."),
+                id: z.string().describe("Job ID."),
+            }),
+        },
+        responses: {
+            200: {
+                content: {
+                    "application/json": {
+                        schema: z.object({
+                            logs: z.array(z.string()).describe("Log entries."),
+                            count: z.number().describe("Total log count."),
+                        }),
+                    },
+                },
+                description: "Job logs.",
+            },
+            403: { content: { "application/json": { schema: ErrorResponse } }, description: "Queue not allowed." },
+            404: { content: { "application/json": { schema: ErrorResponse } }, description: "Job not found." },
+        },
+    });
+    router.openapi(applyRouteSecurity(getJobLogsRoute), async (c) => {
+        const { queue: queueName, id } = c.req.valid("param");
+        if (!isQueueAllowed(queueName)) {
+            return c.json({ error: "Queue not allowed" }, 403);
+        }
+        const queue = createQueue(queueName);
+        const job = await queue.getJob(id);
+        if (!job)
+            return c.json({ error: "Job not found" }, 404);
+        const { logs, count } = await queue.getJobLogs(id);
+        return c.json({ logs, count }, 200);
+    });
+    // ─── Dead letter queue ────────────────────────────────────────────────
+    const getDlqRoute = createRoute({
+        method: "get",
+        path: "/jobs/{queue}/dead-letters",
+        summary: "List dead letter queue jobs",
+        description: "Returns paginated list of jobs in the dead letter queue for a given source queue.",
+        tags,
+        request: {
+            params: z.object({ queue: z.string().describe("Source queue name (DLQ name is {queue}-dlq).") }),
+            query: z.object({
+                start: z.string().optional().describe("Start index. Default: 0."),
+                end: z.string().optional().describe("End index. Default: 19."),
+            }),
+        },
+        responses: {
+            200: {
+                content: {
+                    "application/json": {
+                        schema: z.object({
+                            jobs: z.array(JobStatusResponse),
+                            total: z.number().describe("Total jobs in DLQ."),
+                        }),
+                    },
+                },
+                description: "DLQ jobs.",
+            },
+            403: { content: { "application/json": { schema: ErrorResponse } }, description: "Queue not allowed." },
+        },
+    });
+    router.openapi(applyRouteSecurity(getDlqRoute), async (c) => {
+        const { queue: queueName } = c.req.valid("param");
+        if (!isQueueAllowed(queueName)) {
+            return c.json({ error: "Queue not allowed" }, 403);
+        }
+        const { start: startStr, end: endStr } = c.req.valid("query");
+        const start = startStr ? parseInt(startStr) : 0;
+        const end = endStr ? parseInt(endStr) : 19;
+        const dlqQueue = createQueue(`${queueName}-dlq`);
+        const [jobs, total] = await Promise.all([
+            dlqQueue.getWaiting(start, end),
+            dlqQueue.getWaitingCount(),
+        ]);
+        const result = await Promise.all(jobs.map(jobToResponse));
+        return c.json({ jobs: result, total }, 200);
+    });
+    return router;
+};

package/dist/routes/mfa.d.ts

@@ -0,0 +1,5 @@
+import type { AuthRateLimitConfig } from "../app";
+export interface MfaRouterOptions {
+    rateLimit?: AuthRateLimitConfig;
+}
+export declare const createMfaRouter: ({ rateLimit }?: MfaRouterOptions) => import("@hono/zod-openapi").OpenAPIHono<import("../lib/context").AppEnv, {}, "/">;