@lastshotlabs/bunshot 0.0.16 → 0.0.18

package/dist/routes/mfa.js

@@ -7,8 +7,11 @@ 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 { getRefreshTokenConfig, getAccessTokenExpiry, getRefreshTokenExpiry, getMfaEmailOtpConfig, getMfaWebAuthnConfig, getCsrfEnabled } from "../lib/appConfig";
+import { refreshCsrfToken } from "../middleware/csrf";
 import { getAuthAdapter } from "../lib/authAdapter";
+import { trackAttempt } from "../lib/authRateLimit";
+import { getClientIp } from "../lib/clientIp";
 const isProd = process.env.NODE_ENV === "production";
 const cookieOptions = (maxAge) => ({
     httpOnly: true,
@@ -19,8 +22,11 @@ const cookieOptions = (maxAge) => ({
 });
 const tags = ["MFA"];
 const ErrorResponse = z.object({ error: z.string() }).openapi("MfaErrorResponse");
-export const createMfaRouter = () => {
+export const createMfaRouter = ({ rateLimit } = {}) => {
     const router = createRouter();
+    // Resolve MFA rate limits with defaults
+    const mfaVerifyOpts = { windowMs: rateLimit?.mfaVerify?.windowMs ?? 15 * 60 * 1000, max: rateLimit?.mfaVerify?.max ?? 10 };
+    const mfaResendOpts = { windowMs: rateLimit?.mfaResend?.windowMs ?? 60 * 1000, max: rateLimit?.mfaResend?.max ?? 5 };
     // All MFA setup/management routes require auth
     router.use("/auth/mfa/setup", userAuth);
     router.use("/auth/mfa/verify-setup", userAuth);
@@ -107,7 +113,7 @@ export const createMfaRouter = () => {
         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.",
+        description: "Completes login by verifying a TOTP code, email OTP code, recovery code, or WebAuthn assertion after password authentication. Requires the mfaToken returned from the login endpoint. Optionally specify 'method' to target a specific verification method.",
         tags,
         request: {
             body: {
@@ -115,8 +121,9 @@ export const createMfaRouter = () => {
                     "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."),
+                            code: z.string().optional().describe("6-digit TOTP/email OTP code or 8-character recovery code. Required unless using WebAuthn."),
+                            method: z.enum(["totp", "emailOtp", "webauthn"]).optional().describe("Specify which MFA method to verify. If omitted, methods are tried automatically."),
+                            webauthnResponse: z.record(z.string(), z.unknown()).optional().describe("WebAuthn authentication response from navigator.credentials.get(). Pass the entire response object."),
                         }),
                     },
                 },
@@ -125,24 +132,39 @@ export const createMfaRouter = () => {
         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." },
+            429: { content: { "application/json": { schema: ErrorResponse } }, description: "Too many MFA verification attempts. Try again later." },
         },
     }), async (c) => {
-        const { mfaToken, code, method } = c.req.valid("json");
+        const ip = getClientIp(c);
+        if (await trackAttempt(`mfa-verify:${ip}`, mfaVerifyOpts)) {
+            return c.json({ error: "Too many MFA verification attempts. Try again later." }, 429);
+        }
+        const { mfaToken, code, method, webauthnResponse } = c.req.valid("json");
+        if (!code && !webauthnResponse) {
+            return c.json({ error: "Either 'code' or 'webauthnResponse' is required" }, 401);
+        }
         const challenge = await consumeMfaChallenge(mfaToken);
         if (!challenge)
             return c.json({ error: "Invalid or expired MFA token" }, 401);
-        const { userId, emailOtpHash } = challenge;
+        const { userId, emailOtpHash, webauthnChallenge } = challenge;
         let valid = false;
-        if (method === "totp") {
+        if (method === "webauthn" || (!method && webauthnResponse)) {
+            // WebAuthn verification
+            if (webauthnResponse && webauthnChallenge) {
+                valid = await MfaService.verifyWebAuthn(userId, webauthnResponse, webauthnChallenge);
+            }
+        }
+        else if (method === "totp") {
             // Only try TOTP
-            valid = await MfaService.verifyTotp(userId, code);
+            if (code)
+                valid = await MfaService.verifyTotp(userId, code);
         }
         else if (method === "emailOtp") {
             // Only try email OTP
-            if (emailOtpHash)
+            if (code && emailOtpHash)
                 valid = MfaService.verifyEmailOtp(emailOtpHash, code);
         }
-        else {
+        else if (code) {
             // Auto-detect: use emailOtpHash presence to pick order
             if (emailOtpHash) {
                 // Email OTP first, then TOTP, then recovery
@@ -155,15 +177,15 @@ export const createMfaRouter = () => {
                 valid = await MfaService.verifyTotp(userId, code);
             }
         }
-        // Always try recovery code as fallback
-        if (!valid) {
+        // Always try recovery code as fallback (code-based only)
+        if (!valid && code) {
             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,
+            ipAddress: getClientIp(c),
             userAgent: c.req.header("user-agent") ?? undefined,
         });
         const rtConfig = getRefreshTokenConfig();
@@ -171,6 +193,8 @@ export const createMfaRouter = () => {
         if (result.refreshToken) {
             setCookie(c, COOKIE_REFRESH_TOKEN, result.refreshToken, cookieOptions(getRefreshTokenExpiry()));
         }
+        if (getCsrfEnabled())
+            refreshCsrfToken(c);
         return c.json({ token: result.token, userId, refreshToken: result.refreshToken }, 200);
     });
     // ─── Disable MFA ──────────────────────────────────────────────────────────
@@ -364,6 +388,10 @@ export const createMfaRouter = () => {
             429: { content: { "application/json": { schema: ErrorResponse } }, description: "Maximum resends reached." },
         },
     }), async (c) => {
+        const ip = getClientIp(c);
+        if (await trackAttempt(`mfa-resend:${ip}`, mfaResendOpts)) {
+            return c.json({ error: "Too many resend attempts. Try again later." }, 429);
+        }
         const { mfaToken } = c.req.valid("json");
         const emailOtpConfig = getMfaEmailOtpConfig();
         if (!emailOtpConfig)
@@ -405,5 +433,184 @@ export const createMfaRouter = () => {
         const methods = await MfaService.getMfaMethods(userId);
         return c.json({ methods }, 200);
     });
+    // ─── WebAuthn / Security Keys ─────────────────────────────────────────────
+    if (getMfaWebAuthnConfig()) {
+        // Eager dependency check — fail fast at server start
+        MfaService.assertWebAuthnDependency().catch((err) => { throw err; });
+        router.use("/auth/mfa/webauthn/*", userAuth);
+        // Register options
+        router.openapi(withSecurity(createRoute({
+            method: "post",
+            path: "/auth/mfa/webauthn/register-options",
+            summary: "Generate WebAuthn registration options",
+            description: "Generates registration options for the client to pass to navigator.credentials.create(). Returns a registrationToken to confirm registration.",
+            tags,
+            responses: {
+                200: {
+                    content: {
+                        "application/json": {
+                            schema: z.object({
+                                options: z.record(z.string(), z.unknown()).describe("PublicKeyCredentialCreationOptions — pass directly to navigator.credentials.create()."),
+                                registrationToken: z.string().describe("Token to pass back when completing registration."),
+                            }),
+                        },
+                    },
+                    description: "Registration options generated.",
+                },
+                401: { content: { "application/json": { schema: ErrorResponse } }, description: "No valid session." },
+                501: { content: { "application/json": { schema: ErrorResponse } }, description: "WebAuthn not configured or adapter does not support it." },
+            },
+        }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
+            const userId = c.get("authUserId");
+            const result = await MfaService.initiateWebAuthnRegistration(userId);
+            return c.json(result, 200);
+        });
+        // Complete registration
+        router.openapi(withSecurity(createRoute({
+            method: "post",
+            path: "/auth/mfa/webauthn/register",
+            summary: "Complete WebAuthn registration",
+            description: "Verifies the attestation response from navigator.credentials.create() and stores the credential. Returns recovery codes.",
+            tags,
+            request: {
+                body: {
+                    content: {
+                        "application/json": {
+                            schema: z.object({
+                                registrationToken: z.string().describe("Token from POST /auth/mfa/webauthn/register-options."),
+                                attestationResponse: z.record(z.string(), z.unknown()).describe("Full response from navigator.credentials.create()."),
+                                name: z.string().optional().describe("User-friendly name for the key (e.g. 'YubiKey 5')."),
+                            }),
+                        },
+                    },
+                },
+            },
+            responses: {
+                200: {
+                    content: {
+                        "application/json": {
+                            schema: z.object({
+                                message: z.string(),
+                                credentialId: z.string(),
+                                recoveryCodes: z.array(z.string()).nullable().describe("Recovery codes (always returned when WebAuthn is enabled)."),
+                            }),
+                        },
+                    },
+                    description: "Security key registered.",
+                },
+                401: { content: { "application/json": { schema: ErrorResponse } }, description: "Invalid registration token or verification failed." },
+                409: { content: { "application/json": { schema: ErrorResponse } }, description: "Security key already registered to another account." },
+                501: { content: { "application/json": { schema: ErrorResponse } }, description: "WebAuthn not configured or adapter does not support it." },
+            },
+        }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
+            const userId = c.get("authUserId");
+            const { registrationToken, attestationResponse, name } = c.req.valid("json");
+            const result = await MfaService.completeWebAuthnRegistration(userId, registrationToken, attestationResponse, name);
+            return c.json({ message: "Security key registered", ...result }, 200);
+        });
+        // List credentials
+        router.openapi(withSecurity(createRoute({
+            method: "get",
+            path: "/auth/mfa/webauthn/credentials",
+            summary: "List WebAuthn credentials",
+            description: "Returns the security keys registered for the authenticated user. Does not include private key data.",
+            tags,
+            responses: {
+                200: {
+                    content: {
+                        "application/json": {
+                            schema: z.object({
+                                credentials: z.array(z.object({
+                                    credentialId: z.string(),
+                                    name: z.string().optional(),
+                                    createdAt: z.number(),
+                                    transports: z.array(z.string()).optional(),
+                                })),
+                            }),
+                        },
+                    },
+                    description: "List of registered security keys.",
+                },
+                401: { content: { "application/json": { schema: ErrorResponse } }, description: "No valid session." },
+            },
+        }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
+            const userId = c.get("authUserId");
+            const adapter = getAuthAdapter();
+            const creds = adapter.getWebAuthnCredentials ? await adapter.getWebAuthnCredentials(userId) : [];
+            return c.json({
+                credentials: creds.map((cr) => ({
+                    credentialId: cr.credentialId,
+                    name: cr.name,
+                    createdAt: cr.createdAt,
+                    transports: cr.transports,
+                })),
+            }, 200);
+        });
+        // Remove a single credential
+        router.openapi(withSecurity(createRoute({
+            method: "delete",
+            path: "/auth/mfa/webauthn/credentials/{credentialId}",
+            summary: "Remove a WebAuthn credential",
+            description: "Removes a single security key. Identity verification is only required when removing the last MFA credential.",
+            tags,
+            request: {
+                params: z.object({ credentialId: z.string() }),
+                body: {
+                    content: {
+                        "application/json": {
+                            schema: z.object({
+                                code: z.string().optional().describe("TOTP code (required when removing the last MFA credential, if TOTP is enabled)."),
+                                password: z.string().optional().describe("Password (required when removing the last MFA credential, if no TOTP)."),
+                            }),
+                        },
+                    },
+                },
+            },
+            responses: {
+                200: { content: { "application/json": { schema: z.object({ message: z.string() }) } }, description: "Credential removed." },
+                400: { content: { "application/json": { schema: ErrorResponse } }, description: "Missing required verification." },
+                401: { content: { "application/json": { schema: ErrorResponse } }, description: "Invalid code/password or no valid session." },
+                404: { content: { "application/json": { schema: ErrorResponse } }, description: "Credential not found." },
+                501: { content: { "application/json": { schema: ErrorResponse } }, description: "Adapter does not support WebAuthn." },
+            },
+        }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
+            const userId = c.get("authUserId");
+            const { credentialId } = c.req.valid("param");
+            const { code, password } = c.req.valid("json");
+            await MfaService.removeWebAuthnCredential(userId, credentialId, { code, password });
+            return c.json({ message: "Credential removed" }, 200);
+        });
+        // Disable WebAuthn entirely
+        router.openapi(withSecurity(createRoute({
+            method: "delete",
+            path: "/auth/mfa/webauthn",
+            summary: "Disable WebAuthn MFA",
+            description: "Removes all WebAuthn credentials and disables WebAuthn as an MFA method. Requires identity verification.",
+            tags,
+            request: {
+                body: {
+                    content: {
+                        "application/json": {
+                            schema: z.object({
+                                code: z.string().optional().describe("TOTP code (if TOTP is enabled)."),
+                                password: z.string().optional().describe("Password (if TOTP is not enabled)."),
+                            }),
+                        },
+                    },
+                },
+            },
+            responses: {
+                200: { content: { "application/json": { schema: z.object({ message: z.string() }) } }, description: "WebAuthn 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: "Adapter does not support WebAuthn." },
+            },
+        }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
+            const userId = c.get("authUserId");
+            const { code, password } = c.req.valid("json");
+            await MfaService.disableWebAuthn(userId, { code, password });
+            return c.json({ message: "WebAuthn disabled" }, 200);
+        });
+    }
     return router;
 };

package/dist/routes/oauth.js

@@ -3,14 +3,18 @@ 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 { getGoogle, getApple, getMicrosoft, getGitHub, 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, setRefreshToken } from "../lib/session";
+import { storeOAuthCode, consumeOAuthCode } from "../lib/oauthCode";
 import { COOKIE_TOKEN, COOKIE_REFRESH_TOKEN } from "../lib/constants";
 import { userAuth } from "../middleware/userAuth";
-import { getDefaultRole, getMaxSessions, getRefreshTokenConfig, getAccessTokenExpiry, getRefreshTokenExpiry } from "../lib/appConfig";
+import { getDefaultRole, getMaxSessions, getRefreshTokenConfig, getAccessTokenExpiry, getRefreshTokenExpiry, getCsrfEnabled } from "../lib/appConfig";
+import { refreshCsrfToken } from "../middleware/csrf";
+import { trackAttempt } from "../lib/authRateLimit";
+import { getClientIp } from "../lib/clientIp";
 const isProd = process.env.NODE_ENV === "production";
 const cookieOptions = (maxAge) => ({
     httpOnly: true,
@@ -44,27 +48,30 @@ const finishOAuth = async (c, provider, providerId, profile, postLoginRedirect)
     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,
+        ipAddress: getClientIp(c),
         userAgent: c.req.header("user-agent") ?? undefined,
     };
     while (await getActiveSessionCount(user.id) >= getMaxSessions()) {
         await evictOldestSession(user.id);
     }
     await createSession(user.id, token, sessionId, metadata);
-    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.
+    // Store a one-time authorization code instead of exposing the token in the redirect URL.
+    // The client exchanges this code via POST /auth/oauth/exchange to get the session token.
+    const code = await storeOAuthCode({
+        token,
+        userId: user.id,
+        email: profile.email,
+        refreshToken: refreshTokenValue,
+    });
     try {
         const url = new URL(postLoginRedirect);
-        url.searchParams.set("token", token);
+        url.searchParams.set("code", code);
         if (profile.email)
             url.searchParams.set("user", profile.email);
         return c.redirect(url.toString());
@@ -73,7 +80,7 @@ const finishOAuth = async (c, provider, providerId, profile, postLoginRedirect)
         // Relative path fallback
         const sep = postLoginRedirect.includes("?") ? "&" : "?";
         const userParam = profile.email ? `&user=${encodeURIComponent(profile.email)}` : "";
-        return c.redirect(`${postLoginRedirect}${sep}token=${token}${userParam}`);
+        return c.redirect(`${postLoginRedirect}${sep}code=${code}${userParam}`);
     }
 };
 export const createOAuthRouter = (providers, postLoginRedirect) => {
@@ -246,5 +253,262 @@ export const createOAuthRouter = (providers, postLoginRedirect) => {
             return c.redirect(url.toString());
         });
     }
+    // ─── Microsoft ──────────────────────────────────────────────────────────
+    if (providers.includes("microsoft")) {
+        router.openapi(createRoute({
+            method: "get",
+            path: "/auth/microsoft",
+            summary: "Initiate Microsoft OAuth",
+            description: "Redirects the user to Microsoft's sign-in page to begin the OAuth login flow. After the user authorizes, Microsoft redirects back to `/auth/microsoft/callback`.",
+            tags,
+            responses: {
+                302: { description: "Redirect to Microsoft's OAuth sign-in page." },
+                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 = getMicrosoft().createAuthorizationURL(state, codeVerifier, ["openid", "profile", "email"]);
+            return c.redirect(url.toString());
+        });
+        router.openapi(createRoute({
+            method: "get",
+            path: "/auth/microsoft/callback",
+            summary: "Microsoft OAuth callback",
+            description: "Handles the redirect from Microsoft 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 Microsoft."),
+                    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);
+            if (!stored?.codeVerifier)
+                return c.json({ error: "Invalid or expired state" }, 400);
+            const tokens = await getMicrosoft().validateAuthorizationCode(code, stored.codeVerifier);
+            const info = await fetch("https://graph.microsoft.com/v1.0/me", {
+                headers: { Authorization: `Bearer ${tokens.accessToken()}` },
+            }).then((r) => r.json());
+            if (stored.linkUserId) {
+                const adapter = getAuthAdapter();
+                if (!adapter.linkProvider)
+                    return c.json({ error: "Auth adapter does not support linkProvider" }, 500);
+                await adapter.linkProvider(stored.linkUserId, "microsoft", info.id);
+                const sep = postLoginRedirect.includes("?") ? "&" : "?";
+                return c.redirect(`${postLoginRedirect}${sep}linked=microsoft`);
+            }
+            return finishOAuth(c, "microsoft", info.id, { email: info.mail ?? info.userPrincipalName, name: info.displayName }, postLoginRedirect);
+        });
+        router.use("/auth/microsoft/link", userAuth);
+        router.openapi(withSecurity(createRoute({
+            method: "get",
+            path: "/auth/microsoft/link",
+            summary: "Link Microsoft account",
+            description: "Initiates an OAuth flow to link a Microsoft account to the authenticated user. Requires a valid session. Redirects to Microsoft's sign-in page.",
+            tags,
+            responses: {
+                302: { description: "Redirect to Microsoft's OAuth sign-in page." },
+                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 = getMicrosoft().createAuthorizationURL(state, codeVerifier, ["openid", "profile", "email"]);
+            return c.redirect(url.toString());
+        });
+        router.openapi(withSecurity(createRoute({
+            method: "delete",
+            path: "/auth/microsoft/link",
+            summary: "Unlink Microsoft account",
+            description: "Removes the linked Microsoft OAuth account from the authenticated user. Requires a valid session.",
+            tags,
+            responses: {
+                204: { description: "Microsoft 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);
+            }
+            await adapter.unlinkProvider(c.get("authUserId"), "microsoft");
+            return c.body(null, 204);
+        });
+    }
+    // ─── GitHub ────────────────────────────────────────────────────────────
+    if (providers.includes("github")) {
+        router.openapi(createRoute({
+            method: "get",
+            path: "/auth/github",
+            summary: "Initiate GitHub OAuth",
+            description: "Redirects the user to GitHub's authorization page to begin the OAuth login flow. After the user authorizes, GitHub redirects back to `/auth/github/callback`.",
+            tags,
+            responses: {
+                302: { description: "Redirect to GitHub's OAuth authorization page." },
+                500: { content: { "application/json": { schema: OAuthErrorResponse } }, description: "OAuth provider not configured." },
+            },
+        }), async (c) => {
+            const state = generateState();
+            await storeOAuthState(state);
+            const url = getGitHub().createAuthorizationURL(state, ["read:user", "user:email"]);
+            return c.redirect(url.toString());
+        });
+        router.openapi(createRoute({
+            method: "get",
+            path: "/auth/github/callback",
+            summary: "GitHub OAuth callback",
+            description: "Handles the redirect from GitHub 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 GitHub."),
+                    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);
+            if (!stored)
+                return c.json({ error: "Invalid or expired state" }, 400);
+            const tokens = await getGitHub().validateAuthorizationCode(code);
+            const headers = { Authorization: `Bearer ${tokens.accessToken()}`, "User-Agent": "bunshot" };
+            const info = await fetch("https://api.github.com/user", { headers })
+                .then((r) => r.json());
+            // GitHub may not return email on /user if it's private — fetch from /user/emails
+            let email = info.email;
+            if (!email) {
+                const emails = await fetch("https://api.github.com/user/emails", { headers })
+                    .then((r) => r.json());
+                email = emails.find((e) => e.primary && e.verified)?.email ?? emails.find((e) => e.verified)?.email;
+            }
+            if (stored.linkUserId) {
+                const adapter = getAuthAdapter();
+                if (!adapter.linkProvider)
+                    return c.json({ error: "Auth adapter does not support linkProvider" }, 500);
+                await adapter.linkProvider(stored.linkUserId, "github", String(info.id));
+                const sep = postLoginRedirect.includes("?") ? "&" : "?";
+                return c.redirect(`${postLoginRedirect}${sep}linked=github`);
+            }
+            return finishOAuth(c, "github", String(info.id), { email, name: info.name, avatarUrl: info.avatar_url }, postLoginRedirect);
+        });
+        router.use("/auth/github/link", userAuth);
+        router.openapi(withSecurity(createRoute({
+            method: "get",
+            path: "/auth/github/link",
+            summary: "Link GitHub account",
+            description: "Initiates an OAuth flow to link a GitHub account to the authenticated user. Requires a valid session. Redirects to GitHub's authorization page.",
+            tags,
+            responses: {
+                302: { description: "Redirect to GitHub's OAuth authorization 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 = getGitHub().createAuthorizationURL(state, ["read:user", "user:email"]);
+            return c.redirect(url.toString());
+        });
+        router.openapi(withSecurity(createRoute({
+            method: "delete",
+            path: "/auth/github/link",
+            summary: "Unlink GitHub account",
+            description: "Removes the linked GitHub OAuth account from the authenticated user. Requires a valid session.",
+            tags,
+            responses: {
+                204: { description: "GitHub 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);
+            }
+            await adapter.unlinkProvider(c.get("authUserId"), "github");
+            return c.body(null, 204);
+        });
+    }
+    // ─── Code Exchange ─────────────────────────────────────────────────────
+    router.openapi(createRoute({
+        method: "post",
+        path: "/auth/oauth/exchange",
+        summary: "Exchange OAuth authorization code for session token",
+        description: "Exchanges a one-time authorization code (received from the OAuth redirect) for a session token. The code is single-use and expires after 60 seconds. Sets session cookies for browser clients; returns the token in the JSON response for mobile/SPA clients.",
+        tags,
+        request: {
+            body: {
+                content: {
+                    "application/json": {
+                        schema: z.object({
+                            code: z.string().describe("One-time authorization code from the OAuth redirect."),
+                        }),
+                    },
+                },
+            },
+        },
+        responses: {
+            200: {
+                content: {
+                    "application/json": {
+                        schema: z.object({
+                            token: z.string().describe("Session JWT."),
+                            userId: z.string().describe("Authenticated user ID."),
+                            email: z.string().optional().describe("User email if available."),
+                            refreshToken: z.string().optional().describe("Refresh token if refresh tokens are configured."),
+                        }),
+                    },
+                },
+                description: "Session token and user info.",
+            },
+            400: { content: { "application/json": { schema: OAuthErrorResponse } }, description: "Missing code parameter." },
+            401: { content: { "application/json": { schema: OAuthErrorResponse } }, description: "Invalid, expired, or already-used code." },
+            429: { content: { "application/json": { schema: OAuthErrorResponse } }, description: "Rate limit exceeded." },
+        },
+    }), async (c) => {
+        // Rate limit by IP to prevent brute-forcing codes within the 60s TTL
+        const ip = getClientIp(c);
+        const limited = await trackAttempt(`oauth-exchange:ip:${ip}`, { max: 20, windowMs: 60_000 });
+        if (limited) {
+            return c.json({ error: "Too many requests" }, 429);
+        }
+        const { code } = c.req.valid("json");
+        if (!code)
+            return c.json({ error: "Missing code" }, 400);
+        const payload = await consumeOAuthCode(code);
+        if (!payload)
+            return c.json({ error: "Invalid or expired code" }, 401);
+        // Set session cookies for browser clients
+        const rtConfig = getRefreshTokenConfig();
+        setCookie(c, COOKIE_TOKEN, payload.token, cookieOptions(rtConfig ? getAccessTokenExpiry() : undefined));
+        if (payload.refreshToken && rtConfig) {
+            setCookie(c, COOKIE_REFRESH_TOKEN, payload.refreshToken, cookieOptions(getRefreshTokenExpiry()));
+        }
+        if (getCsrfEnabled())
+            refreshCsrfToken(c);
+        return c.json({
+            token: payload.token,
+            userId: payload.userId,
+            email: payload.email,
+            refreshToken: payload.refreshToken,
+        }, 200);
+    });
     return router;
 };

package/dist/schemas/auth.d.ts

@@ -8,3 +8,5 @@ export declare const makeLoginSchema: (primaryField: PrimaryField) => z.ZodObjec
     [x: string]: z.ZodString;
     password: z.ZodString;
 }, z.core.$strip>;
+/** Password schema for reset-password — same policy as registration. */
+export declare const resetPasswordSchema: () => z.ZodString;