@lastshotlabs/bunshot 0.0.10 → 0.0.16

package/dist/routes/mfa.js

@@ -0,0 +1,409 @@
+import { createRoute, withSecurity } from "../lib/createRoute";
+import { z } from "zod";
+import { setCookie } from "hono/cookie";
+import { createRouter } from "../lib/context";
+import { userAuth } from "../middleware/userAuth";
+import * as MfaService from "../services/mfa";
+import * as AuthService from "../services/auth";
+import { consumeMfaChallenge, replaceMfaChallengeOtp } from "../lib/mfaChallenge";
+import { COOKIE_TOKEN, COOKIE_REFRESH_TOKEN } from "../lib/constants";
+import { getRefreshTokenConfig, getAccessTokenExpiry, getRefreshTokenExpiry, getMfaEmailOtpConfig } from "../lib/appConfig";
+import { getAuthAdapter } from "../lib/authAdapter";
+const isProd = process.env.NODE_ENV === "production";
+const cookieOptions = (maxAge) => ({
+    httpOnly: true,
+    secure: isProd,
+    sameSite: "Lax",
+    path: "/",
+    maxAge: maxAge ?? 60 * 60 * 24 * 7,
+});
+const tags = ["MFA"];
+const ErrorResponse = z.object({ error: z.string() }).openapi("MfaErrorResponse");
+export const createMfaRouter = () => {
+    const router = createRouter();
+    // All MFA setup/management routes require auth
+    router.use("/auth/mfa/setup", userAuth);
+    router.use("/auth/mfa/verify-setup", userAuth);
+    router.use("/auth/mfa", userAuth);
+    router.use("/auth/mfa/recovery-codes", userAuth);
+    router.use("/auth/mfa/email-otp/enable", userAuth);
+    router.use("/auth/mfa/email-otp/verify-setup", userAuth);
+    router.use("/auth/mfa/email-otp", userAuth);
+    router.use("/auth/mfa/methods", userAuth);
+    // ─── Setup ────────────────────────────────────────────────────────────────
+    router.openapi(withSecurity(createRoute({
+        method: "post",
+        path: "/auth/mfa/setup",
+        summary: "Initiate MFA setup",
+        description: "Generates a TOTP secret and returns the otpauth URI for QR code scanning. The user must confirm setup by verifying a code via POST /auth/mfa/verify-setup.",
+        tags,
+        responses: {
+            200: {
+                content: {
+                    "application/json": {
+                        schema: z.object({
+                            secret: z.string().describe("Base32-encoded TOTP secret."),
+                            uri: z.string().describe("otpauth:// URI for QR code generation."),
+                        }),
+                    },
+                },
+                description: "TOTP secret generated. Scan the QR code with an authenticator app.",
+            },
+            401: { content: { "application/json": { schema: ErrorResponse } }, description: "No valid session." },
+            501: { content: { "application/json": { schema: ErrorResponse } }, description: "Auth adapter does not support MFA." },
+        },
+    }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
+        const userId = c.get("authUserId");
+        const result = await MfaService.setupMfa(userId);
+        return c.json(result, 200);
+    });
+    // ─── Verify Setup ─────────────────────────────────────────────────────────
+    router.openapi(withSecurity(createRoute({
+        method: "post",
+        path: "/auth/mfa/verify-setup",
+        summary: "Confirm MFA setup",
+        description: "Verifies a TOTP code from the authenticator app and enables MFA. Returns one-time recovery codes that should be stored securely. If email OTP was previously enabled, recovery codes are regenerated.",
+        tags,
+        request: {
+            body: {
+                content: {
+                    "application/json": {
+                        schema: z.object({
+                            code: z.string().length(6).describe("6-digit TOTP code from the authenticator app."),
+                        }),
+                    },
+                },
+            },
+        },
+        responses: {
+            200: {
+                content: {
+                    "application/json": {
+                        schema: z.object({
+                            message: z.string(),
+                            recoveryCodes: z.array(z.string()).describe("One-time recovery codes. Store these securely — they cannot be shown again."),
+                        }),
+                    },
+                },
+                description: "MFA enabled successfully.",
+            },
+            400: { content: { "application/json": { schema: ErrorResponse } }, description: "MFA setup not initiated." },
+            401: { content: { "application/json": { schema: ErrorResponse } }, description: "Invalid TOTP code or no valid session." },
+            501: { content: { "application/json": { schema: ErrorResponse } }, description: "Auth adapter does not support MFA." },
+        },
+    }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
+        const userId = c.get("authUserId");
+        const { code } = c.req.valid("json");
+        const recoveryCodes = await MfaService.verifySetup(userId, code);
+        return c.json({ message: "MFA enabled", recoveryCodes }, 200);
+    });
+    // ─── Verify (complete login after password) ───────────────────────────────
+    const MfaLoginResponse = z.object({
+        token: z.string().describe("JWT session token."),
+        userId: z.string().describe("Unique user ID."),
+        refreshToken: z.string().optional().describe("Refresh token (when configured)."),
+    }).openapi("MfaLoginResponse");
+    router.openapi(createRoute({
+        method: "post",
+        path: "/auth/mfa/verify",
+        summary: "Complete MFA login",
+        description: "Completes login by verifying a TOTP code, email OTP code, or recovery code after password authentication. Requires the mfaToken returned from the login endpoint. Optionally specify 'method' to target a specific verification method.",
+        tags,
+        request: {
+            body: {
+                content: {
+                    "application/json": {
+                        schema: z.object({
+                            mfaToken: z.string().describe("MFA challenge token from the login response."),
+                            code: z.string().describe("6-digit TOTP/email OTP code or 8-character recovery code."),
+                            method: z.enum(["totp", "emailOtp"]).optional().describe("Specify which MFA method to verify. If omitted, methods are tried automatically."),
+                        }),
+                    },
+                },
+            },
+        },
+        responses: {
+            200: { content: { "application/json": { schema: MfaLoginResponse } }, description: "MFA verified. Session created." },
+            401: { content: { "application/json": { schema: ErrorResponse } }, description: "Invalid or expired MFA token, or invalid code." },
+        },
+    }), async (c) => {
+        const { mfaToken, code, method } = c.req.valid("json");
+        const challenge = await consumeMfaChallenge(mfaToken);
+        if (!challenge)
+            return c.json({ error: "Invalid or expired MFA token" }, 401);
+        const { userId, emailOtpHash } = challenge;
+        let valid = false;
+        if (method === "totp") {
+            // Only try TOTP
+            valid = await MfaService.verifyTotp(userId, code);
+        }
+        else if (method === "emailOtp") {
+            // Only try email OTP
+            if (emailOtpHash)
+                valid = MfaService.verifyEmailOtp(emailOtpHash, code);
+        }
+        else {
+            // Auto-detect: use emailOtpHash presence to pick order
+            if (emailOtpHash) {
+                // Email OTP first, then TOTP, then recovery
+                valid = MfaService.verifyEmailOtp(emailOtpHash, code);
+                if (!valid)
+                    valid = await MfaService.verifyTotp(userId, code);
+            }
+            else {
+                // TOTP first
+                valid = await MfaService.verifyTotp(userId, code);
+            }
+        }
+        // Always try recovery code as fallback
+        if (!valid) {
+            valid = await MfaService.verifyRecoveryCode(userId, code);
+        }
+        if (!valid)
+            return c.json({ error: "Invalid MFA code" }, 401);
+        // Create session — reuse the service helper for refresh token support
+        const result = await AuthService.createSessionForUser(userId, {
+            ipAddress: (c.req.header("x-forwarded-for")?.split(",")[0]?.trim()) ?? c.req.header("x-real-ip") ?? undefined,
+            userAgent: c.req.header("user-agent") ?? undefined,
+        });
+        const rtConfig = getRefreshTokenConfig();
+        setCookie(c, COOKIE_TOKEN, result.token, cookieOptions(rtConfig ? getAccessTokenExpiry() : undefined));
+        if (result.refreshToken) {
+            setCookie(c, COOKIE_REFRESH_TOKEN, result.refreshToken, cookieOptions(getRefreshTokenExpiry()));
+        }
+        return c.json({ token: result.token, userId, refreshToken: result.refreshToken }, 200);
+    });
+    // ─── Disable MFA ──────────────────────────────────────────────────────────
+    router.openapi(withSecurity(createRoute({
+        method: "delete",
+        path: "/auth/mfa",
+        summary: "Disable MFA",
+        description: "Disables MFA for the authenticated user. Requires a valid TOTP code to confirm.",
+        tags,
+        request: {
+            body: {
+                content: {
+                    "application/json": {
+                        schema: z.object({
+                            code: z.string().length(6).describe("6-digit TOTP code to confirm disabling MFA."),
+                        }),
+                    },
+                },
+            },
+        },
+        responses: {
+            200: { content: { "application/json": { schema: z.object({ message: z.string() }) } }, description: "MFA disabled." },
+            401: { content: { "application/json": { schema: ErrorResponse } }, description: "Invalid TOTP code or no valid session." },
+            501: { content: { "application/json": { schema: ErrorResponse } }, description: "Auth adapter does not support MFA." },
+        },
+    }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
+        const userId = c.get("authUserId");
+        const { code } = c.req.valid("json");
+        await MfaService.disableMfa(userId, code);
+        return c.json({ message: "MFA disabled" }, 200);
+    });
+    // ─── Regenerate Recovery Codes ────────────────────────────────────────────
+    router.openapi(withSecurity(createRoute({
+        method: "post",
+        path: "/auth/mfa/recovery-codes",
+        summary: "Regenerate recovery codes",
+        description: "Generates new recovery codes, invalidating all previous ones. Requires a valid TOTP code to confirm.",
+        tags,
+        request: {
+            body: {
+                content: {
+                    "application/json": {
+                        schema: z.object({
+                            code: z.string().length(6).describe("6-digit TOTP code to confirm regeneration."),
+                        }),
+                    },
+                },
+            },
+        },
+        responses: {
+            200: {
+                content: {
+                    "application/json": {
+                        schema: z.object({
+                            recoveryCodes: z.array(z.string()).describe("New one-time recovery codes."),
+                        }),
+                    },
+                },
+                description: "New recovery codes generated.",
+            },
+            401: { content: { "application/json": { schema: ErrorResponse } }, description: "Invalid TOTP code or no valid session." },
+            501: { content: { "application/json": { schema: ErrorResponse } }, description: "Auth adapter does not support MFA." },
+        },
+    }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
+        const userId = c.get("authUserId");
+        const { code } = c.req.valid("json");
+        const recoveryCodes = await MfaService.regenerateRecoveryCodes(userId, code);
+        return c.json({ recoveryCodes }, 200);
+    });
+    // ─── Email OTP: Enable (initiate) ────────────────────────────────────────
+    router.openapi(withSecurity(createRoute({
+        method: "post",
+        path: "/auth/mfa/email-otp/enable",
+        summary: "Initiate email OTP setup",
+        description: "Sends a verification code to the user's email to confirm email OTP setup. Confirm via POST /auth/mfa/email-otp/verify-setup.",
+        tags,
+        responses: {
+            200: {
+                content: {
+                    "application/json": {
+                        schema: z.object({
+                            message: z.string(),
+                            setupToken: z.string().describe("Setup challenge token. Pass to POST /auth/mfa/email-otp/verify-setup with the code."),
+                        }),
+                    },
+                },
+                description: "Verification code sent to email.",
+            },
+            400: { content: { "application/json": { schema: ErrorResponse } }, description: "No email address on account." },
+            401: { content: { "application/json": { schema: ErrorResponse } }, description: "No valid session." },
+            501: { content: { "application/json": { schema: ErrorResponse } }, description: "Email OTP is not configured." },
+        },
+    }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
+        const userId = c.get("authUserId");
+        const setupToken = await MfaService.initiateEmailOtp(userId);
+        return c.json({ message: "Verification code sent", setupToken }, 200);
+    });
+    // ─── Email OTP: Verify Setup ─────────────────────────────────────────────
+    router.openapi(withSecurity(createRoute({
+        method: "post",
+        path: "/auth/mfa/email-otp/verify-setup",
+        summary: "Confirm email OTP setup",
+        description: "Verifies the code sent during email OTP initiation and enables email OTP as an MFA method. Returns recovery codes (new or regenerated if another MFA method was already active).",
+        tags,
+        request: {
+            body: {
+                content: {
+                    "application/json": {
+                        schema: z.object({
+                            setupToken: z.string().describe("Setup challenge token from POST /auth/mfa/email-otp/enable."),
+                            code: z.string().describe("Verification code sent to email."),
+                        }),
+                    },
+                },
+            },
+        },
+        responses: {
+            200: {
+                content: {
+                    "application/json": {
+                        schema: z.object({
+                            message: z.string(),
+                            recoveryCodes: z.array(z.string()).optional().describe("Recovery codes (always returned when email OTP is enabled)."),
+                        }),
+                    },
+                },
+                description: "Email OTP enabled.",
+            },
+            401: { content: { "application/json": { schema: ErrorResponse } }, description: "Invalid setup token or code." },
+            501: { content: { "application/json": { schema: ErrorResponse } }, description: "Auth adapter does not support MFA." },
+        },
+    }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
+        const userId = c.get("authUserId");
+        const { setupToken, code } = c.req.valid("json");
+        const recoveryCodes = await MfaService.confirmEmailOtp(userId, setupToken, code);
+        return c.json({ message: "Email OTP enabled", recoveryCodes: recoveryCodes ?? undefined }, 200);
+    });
+    // ─── Email OTP: Disable ──────────────────────────────────────────────────
+    router.openapi(withSecurity(createRoute({
+        method: "delete",
+        path: "/auth/mfa/email-otp",
+        summary: "Disable email OTP",
+        description: "Disables email OTP for the authenticated user. Requires a TOTP code if TOTP is also enabled, or a password if email OTP is the only MFA method.",
+        tags,
+        request: {
+            body: {
+                content: {
+                    "application/json": {
+                        schema: z.object({
+                            code: z.string().optional().describe("6-digit TOTP code (required when TOTP is also enabled)."),
+                            password: z.string().optional().describe("Account password (required when email OTP is the only MFA method)."),
+                        }),
+                    },
+                },
+            },
+        },
+        responses: {
+            200: { content: { "application/json": { schema: z.object({ message: z.string() }) } }, description: "Email OTP disabled." },
+            400: { content: { "application/json": { schema: ErrorResponse } }, description: "Missing required verification." },
+            401: { content: { "application/json": { schema: ErrorResponse } }, description: "Invalid code/password or no valid session." },
+            501: { content: { "application/json": { schema: ErrorResponse } }, description: "Auth adapter does not support MFA." },
+        },
+    }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
+        const userId = c.get("authUserId");
+        const { code, password } = c.req.valid("json");
+        await MfaService.disableEmailOtp(userId, { code, password });
+        return c.json({ message: "Email OTP disabled" }, 200);
+    });
+    // ─── Resend Email OTP ────────────────────────────────────────────────────
+    router.openapi(createRoute({
+        method: "post",
+        path: "/auth/mfa/resend",
+        summary: "Resend email OTP code",
+        description: "Generates and sends a new email OTP code for the given MFA challenge. Rate-limited to 3 resends per challenge. Does not extend the challenge beyond 3x the original TTL.",
+        tags,
+        request: {
+            body: {
+                content: {
+                    "application/json": {
+                        schema: z.object({
+                            mfaToken: z.string().describe("MFA challenge token from the login response."),
+                        }),
+                    },
+                },
+            },
+        },
+        responses: {
+            200: { content: { "application/json": { schema: z.object({ message: z.string() }) } }, description: "Code sent." },
+            400: { content: { "application/json": { schema: ErrorResponse } }, description: "Email OTP not configured." },
+            401: { content: { "application/json": { schema: ErrorResponse } }, description: "Invalid or expired MFA token." },
+            429: { content: { "application/json": { schema: ErrorResponse } }, description: "Maximum resends reached." },
+        },
+    }), async (c) => {
+        const { mfaToken } = c.req.valid("json");
+        const emailOtpConfig = getMfaEmailOtpConfig();
+        if (!emailOtpConfig)
+            return c.json({ error: "Email OTP is not configured" }, 400);
+        const { code, hash } = MfaService.generateEmailOtpCode();
+        const result = await replaceMfaChallengeOtp(mfaToken, hash);
+        if (!result)
+            return c.json({ error: "Invalid/expired MFA token or maximum resends reached" }, 401);
+        // Get user email and send
+        const adapter = getAuthAdapter();
+        const user = adapter.getUser ? await adapter.getUser(result.userId) : null;
+        if (user?.email) {
+            await emailOtpConfig.onSend(user.email, code);
+        }
+        return c.json({ message: "Code sent" }, 200);
+    });
+    // ─── Get MFA Methods ────────────────────────────────────────────────────
+    router.openapi(withSecurity(createRoute({
+        method: "get",
+        path: "/auth/mfa/methods",
+        summary: "Get enabled MFA methods",
+        description: "Returns the MFA methods currently enabled for the authenticated user.",
+        tags,
+        responses: {
+            200: {
+                content: {
+                    "application/json": {
+                        schema: z.object({
+                            methods: z.array(z.string()).describe("Enabled MFA methods (e.g., 'totp', 'emailOtp')."),
+                        }),
+                    },
+                },
+                description: "Enabled MFA methods.",
+            },
+            401: { content: { "application/json": { schema: ErrorResponse } }, description: "No valid session." },
+        },
+    }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
+        const userId = c.get("authUserId");
+        const methods = await MfaService.getMfaMethods(userId);
+        return c.json({ methods }, 200);
+    });
+    return router;
+};

package/dist/routes/oauth.js

@@ -1,22 +1,26 @@
+import { createRoute, withSecurity } from "../lib/createRoute";
 import { createRouter } from "../lib/context";
 import { setCookie } from "hono/cookie";
 import { decodeIdToken } from "arctic";
+import { z } from "zod";
 import { getGoogle, getApple, storeOAuthState, consumeOAuthState, generateState, generateCodeVerifier, } from "../lib/oauth";
 import { getAuthAdapter } from "../lib/authAdapter";
 import { HttpError } from "../lib/HttpError";
 import { signToken } from "../lib/jwt";
-import { createSession, getActiveSessionCount, evictOldestSession } from "../lib/session";
-import { COOKIE_TOKEN } from "../lib/constants";
+import { createSession, getActiveSessionCount, evictOldestSession, setRefreshToken } from "../lib/session";
+import { COOKIE_TOKEN, COOKIE_REFRESH_TOKEN } from "../lib/constants";
 import { userAuth } from "../middleware/userAuth";
-import { getDefaultRole, getMaxSessions } from "../lib/appConfig";
+import { getDefaultRole, getMaxSessions, getRefreshTokenConfig, getAccessTokenExpiry, getRefreshTokenExpiry } from "../lib/appConfig";
 const isProd = process.env.NODE_ENV === "production";
-const cookieOptions = {
+const cookieOptions = (maxAge) => ({
     httpOnly: true,
     secure: isProd,
     sameSite: "Lax",
     path: "/",
-    maxAge: 60 * 60 * 24 * 7,
-};
+    maxAge: maxAge ?? 60 * 60 * 24 * 7,
+});
+const tags = ["OAuth"];
+const OAuthErrorResponse = z.object({ error: z.string().describe("Human-readable error message.") }).openapi("OAuthErrorResponse");
 const finishOAuth = async (c, provider, providerId, profile, postLoginRedirect) => {
     const adapter = getAuthAdapter();
     if (!adapter.findOrCreateByProvider) {
@@ -37,7 +41,9 @@ const finishOAuth = async (c, provider, providerId, profile, postLoginRedirect)
             await adapter.setRoles(user.id, [role]);
     }
     const sessionId = crypto.randomUUID();
-    const token = await signToken(user.id, sessionId);
+    const rtConfig = getRefreshTokenConfig();
+    const expirySeconds = rtConfig ? getAccessTokenExpiry() : undefined;
+    const token = await signToken(user.id, sessionId, expirySeconds);
     const xff = c.req.header("x-forwarded-for");
     const metadata = {
         ipAddress: (xff ? xff.split(",")[0]?.trim() : undefined) ?? c.req.header("x-real-ip") ?? undefined,
@@ -47,7 +53,13 @@ const finishOAuth = async (c, provider, providerId, profile, postLoginRedirect)
         await evictOldestSession(user.id);
     }
     await createSession(user.id, token, sessionId, metadata);
-    setCookie(c, COOKIE_TOKEN, token, cookieOptions);
+    setCookie(c, COOKIE_TOKEN, token, cookieOptions(rtConfig ? getAccessTokenExpiry() : undefined));
+    let refreshTokenValue;
+    if (rtConfig) {
+        refreshTokenValue = crypto.randomUUID();
+        await setRefreshToken(sessionId, refreshTokenValue);
+        setCookie(c, COOKIE_REFRESH_TOKEN, refreshTokenValue, cookieOptions(getRefreshTokenExpiry()));
+    }
     // Append token to redirect so non-browser clients (mobile deep links) can extract it.
     // Browser apps can safely ignore the query param.
     try {
@@ -68,15 +80,41 @@ export const createOAuthRouter = (providers, postLoginRedirect) => {
     const router = createRouter();
     // ─── Google ───────────────────────────────────────────────────────────────
     if (providers.includes("google")) {
-        router.get("/auth/google", async (c) => {
+        router.openapi(createRoute({
+            method: "get",
+            path: "/auth/google",
+            summary: "Initiate Google OAuth",
+            description: "Redirects the user to Google's consent screen to begin the OAuth login flow. After the user authorizes, Google redirects back to `/auth/google/callback`.",
+            tags,
+            responses: {
+                302: { description: "Redirect to Google's OAuth consent screen." },
+                500: { content: { "application/json": { schema: OAuthErrorResponse } }, description: "OAuth provider not configured." },
+            },
+        }), async (c) => {
             const state = generateState();
             const codeVerifier = generateCodeVerifier();
             await storeOAuthState(state, codeVerifier);
             const url = getGoogle().createAuthorizationURL(state, codeVerifier, ["openid", "profile", "email"]);
             return c.redirect(url.toString());
         });
-        router.get("/auth/google/callback", async (c) => {
-            const { code, state } = c.req.query();
+        router.openapi(createRoute({
+            method: "get",
+            path: "/auth/google/callback",
+            summary: "Google OAuth callback",
+            description: "Handles the redirect from Google after user authorization. Validates the OAuth state and code, then creates or finds the user account. Sets a session cookie and redirects to the configured post-login URL.",
+            tags,
+            request: {
+                query: z.object({
+                    code: z.string().describe("Authorization code from Google."),
+                    state: z.string().describe("OAuth state parameter for CSRF protection."),
+                }),
+            },
+            responses: {
+                302: { description: "Redirect to the post-login URL with session token." },
+                400: { content: { "application/json": { schema: OAuthErrorResponse } }, description: "Invalid callback parameters or expired state." },
+            },
+        }), async (c) => {
+            const { code, state } = c.req.valid("query");
             if (!code || !state)
                 return c.json({ error: "Invalid callback" }, 400);
             const stored = await consumeOAuthState(state);
@@ -96,14 +134,36 @@ export const createOAuthRouter = (providers, postLoginRedirect) => {
             }
             return finishOAuth(c, "google", info.sub, { email: info.email, name: info.name, avatarUrl: info.picture }, postLoginRedirect);
         });
-        router.get("/auth/google/link", userAuth, async (c) => {
+        router.use("/auth/google/link", userAuth);
+        router.openapi(withSecurity(createRoute({
+            method: "get",
+            path: "/auth/google/link",
+            summary: "Link Google account",
+            description: "Initiates an OAuth flow to link a Google account to the authenticated user. Requires a valid session. Redirects to Google's consent screen.",
+            tags,
+            responses: {
+                302: { description: "Redirect to Google's OAuth consent screen." },
+                401: { content: { "application/json": { schema: OAuthErrorResponse } }, description: "No valid session." },
+            },
+        }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
             const state = generateState();
             const codeVerifier = generateCodeVerifier();
             await storeOAuthState(state, codeVerifier, c.get("authUserId"));
             const url = getGoogle().createAuthorizationURL(state, codeVerifier, ["openid", "profile", "email"]);
             return c.redirect(url.toString());
         });
-        router.delete("/auth/google/link", userAuth, async (c) => {
+        router.openapi(withSecurity(createRoute({
+            method: "delete",
+            path: "/auth/google/link",
+            summary: "Unlink Google account",
+            description: "Removes the linked Google OAuth account from the authenticated user. Requires a valid session.",
+            tags,
+            responses: {
+                204: { description: "Google account unlinked successfully." },
+                401: { content: { "application/json": { schema: OAuthErrorResponse } }, description: "No valid session." },
+                500: { content: { "application/json": { schema: OAuthErrorResponse } }, description: "Auth adapter does not support unlinkProvider." },
+            },
+        }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
             const adapter = getAuthAdapter();
             if (!adapter.unlinkProvider) {
                 return c.json({ error: "Auth adapter does not support unlinkProvider" }, 500);
@@ -114,14 +174,34 @@ export const createOAuthRouter = (providers, postLoginRedirect) => {
     }
     // ─── Apple ────────────────────────────────────────────────────────────────
     if (providers.includes("apple")) {
-        router.get("/auth/apple", async (c) => {
+        router.openapi(createRoute({
+            method: "get",
+            path: "/auth/apple",
+            summary: "Initiate Apple OAuth",
+            description: "Redirects the user to Apple's sign-in page to begin the OAuth login flow. After the user authorizes, Apple posts back to `/auth/apple/callback`.",
+            tags,
+            responses: {
+                302: { description: "Redirect to Apple's OAuth sign-in page." },
+                500: { content: { "application/json": { schema: OAuthErrorResponse } }, description: "OAuth provider not configured." },
+            },
+        }), async (c) => {
             const state = generateState();
             await storeOAuthState(state);
             const url = getApple().createAuthorizationURL(state, ["name", "email"]);
             return c.redirect(url.toString());
         });
         // Apple sends a POST with form data to the callback URL
-        router.post("/auth/apple/callback", async (c) => {
+        router.openapi(createRoute({
+            method: "post",
+            path: "/auth/apple/callback",
+            summary: "Apple OAuth callback",
+            description: "Handles the POST redirect from Apple after user authorization. Apple sends form-encoded data containing the authorization code and state. Validates the OAuth state, exchanges the code for tokens, then creates or finds the user account. Sets a session cookie and redirects to the configured post-login URL.",
+            tags,
+            responses: {
+                302: { description: "Redirect to the post-login URL with session token." },
+                400: { content: { "application/json": { schema: OAuthErrorResponse } }, description: "Invalid callback parameters or expired state." },
+            },
+        }), async (c) => {
             const form = await c.req.formData();
             const code = form.get("code");
             const state = form.get("state");
@@ -148,7 +228,18 @@ export const createOAuthRouter = (providers, postLoginRedirect) => {
                 : undefined;
             return finishOAuth(c, "apple", claims.sub, { email: claims.email, name }, postLoginRedirect);
         });
-        router.get("/auth/apple/link", userAuth, async (c) => {
+        router.use("/auth/apple/link", userAuth);
+        router.openapi(withSecurity(createRoute({
+            method: "get",
+            path: "/auth/apple/link",
+            summary: "Link Apple account",
+            description: "Initiates an OAuth flow to link an Apple account to the authenticated user. Requires a valid session. Redirects to Apple's sign-in page.",
+            tags,
+            responses: {
+                302: { description: "Redirect to Apple's OAuth sign-in page." },
+                401: { content: { "application/json": { schema: OAuthErrorResponse } }, description: "No valid session." },
+            },
+        }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
             const state = generateState();
             await storeOAuthState(state, undefined, c.get("authUserId"));
             const url = getApple().createAuthorizationURL(state, ["name", "email"]);

package/dist/server.js

@@ -46,6 +46,15 @@ export const createServer = async (config) => {
         for await (const file of glob.scan({ cwd: workersDir })) {
             await import(`${workersDir}/${file}`);
         }
+        // Clean up ghost cron schedulers after all workers are loaded
+        try {
+            const { getRegisteredCronNames, cleanupStaleSchedulers } = await import("./lib/queue");
+            const activeNames = [...getRegisteredCronNames()];
+            if (activeNames.length > 0) {
+                await cleanupStaleSchedulers(activeNames);
+            }
+        }
+        catch { /* bullmq not installed or no cron workers */ }
     }
     log(`[server] running at http://localhost:${server.port}`);
     log(`[server] API docs at http://localhost:${server.port}/docs`);

package/dist/services/auth.d.ts

@@ -1,7 +1,26 @@
 import type { SessionMetadata } from "../lib/session";
-export declare const register: (identifier: string, password: string, metadata?: SessionMetadata) => Promise<string>;
-export declare const login: (identifier: string, password: string, metadata?: SessionMetadata) => Promise<{
+export interface AuthResult {
     token: string;
+    userId: string;
+    email?: string;
     emailVerified?: boolean;
+    googleLinked?: boolean;
+    refreshToken?: string;
+    mfaRequired?: boolean;
+    mfaToken?: string;
+    mfaMethods?: string[];
+}
+/** Create a session for a user (used internally and by MFA verify). */
+export declare const createSessionForUser: (userId: string, metadata?: SessionMetadata) => Promise<{
+    token: string;
+    refreshToken?: string;
+}>;
+export declare const register: (identifier: string, password: string, metadata?: SessionMetadata) => Promise<AuthResult>;
+export declare const login: (identifier: string, password: string, metadata?: SessionMetadata) => Promise<AuthResult>;
+export declare const refresh: (refreshTokenValue: string) => Promise<{
+    token: string;
+    refreshToken: string;
+    userId: string;
 }>;
+export declare const deleteAccount: (userId: string, password?: string) => Promise<void>;
 export declare const logout: (token: string | null) => Promise<void>;