fix: add auth callback route to complete email verification PKCE flow

- Add /auth/callback route handler to exchange the PKCE code for a
  session when users click their verification email link
- Fix emailRedirectTo to point to /auth/callback instead of /login
- Add /auth/callback to middleware public routes so unauthenticated
  users arriving from verification emails are not redirected away
- Show ?error= query param on login page for failed verification
- Fix backend /auth/signup crash when response.session is None
  (returns 202 with requires_email_confirmation flag instead)

Author: mohi-devhub

backend/routes/auth.py

@@ -1,4 +1,5 @@
 from fastapi import APIRouter, HTTPException, status, Depends, Request
+from fastapi.responses import JSONResponse
 from pydantic import BaseModel, EmailStr, Field
 from config.supabase_client import get_supabase
 from utils.auth import verify_user
@@ -84,15 +85,32 @@ async def signup(request: SignUpRequest, req: Request):
                 status_code=status.HTTP_400_BAD_REQUEST,
                 detail="Failed to create user account"
             )
-        
+
+        # When Supabase email confirmations are enabled, session is None until
+        # the user clicks the verification link. Return 202 to indicate that the
+        # account was created but is pending email confirmation.
+        if response.session is None:
+            return JSONResponse(
+                status_code=status.HTTP_202_ACCEPTED,
+                content={
+                    "message": "Account created. Please check your email to confirm your account.",
+                    "requires_email_confirmation": True,
+                    "user": {
+                        "id": str(response.user.id),
+                        "email": response.user.email,
+                        "created_at": str(response.user.created_at),
+                    },
+                },
+            )
+
         return {
             "access_token": response.session.access_token,
             "token_type": "bearer",
             "user": {
                 "id": response.user.id,
                 "email": response.user.email,
-                "created_at": response.user.created_at
-            }
+                "created_at": str(response.user.created_at),
+            },
         }
 
     except HTTPException:

frontend/app/auth/callback/route.ts

@@ -0,0 +1,43 @@
+import { createServerClient, type CookieOptions } from "@supabase/ssr";
+import { NextRequest, NextResponse } from "next/server";
+
+export async function GET(request: NextRequest) {
+  const requestUrl = new URL(request.url);
+  const code = requestUrl.searchParams.get("code");
+
+  if (code) {
+    // Build the response first so we can attach cookies to it
+    const response = NextResponse.redirect(
+      new URL("/dashboard", requestUrl.origin)
+    );
+
+    const supabase = createServerClient(
+      process.env.NEXT_PUBLIC_SUPABASE_URL!,
+      process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+      {
+        cookies: {
+          get(name: string) {
+            return request.cookies.get(name)?.value;
+          },
+          set(name: string, value: string, options: CookieOptions) {
+            response.cookies.set({ name, value, ...options });
+          },
+          remove(name: string, options: CookieOptions) {
+            response.cookies.set({ name, value: "", ...options });
+          },
+        },
+      }
+    );
+
+    const { error } = await supabase.auth.exchangeCodeForSession(code);
+
+    if (!error) {
+      return response;
+    }
+  }
+
+  // Verification failed or no code present — send user back to login with an error
+  return NextResponse.redirect(
+    new URL("/login?error=Email+verification+failed.+Please+try+again.", requestUrl.origin)
+  );
+}

frontend/app/login/page.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useState } from "react";
+import { useState, useEffect } from "react";
 import { useAuth } from "@/lib/useAuth";
 import { useRouter } from "next/navigation";
 import { motion } from "framer-motion";
@@ -16,6 +16,15 @@ export default function LoginPage() {
   const { signIn } = useAuth();
   const router = useRouter();
 
+  // Show any error passed via query param (e.g. from the auth callback route)
+  useEffect(() => {
+    const params = new URLSearchParams(window.location.search);
+    const errorParam = params.get("error");
+    if (errorParam) {
+      setError(errorParam);
+    }
+  }, []);
+
   const handleLogin = async (e: React.FormEvent) => {
     e.preventDefault();
     setLoading(true);

frontend/lib/useAuth.tsx

@@ -52,10 +52,11 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
   };
 
   const signUp = async (email: string, password: string, username: string) => {
-    // Get the current origin for redirect URL
-    const redirectUrl = typeof window !== 'undefined' 
-      ? `${window.location.origin}/login`
-      : 'https://study-quest-mohi-devhubs-projects.vercel.app/login';
+    // Get the current origin for redirect URL — must point to the auth callback
+    // handler so the PKCE code can be exchanged for a session.
+    const redirectUrl = typeof window !== 'undefined'
+      ? `${window.location.origin}/auth/callback`
+      : 'https://study-quest-mohi-devhubs-projects.vercel.app/auth/callback';
 
     const { data, error } = await supabase.auth.signUp({
       email,

frontend/middleware.ts

@@ -66,10 +66,14 @@ export async function middleware(req: NextRequest) {
   );
 
   // Public routes that don't require authentication (includes root for landing page)
-  const publicRoutes = ["/", "/landing"];
-  const isPublicRoute = 
-    req.nextUrl.pathname === "/" || 
-    publicRoutes.some((route) => req.nextUrl.pathname.startsWith(route + "/"));
+  // /auth/callback must be public so the email-verification redirect can reach it
+  // before a session exists.
+  const publicRoutes = ["/", "/landing", "/auth/callback"];
+  const isPublicRoute =
+    req.nextUrl.pathname === "/" ||
+    publicRoutes.some((route) =>
+      req.nextUrl.pathname === route || req.nextUrl.pathname.startsWith(route + "/")
+    );
 
   // If user is not authenticated and trying to access protected route
   if (!session && !isPublicRoute && !isAuthRoute) {