feat(web): add email/password auth with resend and session exchange

Add better-auth email/password authentication alongside existing OAuth flow.
Frontend uses Resend for verification emails and password resets.
Backend adds /session-exchange endpoint for email auth users who lack
OAuth provider tokens, verifying better-auth sessions directly.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: gracefullight

.agents/skills/oma-frontend/resources/snippets.md

@@ -202,6 +202,187 @@ export function StatsGrid({ children }: { children: React.ReactNode }) {
 
 ---
 
+## Email Auth - better-auth + Resend (Server Config)
+
+```typescript
+// src/lib/auth/auth-server.ts
+import { betterAuth } from "better-auth";
+import { nextCookies } from "better-auth/next-js";
+import { Resend } from "resend";
+import { env } from "@/config/env";
+
+const resend = new Resend(env.RESEND_API_KEY);
+
+export const auth = betterAuth({
+  baseURL: env.BETTER_AUTH_URL,
+  secret: env.BETTER_AUTH_SECRET,
+  emailAndPassword: {
+    enabled: true,
+    requireEmailVerification: true,
+    sendResetPassword: async ({ user, url }) => {
+      void resend.emails.send({
+        from: env.EMAIL_FROM,
+        to: user.email,
+        subject: "비밀번호 재설정",
+        html: `<a href="${url}">비밀번호 재설정하기</a>`,
+      });
+    },
+  },
+  emailVerification: {
+    sendOnSignUp: true,
+    sendVerificationEmail: async ({ user, url }) => {
+      void resend.emails.send({
+        from: env.EMAIL_FROM,
+        to: user.email,
+        subject: "이메일 인증",
+        html: `<a href="${url}">이메일 인증하기</a>`,
+      });
+    },
+  },
+  socialProviders: {
+    // ... existing OAuth providers
+  },
+  plugins: [nextCookies()],
+  session: {
+    expiresIn: 60 * 60 * 24 * 7,
+    cookieCache: { enabled: true, strategy: "jwe" },
+  },
+  trustedOrigins: [env.BETTER_AUTH_URL],
+});
+```
+
+---
+
+## Email Auth - Client (Sign Up / Sign In / Verify)
+
+```typescript
+// src/lib/auth/auth-client.ts
+import { createAuthClient } from "better-auth/react";
+import { env } from "@/config/env";
+
+export const authClient = createAuthClient({
+  baseURL: env.NEXT_PUBLIC_BETTER_AUTH_URL,
+});
+
+// Sign up with email
+export async function signUpWithEmail(email: string, password: string, name: string) {
+  return authClient.signUp.email({
+    email,
+    password,
+    name,
+    callbackURL: "/",
+  });
+}
+
+// Sign in with email
+export async function signInWithEmail(email: string, password: string) {
+  return authClient.signIn.email(
+    { email, password },
+    {
+      onError: (ctx) => {
+        if (ctx.error.status === 403) {
+          // Email not verified - show verification prompt
+        }
+      },
+    },
+  );
+}
+
+// Resend verification email
+export async function resendVerificationEmail(email: string) {
+  return authClient.sendVerificationEmail({
+    email,
+    callbackURL: "/",
+  });
+}
+
+// Request password reset
+export async function requestPasswordReset(email: string) {
+  return authClient.requestPasswordReset({
+    email,
+    redirectTo: "/reset-password",
+  });
+}
+
+// Reset password with token
+export async function resetPassword(token: string, newPassword: string) {
+  return authClient.resetPassword({
+    newPassword,
+    token,
+  });
+}
+```
+
+---
+
+## Email Auth - Backend Token Exchange (Bridge)
+
+Email auth에는 OAuth provider token이 없으므로, better-auth 세션 기반으로 백엔드 JWE 토큰을 교환합니다.
+
+```typescript
+// src/lib/auth/auth-client.ts - exchangeSessionForBackendJwt 추가
+export async function exchangeSessionForBackendJwt() {
+  const { data: session } = await authClient.getSession();
+  if (!session?.user?.email) return;
+
+  // email auth 유저는 OAuth provider가 없음
+  // better-auth 세션 토큰으로 백엔드에 직접 인증 요청
+  const sessionToken = document.cookie
+    .split("; ")
+    .find((row) => row.startsWith("better-auth.session_token="))
+    ?.split("=")[1];
+
+  if (!sessionToken) return;
+
+  const { data } = await apiClient.post<BackendTokenResponse>(
+    "/api/auth/session-exchange",
+    { session_token: sessionToken },
+  );
+
+  if (data?.access_token) setAccessToken(data.access_token);
+  if (data?.refresh_token) setRefreshToken(data.refresh_token);
+}
+```
+
+```typescript
+// src/app/providers.tsx - BackendJwtBridge 수정
+function BackendJwtBridge() {
+  const { data: session, isPending } = useSession();
+  const user = session?.user;
+
+  useEffect(() => {
+    if (isPending) return;
+    if (!user) {
+      if (hasBackendAccessToken()) clearBackendTokens();
+      return;
+    }
+    if (hasBackendAccessToken()) return;
+
+    // OAuth 유저는 기존 flow, email 유저는 session exchange
+    exchangeOAuthForBackendJwt()
+      .catch(() => exchangeSessionForBackendJwt())
+      .catch(() => {});
+  }, [isPending, user]);
+
+  return null;
+}
+```
+
+---
+
+## Email Auth - Environment Variables
+
+```typescript
+// src/config/env.ts - 추가할 환경변수
+server: {
+  // ... existing
+  RESEND_API_KEY: z.string().min(1),
+  EMAIL_FROM: z.string().email().optional().default("noreply@yourdomain.com"),
+},
+```
+
+---
+
 ## Vitest Component Test
 
 ```tsx

apps/api/src/auth/router.py

@@ -5,9 +5,11 @@
 from src.lib.auth import (
     OAuthLoginRequest,
     RefreshTokenRequest,
+    SessionExchangeRequest,
     TokenResponse,
     decode_token,
     verify_oauth_token,
+    verify_session_token,
 )
 from src.lib.dependencies import DBSession
 from src.users.model import User
@@ -53,6 +55,45 @@ async def login(
     )
 
 
+@router.post("/session-exchange", response_model=TokenResponse)
+async def session_exchange(
+    request: SessionExchangeRequest,
+    db: DBSession,
+) -> TokenResponse:
+    """Exchange better-auth session token for backend JWE tokens.
+
+    Used by email/password auth users who have no OAuth provider token.
+    Verifies session with better-auth server, then issues backend tokens.
+    """
+    user_info = await verify_session_token(request.session_token)
+
+    from sqlalchemy import select
+
+    result = await db.execute(select(User).where(User.email == user_info.email))
+    user = result.scalar_one_or_none()
+
+    if not user:
+        user = User(
+            email=user_info.email,
+            name=user_info.name,
+            image=user_info.image,
+            email_verified=user_info.email_verified,
+        )
+        db.add(user)
+        await db.commit()
+        await db.refresh(user)
+
+    from src.lib.auth import create_access_token, create_refresh_token
+
+    access_token = create_access_token(str(user.id))
+    refresh_token = create_refresh_token(str(user.id))
+
+    return TokenResponse(
+        access_token=access_token,
+        refresh_token=refresh_token,
+    )
+
+
 @router.post("/refresh", response_model=TokenResponse)
 async def refresh_token(
     request: RefreshTokenRequest,

apps/api/src/lib/auth.py

@@ -39,6 +39,12 @@ class OAuthLoginRequest(BaseModel):
     name: str | None = None
 
 
+class SessionExchangeRequest(BaseModel):
+    """Exchange better-auth session token for backend JWE tokens."""
+
+    session_token: str
+
+
 class RefreshTokenRequest(BaseModel):
     """Refresh token request."""
 
@@ -204,6 +210,36 @@ async def verify_facebook_token(access_token: str) -> OAuthUserInfo:
         )
 
 
+async def verify_session_token(session_token: str) -> OAuthUserInfo:
+    """Verify better-auth session token and extract user info."""
+    async with httpx.AsyncClient() as client:
+        response = await client.get(
+            f"{settings.BETTER_AUTH_URL}/api/auth/get-session",
+            headers={"Cookie": f"better-auth.session_token={session_token}"},
+            timeout=5.0,
+        )
+        if response.status_code != 200:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Invalid session token",
+            )
+        data = response.json()
+        user = data.get("user", {})
+        email = user.get("email")
+        if not email:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Invalid session: no email",
+            )
+        return OAuthUserInfo(
+            id=user.get("id", ""),
+            email=email,
+            name=user.get("name"),
+            image=user.get("image"),
+            email_verified=user.get("emailVerified", False),
+        )
+
+
 async def verify_oauth_token(provider: str, access_token: str) -> OAuthUserInfo:
     """Verify OAuth token based on provider."""
     if provider == "google":