feat: implement stateless JWE authentication and add documentation

Author: gracefullight

.sisyphus/notepads/better-auth-analysis/better-auth-configuration.md

@@ -0,0 +1,6 @@
+# Decisions
+
+- Keep Better Auth server configuration in `apps/web/src/lib/auth.ts` as the only `auth` export (Next.js route handler depends on it).
+- Keep Better Auth React client in `apps/web/src/lib/auth-client.ts` as `authClient` (no `auth` export) to avoid naming collisions and keep concerns clear.
+- Implement a small client-side bridge that, once a Better Auth session exists, exchanges the provider access token for backend JWTs via `POST /api/auth/login`, then stores them via `setAccessToken`/`setRefreshToken`.
+- Mount the bridge once globally in `apps/web/src/app/providers.tsx` so existing pages don’t need to remember to do token exchange.

.sisyphus/notepads/better-auth-analysis/decisions.md

@@ -0,0 +1,3 @@
+# Issues
+
+- Backend OAuth login currently only supports `google`, `github`, and `facebook` (`apps/api/src/lib/auth.py`). If additional providers are added to Better Auth, the backend must be extended separately (out of scope).

.sisyphus/notepads/better-auth-analysis/issues.md

@@ -0,0 +1,6 @@
+# Learnings
+
+- Better Auth client can fetch provider OAuth access tokens post-login via `authClient.getAccessToken({ providerId })`.
+- Provider selection can be inferred via `authClient.listAccounts()` and reading `providerId`.
+- `authClient.getSession()` works well for a non-hook, async bridge that needs `session.user.email`/`name`.
+- Backend JWT storage already exists in `apps/web/src/lib/api-client.ts` (localStorage + refresh interceptor), so the missing piece is a one-time OAuth→JWT exchange.

.sisyphus/notepads/better-auth-analysis/learnings.md

@@ -0,0 +1,3 @@
+# Problems / Follow-ups
+
+- `apps/web/src/lib/api-client.ts` redirects to `/login` on missing/invalid refresh token, but there is currently no `/login` route implemented in `apps/web/src/app` (route group `(auth)` is empty). This isn’t introduced by the auth bridge, but it will matter once auth is wired into UI.

.sisyphus/notepads/better-auth-analysis/problems.md

@@ -12,6 +12,10 @@ CORS_ORIGINS=["http://localhost:3000"]
 # Auth (better-auth web server)
 BETTER_AUTH_URL=http://localhost:3000
 
+# JWT/JWE (stateless authentication)
+JWT_SECRET=your-super-secret-jwt-key-change-in-production
+JWE_SECRET_KEY=your-super-secret-jwe-encryption-key-change-in-production
+
 # Redis (optional)
 REDIS_URL=redis://localhost:6379
 

apps/api/.env.example

@@ -18,7 +18,7 @@
     fileConfig(config.config_file_name)
 
 # Set sqlalchemy.url from settings
-config.set_main_option("sqlalchemy.url", settings.DATABASE_URL_SYNC)
+config.set_main_option("sqlalchemy.url", settings.DATABASE_URL)
 
 target_metadata = Base.metadata
 

apps/api/alembic/env.py

@@ -22,6 +22,9 @@ dependencies = [
     "opentelemetry-instrumentation-httpx>=0.49b0",
     "opentelemetry-instrumentation-redis>=0.49b0",
     "opentelemetry-exporter-otlp>=1.28.0",
+    "python-jose>=3.3.0",
+    "cryptography>=44.0.0",
+    "psycopg2-binary>=2.9.9",
 ]
 
 [dependency-groups]
@@ -33,6 +36,7 @@ dev = [
     "pytest-asyncio>=0.26.0",
     "pytest-cov>=6.1.1",
     "factory-boy>=3.3.3",
+    "types-python-jose>=3.3.0.13",
 ]
 
 [tool.uv]

apps/api/pyproject.toml

@@ -0,0 +1,99 @@
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from src.lib.auth import (
+    OAuthLoginRequest,
+    RefreshTokenRequest,
+    TokenResponse,
+    CurrentUserInfo,
+    decode_token,
+    verify_oauth_token,
+)
+from src.lib.dependencies import DBSession
+from src.users.model import User
+
+router = APIRouter()
+
+
+@router.post("/login", response_model=TokenResponse)
+async def login(
+    request: OAuthLoginRequest,
+    db: DBSession,
+) -> TokenResponse:
+    """OAuth login endpoint.
+
+    Verify OAuth token, create/update user, and issue JWE tokens.
+    """
+    user_info = await verify_oauth_token(request.provider, request.access_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,
+    db: DBSession,
+) -> TokenResponse:
+    """Refresh access token using refresh token."""
+    payload = decode_token(request.refresh_token)
+
+    if payload.token_type != "refresh":
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid token type",
+        )
+
+    from sqlalchemy import select
+
+    result = await db.execute(select(User).where(User.id == UUID(payload.user_id)))
+    user = result.scalar_one_or_none()
+
+    if not user:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="User not found",
+        )
+
+    from src.lib.auth import create_access_token
+
+    access_token = create_access_token(str(user.id))
+
+    return TokenResponse(
+        access_token=access_token,
+        refresh_token=request.refresh_token,
+    )
+
+
+@router.post("/logout", status_code=status.HTTP_204_NO_CONTENT)
+async def logout() -> None:
+    """Logout endpoint.
+
+    Client should remove tokens from localStorage.
+    """
+    return None