Migrate Authentication from Better-Auth to fastapi-users

[frankbria]

Migrate Authentication from Better-Auth to fastapi-users

Summary

Replace the current Better-Auth (JavaScript) authentication setup with fastapi-users (Python) so that authentication is owned entirely by the FastAPI backend. This eliminates the architectural mismatch where a JavaScript auth library tries to sync with a Python backend.

Priority

P0 - Blocker — Required for multi-tenant user scoping. All database entities depend on user_id.

Problem Statement

Current State

• Frontend: Next.js with Better-Auth installed (cookies-only mode)
• Backend: FastAPI (Python) — the "real" application
• Database: SQLite (shared between both, but with schema conflicts)
• Failed Integration: Drizzle ORM was installed to try to bridge JS ↔ Python, but this doesn't work

Why It's Broken

Better-Auth is designed for JavaScript-only stacks. It expects to:

1. Own and manage user/session tables with its specific schema
2. Run in a Node.js environment
3. Handle both auth logic AND database operations in JavaScript

This creates an impedance mismatch when a Python backend also needs to:

• Validate authentication state
• Access user IDs for multi-tenant data scoping
• Manage its own database models

The result is confusion about:

• Table names (user vs users)
• ID types (string UUIDs vs integers)
• Password handling (who hashes, who validates)
• Two ORMs (Drizzle + SQLAlchemy) fighting over the same SQLite file

Target State

Python/FastAPI owns authentication completely. Next.js becomes a thin API client with no auth logic.

┌───────────────────────────────────────────────────────────┐
│  Next.js Frontend (UI only, no auth logic)                │
│  - Calls /api/auth/login, /api/auth/register on backend   │
│  - Stores JWT in memory or httpOnly cookie                │
│  - Sends Authorization: Bearer <token> on API calls       │
└───────────────────────────────────────────────────────────┘
                           │
                           ▼
┌───────────────────────────────────────────────────────────┐
│  FastAPI Backend (owns everything)                        │
│  ┌─────────────────────────────────────────────────────┐ │
│  │  fastapi-users                                      │ │
│  │  - /auth/register, /auth/login, /auth/logout        │ │
│  │  - Password hashing (bcrypt)                        │ │
│  │  - JWT token generation & validation                │ │
│  │  - Single source of truth for users table           │ │
│  └─────────────────────────────────────────────────────┘ │
│  ┌─────────────────────────────────────────────────────┐ │
│  │  SQLite - all tables owned by Python/SQLAlchemy     │ │
│  │  - users (UUID primary key)                         │ │
│  │  - All business entities with user_id FK            │ │
│  └─────────────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────────────┘

---

Implementation Tasks

Phase 1: Remove Better-Auth from Frontend

1.1 Remove Better-Auth dependencies

cd web-ui
npm uninstall better-auth @better-auth/client drizzle-orm drizzle-kit

1.2 Delete Better-Auth configuration files

Remove these files/directories if they exist:

• web-ui/lib/auth.ts (Better-Auth server config)
• web-ui/lib/auth-client.ts (Better-Auth client)
• web-ui/app/api/auth/[...all]/route.ts (Better-Auth API routes)
• web-ui/drizzle/ (Drizzle migrations/schema)
• web-ui/drizzle.config.ts
• Any *.db files created by Better-Auth in web-ui

1.3 Remove Better-Auth environment variables

Clean up .env and .env.local:

• BETTER_AUTH_SECRET
• BETTER_AUTH_URL
• Any Drizzle-related env vars

---

Phase 2: Install fastapi-users in Backend

2.1 Add dependencies

In pyproject.toml, add:

[project.dependencies]
# ... existing deps ...
fastapi-users = { extras = ["sqlalchemy"], version = "^13.0.0" }
aiosqlite = "^0.20.0"
python-jose = { extras = ["cryptography"], version = "^3.3.0" }
passlib = { extras = ["bcrypt"], version = "^1.7.4" }

Then run:

uv sync

2.2 Create auth module structure

codeframe/
├── auth/
│   ├── __init__.py
│   ├── models.py      # User SQLAlchemy model
│   ├── schemas.py     # Pydantic schemas (UserRead, UserCreate, UserUpdate)
│   ├── users.py       # fastapi-users configuration
│   ├── router.py      # Auth route mounting
│   └── dependencies.py # current_active_user dependency

---

Phase 3: Implement Auth Models

3.1 User model (codeframe/auth/models.py)

"""User model for authentication."""
import uuid
from typing import Optional

from fastapi_users.db import SQLAlchemyBaseUserTableUUID
from sqlalchemy import String, ForeignKey
from sqlalchemy.orm import Mapped, mapped_column

from codeframe.db import Base  # Import existing Base


class User(SQLAlchemyBaseUserTableUUID, Base):
    """User model with multi-tenant support."""
    
    __tablename__ = "users"
    
    # Additional fields for CodeFRAME
    display_name: Mapped[Optional[str]] = mapped_column(String(255), nullable=True)
    tenant_id: Mapped[Optional[uuid.UUID]] = mapped_column(nullable=True)
    
    # Relationships to existing models can be added here
    # projects: Mapped[list["Project"]] = relationship(back_populates="owner")

3.2 Pydantic schemas (codeframe/auth/schemas.py)

"""Pydantic schemas for user operations."""
import uuid
from typing import Optional

from fastapi_users import schemas


class UserRead(schemas.BaseUser[uuid.UUID]):
    """Schema for reading user data."""
    display_name: Optional[str] = None
    tenant_id: Optional[uuid.UUID] = None


class UserCreate(schemas.BaseUserCreate):
    """Schema for creating users."""
    display_name: Optional[str] = None


class UserUpdate(schemas.BaseUserUpdate):
    """Schema for updating users."""
    display_name: Optional[str] = None

---

Phase 4: Configure fastapi-users

4.1 User manager and auth backends (codeframe/auth/users.py)

"""fastapi-users configuration."""
import os
import uuid
from typing import Optional

from fastapi import Depends, Request
from fastapi_users import BaseUserManager, FastAPIUsers, UUIDIDMixin
from fastapi_users.authentication import (
    AuthenticationBackend,
    BearerTransport,
    JWTStrategy,
)
from fastapi_users.db import SQLAlchemyUserDatabase
from sqlalchemy.ext.asyncio import AsyncSession

from codeframe.auth.models import User
from codeframe.db import get_async_session  # You may need to create this

SECRET = os.getenv("AUTH_SECRET", "CHANGE-ME-IN-PRODUCTION-USE-SECRETS")
JWT_LIFETIME_SECONDS = 60 * 60 * 24 * 7  # 7 days


class UserManager(UUIDIDMixin, BaseUserManager[User, uuid.UUID]):
    """Custom user manager for CodeFRAME."""
    
    reset_password_token_secret = SECRET
    verification_token_secret = SECRET

    async def on_after_register(self, user: User, request: Optional[Request] = None):
        """Called after successful registration."""
        print(f"User {user.id} registered.")

    async def on_after_login(
        self, user: User, request: Optional[Request] = None, response=None
    ):
        """Called after successful login."""
        print(f"User {user.id} logged in.")


async def get_user_db(session: AsyncSession = Depends(get_async_session)):
    """Dependency for user database adapter."""
    yield SQLAlchemyUserDatabase(session, User)


async def get_user_manager(user_db: SQLAlchemyUserDatabase = Depends(get_user_db)):
    """Dependency for user manager."""
    yield UserManager(user_db)


# JWT Bearer token transport
bearer_transport = BearerTransport(tokenUrl="auth/login")


def get_jwt_strategy() -> JWTStrategy:
    """JWT strategy for authentication."""
    return JWTStrategy(secret=SECRET, lifetime_seconds=JWT_LIFETIME_SECONDS)


auth_backend = AuthenticationBackend(
    name="jwt",
    transport=bearer_transport,
    get_strategy=get_jwt_strategy,
)

# FastAPIUsers instance
fastapi_users = FastAPIUsers[User, uuid.UUID](
    get_user_manager,
    [auth_backend],
)

# Dependency for protected routes
current_active_user = fastapi_users.current_user(active=True)
current_superuser = fastapi_users.current_user(active=True, superuser=True)

4.2 Mount auth routes (codeframe/auth/router.py)

"""Auth router configuration."""
from fastapi import APIRouter

from codeframe.auth.schemas import UserCreate, UserRead, UserUpdate
from codeframe.auth.users import auth_backend, fastapi_users

router = APIRouter()

# Authentication routes (login, logout)
router.include_router(
    fastapi_users.get_auth_router(auth_backend),
    prefix="/auth",
    tags=["auth"],
)

# Registration route
router.include_router(
    fastapi_users.get_register_router(UserRead, UserCreate),
    prefix="/auth",
    tags=["auth"],
)

# User management routes (get me, update me)
router.include_router(
    fastapi_users.get_users_router(UserRead, UserUpdate),
    prefix="/users",
    tags=["users"],
)

# Optional: Reset password, verify email
# router.include_router(
#     fastapi_users.get_reset_password_router(),
#     prefix="/auth",
#     tags=["auth"],
# )
# router.include_router(
#     fastapi_users.get_verify_router(UserRead),
#     prefix="/auth",
#     tags=["auth"],
# )

---

Phase 5: Update FastAPI Application

5.1 Mount auth router in main app

In codeframe/ui/server.py (or wherever the FastAPI app is defined):

from codeframe.auth.router import router as auth_router

# Add auth routes
app.include_router(auth_router)

5.2 Create async database session (if not already async)

You may need to add an async session factory for fastapi-users. In codeframe/db.py:

from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine, async_sessionmaker

ASYNC_DATABASE_URL = "sqlite+aiosqlite:///./codeframe.db"

async_engine = create_async_engine(ASYNC_DATABASE_URL)
async_session_maker = async_sessionmaker(async_engine, expire_on_commit=False)


async def get_async_session() -> AsyncSession:
    async with async_session_maker() as session:
        yield session

---

Phase 6: Update Database Schema

6.1 Create migration for users table

If using Alembic:

alembic revision --autogenerate -m "Add users table for fastapi-users"
alembic upgrade head

Or if letting SQLAlchemy create tables:

# In startup or a script
async with async_engine.begin() as conn:
    await conn.run_sync(Base.metadata.create_all)

6.2 Clean up old Better-Auth tables

Remove any tables created by Better-Auth:

• user (singular)
• session
• account
• Any Drizzle migration tracking tables

---

Phase 7: Update Existing Protected Routes

7.1 Add auth dependency to existing routes

Before:

@app.get("/api/projects")
async def get_projects():
    return {"projects": [...]}

After:

from codeframe.auth.users import current_active_user
from codeframe.auth.models import User

@app.get("/api/projects")
async def get_projects(user: User = Depends(current_active_user)):
    # user.id is now available for scoping
    return db.query(Project).filter(Project.owner_id == user.id).all()

7.2 Create tenant context dependency (for multi-tenant scoping)

from fastapi import Depends
from codeframe.auth.users import current_active_user
from codeframe.auth.models import User


async def get_tenant_context(user: User = Depends(current_active_user)) -> dict:
    """Dependency that provides user and tenant context."""
    return {
        "user_id": user.id,
        "tenant_id": user.tenant_id,
    }

---

Phase 8: Update Frontend Auth Client

8.1 Create new auth client (web-ui/lib/auth.ts)

const API_URL = process.env.NEXT_PUBLIC_API_URL || 'http://localhost:8080';

interface AuthTokens {
  access_token: string;
  token_type: string;
}

interface User {
  id: string;
  email: string;
  display_name?: string;
  is_active: boolean;
  is_superuser: boolean;
  is_verified: boolean;
}

export async function login(email: string, password: string): Promise<AuthTokens> {
  const formData = new URLSearchParams();
  formData.append('username', email);  // fastapi-users expects 'username'
  formData.append('password', password);

  const res = await fetch(`${API_URL}/auth/login`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: formData,
  });

  if (!res.ok) {
    const error = await res.json();
    throw new Error(error.detail || 'Login failed');
  }
  
  return res.json();
}

export async function register(email: string, password: string, displayName?: string): Promise<User> {
  const res = await fetch(`${API_URL}/auth/register`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      email,
      password,
      display_name: displayName,
    }),
  });

  if (!res.ok) {
    const error = await res.json();
    throw new Error(error.detail || 'Registration failed');
  }
  
  return res.json();
}

export async function getCurrentUser(token: string): Promise<User> {
  const res = await fetch(`${API_URL}/users/me`, {
    headers: { Authorization: `Bearer ${token}` },
  });

  if (!res.ok) {
    throw new Error('Failed to get user');
  }
  
  return res.json();
}

export async function logout(token: string): Promise<void> {
  await fetch(`${API_URL}/auth/logout`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${token}` },
  });
}

8.2 Create auth context/hook (web-ui/lib/auth-context.tsx)

'use client';

import { createContext, useContext, useEffect, useState, ReactNode } from 'react';
import { login as apiLogin, logout as apiLogout, getCurrentUser, register as apiRegister } from './auth';

interface User {
  id: string;
  email: string;
  display_name?: string;
}

interface AuthContextType {
  user: User | null;
  token: string | null;
  isLoading: boolean;
  login: (email: string, password: string) => Promise<void>;
  register: (email: string, password: string, displayName?: string) => Promise<void>;
  logout: () => Promise<void>;
}

const AuthContext = createContext<AuthContextType | undefined>(undefined);

export function AuthProvider({ children }: { children: ReactNode }) {
  const [user, setUser] = useState<User | null>(null);
  const [token, setToken] = useState<string | null>(null);
  const [isLoading, setIsLoading] = useState(true);

  useEffect(() => {
    // Check for existing token on mount
    const storedToken = localStorage.getItem('auth_token');
    if (storedToken) {
      getCurrentUser(storedToken)
        .then(setUser)
        .catch(() => localStorage.removeItem('auth_token'))
        .finally(() => setIsLoading(false));
      setToken(storedToken);
    } else {
      setIsLoading(false);
    }
  }, []);

  const login = async (email: string, password: string) => {
    const { access_token } = await apiLogin(email, password);
    localStorage.setItem('auth_token', access_token);
    setToken(access_token);
    const user = await getCurrentUser(access_token);
    setUser(user);
  };

  const register = async (email: string, password: string, displayName?: string) => {
    await apiRegister(email, password, displayName);
    // Auto-login after registration
    await login(email, password);
  };

  const logout = async () => {
    if (token) {
      await apiLogout(token);
    }
    localStorage.removeItem('auth_token');
    setToken(null);
    setUser(null);
  };

  return (
    <AuthContext.Provider value={{ user, token, isLoading, login, register, logout }}>
      {children}
    </AuthContext.Provider>
  );
}

export function useAuth() {
  const context = useContext(AuthContext);
  if (context === undefined) {
    throw new Error('useAuth must be used within an AuthProvider');
  }
  return context;
}

---

Phase 9: Testing

9.1 Backend auth tests (tests/auth/test_auth.py)

"""Tests for authentication endpoints."""
import pytest
from httpx import AsyncClient

from codeframe.ui.server import app


@pytest.mark.asyncio
async def test_register_user():
    async with AsyncClient(app=app, base_url="http://test") as client:
        response = await client.post(
            "/auth/register",
            json={
                "email": "test@example.com",
                "password": "securepassword123",
            },
        )
        assert response.status_code == 201
        data = response.json()
        assert data["email"] == "test@example.com"
        assert "id" in data


@pytest.mark.asyncio
async def test_login_user():
    async with AsyncClient(app=app, base_url="http://test") as client:
        # Register first
        await client.post(
            "/auth/register",
            json={"email": "login@example.com", "password": "password123"},
        )
        
        # Login
        response = await client.post(
            "/auth/login",
            data={"username": "login@example.com", "password": "password123"},
        )
        assert response.status_code == 200
        data = response.json()
        assert "access_token" in data


@pytest.mark.asyncio
async def test_protected_route_without_token():
    async with AsyncClient(app=app, base_url="http://test") as client:
        response = await client.get("/users/me")
        assert response.status_code == 401


@pytest.mark.asyncio
async def test_protected_route_with_token():
    async with AsyncClient(app=app, base_url="http://test") as client:
        # Register and login
        await client.post(
            "/auth/register",
            json={"email": "protected@example.com", "password": "password123"},
        )
        login_response = await client.post(
            "/auth/login",
            data={"username": "protected@example.com", "password": "password123"},
        )
        token = login_response.json()["access_token"]
        
        # Access protected route
        response = await client.get(
            "/users/me",
            headers={"Authorization": f"Bearer {token}"},
        )
        assert response.status_code == 200
        assert response.json()["email"] == "protected@example.com"

9.2 Frontend auth tests

Add Playwright E2E tests for login/register flow.

---

Environment Variables

Add to .env.example:

# Authentication
AUTH_SECRET=your-secret-key-here-use-openssl-rand-hex-32

---

Migration Checklist

• Phase 1: Remove Better-Auth from frontend
  • Uninstall npm packages
  • Delete config files
  • Clean up env vars
• Phase 2: Install fastapi-users
  • Add dependencies to pyproject.toml
  • Create auth module structure
• Phase 3: Implement models
  • User model with UUID PK
  • Pydantic schemas
• Phase 4: Configure fastapi-users
  • User manager
  • JWT auth backend
  • Mount routes
• Phase 5: Update FastAPI app
  • Mount auth router
  • Create async session if needed
• Phase 6: Database migration
  • Create users table
  • Remove Better-Auth tables
• Phase 7: Update protected routes
  • Add current_active_user dependency
  • Create tenant context helper
• Phase 8: Update frontend
  • New auth client
  • Auth context/provider
  • Update components using auth
• Phase 9: Testing
  • Backend unit tests
  • E2E tests for auth flow
  • Verify multi-tenant scoping works

---

Acceptance Criteria

1. Registration works: POST /auth/register creates user in Python-owned users table
2. Login returns JWT: POST /auth/login returns { access_token, token_type }
3. Protected routes work: Routes with current_active_user dependency reject unauthenticated requests (401)
4. User ID available: user.id is accessible in route handlers for multi-tenant scoping
5. Frontend can authenticate: Login/register forms work end-to-end
6. No Better-Auth remnants: All JS auth code removed, no Drizzle, no Better-Auth tables
7. Tests pass: Both backend unit tests and E2E auth tests pass

---

Related Issues

• Closes existing auth-related issues

Labels

bug, P0-blocker-beta, auth, refactor

[traycerai]

Plan

Observations

The codebase currently uses Better-Auth (JavaScript) with Drizzle ORM to manage authentication in a shared SQLite database. The backend Python code validates tokens by querying the sessions table directly. The database already has Better-Auth compatible tables (users, accounts, sessions, verification) created by file:codeframe/persistence/schema_manager.py. The file:codeframe/ui/auth.py module implements custom authentication that reads from these tables. Projects already have user_id foreign keys and a project_users table for multi-tenant access control. The AUTH_REQUIRED environment variable defaults to false for backward compatibility.

Approach

Replace Better-Auth with fastapi-users to consolidate authentication ownership in the Python backend. The migration will preserve the existing users table structure but replace session-based authentication with JWT tokens. The frontend will become a stateless API client that stores JWTs and sends them via Authorization headers. The existing database schema requires minimal changes since fastapi-users can work with the current users table by defining a custom SQLAlchemy model. Remove all JavaScript auth dependencies (Better-Auth, Drizzle ORM) and replace with simple fetch-based API calls to FastAPI endpoints.

Implementation Steps

Phase 1: Backend - Install fastapi-users Dependencies

1.1 Update file:pyproject.toml dependencies

Add the following to the dependencies array:

"fastapi-users[sqlalchemy]==13.0.0",
"python-jose[cryptography]==3.3.0",
"passlib[bcrypt]==1.7.4",

Note: aiosqlite>=0.19.0 is already present in dependencies.

Run uv sync to install new packages.

1.2 Add environment variable to file:.env.example

Add authentication configuration section:

# ============================================================================
# Authentication (fastapi-users)
# ============================================================================

# Secret key for JWT token signing (REQUIRED in production)
# Generate with: openssl rand -hex 32
AUTH_SECRET=your-secret-key-change-in-production

# JWT token lifetime in seconds (default: 7 days)
# JWT_LIFETIME_SECONDS=604800

# Enable authentication requirement (default: false for migration)
# Set to true in production to enforce authentication
# AUTH_REQUIRED=false

---

Phase 2: Backend - Create Auth Module Structure

2.1 Create auth module directory

Create file:codeframe/auth/ directory with the following files:

• __init__.py
• models.py - SQLAlchemy User model
• schemas.py - Pydantic schemas for API
• manager.py - User manager and auth backends
• dependencies.py - Dependency injection for routes

2.2 Implement file:codeframe/auth/models.py

Create SQLAlchemy User model that works with existing users table:

"""SQLAlchemy User model for fastapi-users."""
from typing import Optional
from fastapi_users.db import SQLAlchemyBaseUserTable
from sqlalchemy import Integer, String, Boolean
from sqlalchemy.orm import Mapped, mapped_column, DeclarativeBase

class Base(DeclarativeBase):
    """SQLAlchemy declarative base."""
    pass

class User(SQLAlchemyBaseUserTable[int], Base):
    """User model compatible with existing users table.
    
    Uses integer primary key instead of UUID to match existing schema.
    Maps to existing 'users' table created by SchemaManager.
    """
    __tablename__ = "users"
    
    # Override id to use Integer instead of UUID
    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    
    # Required fastapi-users fields (already in schema)
    email: Mapped[str] = mapped_column(String(255), unique=True, nullable=False)
    hashed_password: Mapped[str] = mapped_column(String(1024), nullable=False)
    is_active: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
    is_superuser: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
    is_verified: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
    
    # Additional fields from existing schema
    name: Mapped[Optional[str]] = mapped_column(String(255), nullable=True)

Important: The existing users table doesn't have hashed_password, is_active, is_superuser, or is_verified columns. These need to be added via migration.

2.3 Implement file:codeframe/auth/schemas.py

Create Pydantic schemas for API requests/responses:

"""Pydantic schemas for user operations."""
from typing import Optional
from fastapi_users import schemas

class UserRead(schemas.BaseUser[int]):
    """Schema for reading user data."""
    name: Optional[str] = None

class UserCreate(schemas.BaseUserCreate):
    """Schema for creating users."""
    name: Optional[str] = None

class UserUpdate(schemas.BaseUserUpdate):
    """Schema for updating users."""
    name: Optional[str] = None

2.4 Implement file:codeframe/auth/manager.py

Configure fastapi-users with JWT authentication:

"""User manager and authentication backends."""
import os
from typing import Optional
from fastapi import Depends, Request
from fastapi_users import BaseUserManager, IntegerIDMixin, FastAPIUsers
from fastapi_users.authentication import (
    AuthenticationBackend,
    BearerTransport,
    JWTStrategy,
)
from fastapi_users.db import SQLAlchemyUserDatabase
from sqlalchemy.ext.asyncio import AsyncSession

from codeframe.auth.models import User
from codeframe.persistence.database import Database

# Get configuration from environment
SECRET = os.getenv("AUTH_SECRET", "CHANGE-ME-IN-PRODUCTION")
JWT_LIFETIME_SECONDS = int(os.getenv("JWT_LIFETIME_SECONDS", "604800"))  # 7 days

class UserManager(IntegerIDMixin, BaseUserManager[User, int]):
    """User manager for CodeFRAME."""
    
    reset_password_token_secret = SECRET
    verification_token_secret = SECRET

    async def on_after_register(self, user: User, request: Optional[Request] = None):
        """Called after successful registration."""
        print(f"User {user.id} ({user.email}) registered.")

    async def on_after_login(
        self, user: User, request: Optional[Request] = None, response=None
    ):
        """Called after successful login."""
        print(f"User {user.id} ({user.email}) logged in.")

async def get_async_session(request: Request) -> AsyncSession:
    """Get async database session from app state."""
    db: Database = request.app.state.db
    async_conn = await db._get_async_conn()
    # Create async session from connection
    from sqlalchemy.ext.asyncio import AsyncSession
    session = AsyncSession(bind=async_conn)
    try:
        yield session
    finally:
        await session.close()

async def get_user_db(session: AsyncSession = Depends(get_async_session)):
    """Get user database adapter."""
    yield SQLAlchemyUserDatabase(session, User)

async def get_user_manager(user_db: SQLAlchemyUserDatabase = Depends(get_user_db)):
    """Get user manager."""
    yield UserManager(user_db)

# JWT Bearer token transport
bearer_transport = BearerTransport(tokenUrl="auth/jwt/login")

def get_jwt_strategy() -> JWTStrategy:
    """JWT strategy for authentication."""
    return JWTStrategy(secret=SECRET, lifetime_seconds=JWT_LIFETIME_SECONDS)

# Authentication backend
auth_backend = AuthenticationBackend(
    name="jwt",
    transport=bearer_transport,
    get_strategy=get_jwt_strategy,
)

# FastAPIUsers instance
fastapi_users = FastAPIUsers[User, int](
    get_user_manager,
    [auth_backend],
)

# Dependencies for protected routes
current_active_user = fastapi_users.current_user(active=True)
current_superuser = fastapi_users.current_user(active=True, superuser=True)

2.5 Implement file:codeframe/auth/dependencies.py

Create dependency for backward compatibility with existing file:codeframe/ui/auth.py:

"""Authentication dependencies for route handlers."""
from fastapi import Depends
from codeframe.auth.models import User
from codeframe.auth.manager import current_active_user

async def get_current_user(user: User = Depends(current_active_user)) -> User:
    """Get currently authenticated user.
    
    Replacement for codeframe.ui.auth.get_current_user.
    Returns fastapi-users User model instead of Pydantic User.
    """
    return user

2.6 Create file:codeframe/auth/__init__.py

Export public API:

"""Authentication module for CodeFRAME."""
from codeframe.auth.models import User
from codeframe.auth.schemas import UserRead, UserCreate, UserUpdate
from codeframe.auth.manager import fastapi_users, auth_backend, current_active_user
from codeframe.auth.dependencies import get_current_user

__all__ = [
    "User",
    "UserRead",
    "UserCreate",
    "UserUpdate",
    "fastapi_users",
    "auth_backend",
    "current_active_user",
    "get_current_user",
]

---

Phase 3: Backend - Database Migration

3.1 Update file:codeframe/persistence/schema_manager.py

Modify _create_auth_tables method to add fastapi-users required columns:

def _create_auth_tables(self, cursor: sqlite3.Cursor) -> None:
    """Create authentication tables (fastapi-users compatible)."""
    cursor.execute(
        """
        CREATE TABLE IF NOT EXISTS users (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            email TEXT UNIQUE NOT NULL,
            name TEXT,
            hashed_password TEXT NOT NULL,
            is_active INTEGER DEFAULT 1,
            is_superuser INTEGER DEFAULT 0,
            is_verified INTEGER DEFAULT 0,
            email_verified INTEGER DEFAULT 0,
            image TEXT,
            created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
            updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
        )
        """
    )

3.2 Create migration script file:codeframe/persistence/migrations/migrate_to_fastapi_users.py

Create migration to add missing columns to existing users table:

"""Migration: Add fastapi-users columns to users table."""
import sqlite3
import logging
from pathlib import Path

logger = logging.getLogger(__name__)

def migrate(db_path: Path) -> None:
    """Add fastapi-users required columns to users table.
    
    Adds:
    - hashed_password TEXT NOT NULL DEFAULT ''
    - is_active INTEGER DEFAULT 1
    - is_superuser INTEGER DEFAULT 0
    - is_verified INTEGER DEFAULT 0
    """
    conn = sqlite3.connect(str(db_path))
    cursor = conn.cursor()
    
    try:
        # Check if columns already exist
        cursor.execute("PRAGMA table_info(users)")
        columns = {row[1] for row in cursor.fetchall()}
        
        # Add missing columns
        if "hashed_password" not in columns:
            cursor.execute("ALTER TABLE users ADD COLUMN hashed_password TEXT NOT NULL DEFAULT ''")
            logger.info("Added hashed_password column to users table")
        
        if "is_active" not in columns:
            cursor.execute("ALTER TABLE users ADD COLUMN is_active INTEGER DEFAULT 1")
            logger.info("Added is_active column to users table")
        
        if "is_superuser" not in columns:
            cursor.execute("ALTER TABLE users ADD COLUMN is_superuser INTEGER DEFAULT 0")
            logger.info("Added is_superuser column to users table")
        
        if "is_verified" not in columns:
            cursor.execute("ALTER TABLE users ADD COLUMN is_verified INTEGER DEFAULT 0")
            logger.info("Added is_verified column to users table")
        
        conn.commit()
        logger.info("Migration completed successfully")
        
    except Exception as e:
        conn.rollback()
        logger.error(f"Migration failed: {e}")
        raise
    finally:
        conn.close()

if __name__ == "__main__":
    import sys
    if len(sys.argv) < 2:
        print("Usage: python migrate_to_fastapi_users.py <db_path>")
        sys.exit(1)
    
    db_path = Path(sys.argv[1])
    migrate(db_path)

Run migration: python -m codeframe.persistence.migrations.migrate_to_fastapi_users .codeframe/state.db

3.3 Drop Better-Auth specific tables

The accounts, sessions, and verification tables are no longer needed with JWT authentication. These can be dropped after migration is complete:

DROP TABLE IF EXISTS accounts;
DROP TABLE IF EXISTS sessions;
DROP TABLE IF EXISTS verification;

Add this to migration script or run manually after confirming JWT auth works.

---

Phase 4: Backend - Mount Auth Routes

4.1 Update file:codeframe/ui/server.py

Import and mount fastapi-users routers:

# Add to imports section
from codeframe.auth.manager import fastapi_users, auth_backend
from codeframe.auth.schemas import UserRead, UserCreate, UserUpdate

# Add after existing router mounts (around line 335)
# Mount authentication routes
app.include_router(
    fastapi_users.get_auth_router(auth_backend),
    prefix="/auth/jwt",
    tags=["auth"],
)

app.include_router(
    fastapi_users.get_register_router(UserRead, UserCreate),
    prefix="/auth",
    tags=["auth"],
)

app.include_router(
    fastapi_users.get_users_router(UserRead, UserUpdate),
    prefix="/users",
    tags=["users"],
)

This creates the following endpoints:

• POST /auth/jwt/login - Login with email/password, returns JWT
• POST /auth/jwt/logout - Logout (client-side token deletion)
• POST /auth/register - Register new user
• GET /users/me - Get current user info
• PATCH /users/me - Update current user

4.2 Update existing protected routes

Replace imports in route files (e.g., file:codeframe/ui/routers/projects.py):

# OLD:
from codeframe.ui.auth import get_current_user, User

# NEW:
from codeframe.auth import get_current_user, User

The User type changes from Pydantic model to SQLAlchemy model, but the interface remains compatible (user.id, user.email, user.name).

4.3 Deprecate file:codeframe/ui/auth.py

Add deprecation notice at top of file:

"""DEPRECATED: This module is deprecated in favor of codeframe.auth.

This module provided Better-Auth session validation. It has been replaced
by fastapi-users with JWT authentication in codeframe.auth.

Migration path:
- Replace: from codeframe.ui.auth import get_current_user
- With: from codeframe.auth import get_current_user

This file will be removed in a future release.
"""

---

Phase 5: Frontend - Remove Better-Auth

5.1 Remove Better-Auth dependencies from file:web-ui/package.json

Remove the following packages:

• better-auth
• better-sqlite3
• drizzle-orm
• @types/better-sqlite3

Run: npm uninstall better-auth better-sqlite3 drizzle-orm @types/better-sqlite3

5.2 Delete Better-Auth configuration files

Remove the following files:

• file:web-ui/src/lib/auth.ts
• file:web-ui/src/lib/auth-client.ts
• file:web-ui/src/lib/db-schema.ts
• file:web-ui/src/app/api/auth/[...all]/route.ts

5.3 Update file:web-ui/.env.local (or create if missing)

Add FastAPI backend URL:

NEXT_PUBLIC_API_URL=http://localhost:8080

---

Phase 6: Frontend - Create New Auth Client

6.1 Create file:web-ui/src/lib/api-client.ts

Create simple fetch-based API client:

const API_URL = process.env.NEXT_PUBLIC_API_URL || 'http://localhost:8080';

export interface AuthTokens {
  access_token: string;
  token_type: string;
}

export interface User {
  id: number;
  email: string;
  name?: string;
  is_active: boolean;
  is_superuser: boolean;
  is_verified: boolean;
}

export interface LoginCredentials {
  username: string;  // fastapi-users expects 'username' field
  password: string;
}

export interface RegisterData {
  email: string;
  password: string;
  name?: string;
}

export async function login(email: string, password: string): Promise<AuthTokens> {
  const formData = new URLSearchParams();
  formData.append('username', email);
  formData.append('password', password);

  const res = await fetch(`${API_URL}/auth/jwt/login`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: formData,
  });

  if (!res.ok) {
    const error = await res.json().catch(() => ({ detail: 'Login failed' }));
    throw new Error(error.detail || 'Login failed');
  }
  
  return res.json();
}

export async function register(data: RegisterData): Promise<User> {
  const res = await fetch(`${API_URL}/auth/register`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(data),
  });

  if (!res.ok) {
    const error = await res.json().catch(() => ({ detail: 'Registration failed' }));
    throw new Error(error.detail || 'Registration failed');
  }
  
  return res.json();
}

export async function getCurrentUser(token: string): Promise<User> {
  const res = await fetch(`${API_URL}/users/me`, {
    headers: { Authorization: `Bearer ${token}` },
  });

  if (!res.ok) {
    throw new Error('Failed to get user');
  }
  
  return res.json();
}

export async function logout(token: string): Promise<void> {
  // JWT logout is client-side only (delete token)
  // Optional: call backend to invalidate token if using token blacklist
  await fetch(`${API_URL}/auth/jwt/logout`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${token}` },
  });
}

6.2 Create file:web-ui/src/contexts/AuthContext.tsx

Create React context for auth state management:

'use client';

import { createContext, useContext, useEffect, useState, ReactNode } from 'react';
import { login as apiLogin, logout as apiLogout, getCurrentUser, register as apiRegister, User } from '@/lib/api-client';

interface AuthContextType {
  user: User | null;
  token: string | null;
  isLoading: boolean;
  login: (email: string, password: string) => Promise<void>;
  register: (email: string, password: string, name?: string) => Promise<void>;
  logout: () => Promise<void>;
}

const AuthContext = createContext<AuthContextType | undefined>(undefined);

export function AuthProvider({ children }: { children: ReactNode }) {
  const [user, setUser] = useState<User | null>(null);
  const [token, setToken] = useState<string | null>(null);
  const [isLoading, setIsLoading] = useState(true);

  useEffect(() => {
    // Check for existing token on mount
    const storedToken = localStorage.getItem('auth_token');
    if (storedToken) {
      getCurrentUser(storedToken)
        .then((userData) => {
          setUser(userData);
          setToken(storedToken);
        })
        .catch(() => {
          localStorage.removeItem('auth_token');
        })
        .finally(() => setIsLoading(false));
    } else {
      setIsLoading(false);
    }
  }, []);

  const login = async (email: string, password: string) => {
    const { access_token } = await apiLogin(email, password);
    localStorage.setItem('auth_token', access_token);
    setToken(access_token);
    const userData = await getCurrentUser(access_token);
    setUser(userData);
  };

  const register = async (email: string, password: string, name?: string) => {
    await apiRegister({ email, password, name });
    // Auto-login after registration
    await login(email, password);
  };

  const logout = async () => {
    if (token) {
      await apiLogout(token);
    }
    localStorage.removeItem('auth_token');
    setToken(null);
    setUser(null);
  };

  return (
    <AuthContext.Provider value={{ user, token, isLoading, login, register, logout }}>
      {children}
    </AuthContext.Provider>
  );
}

export function useAuth() {
  const context = useContext(AuthContext);
  if (context === undefined) {
    throw new Error('useAuth must be used within an AuthProvider');
  }
  return context;
}

6.3 Update file:web-ui/src/app/layout.tsx

Wrap app with AuthProvider:

import { AuthProvider } from '@/contexts/AuthContext';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <AuthProvider>
          {children}
        </AuthProvider>
      </body>
    </html>
  );
}

6.4 Update auth components

Update file:web-ui/src/components/auth/LoginForm.tsx:

'use client';

import { useState } from 'react';
import { useAuth } from '@/contexts/AuthContext';
import { useRouter } from 'next/navigation';

export function LoginForm() {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const [error, setError] = useState('');
  const { login } = useAuth();
  const router = useRouter();

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    setError('');
    
    try {
      await login(email, password);
      router.push('/dashboard');
    } catch (err) {
      setError(err instanceof Error ? err.message : 'Login failed');
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      {error && <div className="error">{error}</div>}
      <input
        type="email"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        placeholder="Email"
        required
      />
      <input
        type="password"
        value={password}
        onChange={(e) => setPassword(e.target.value)}
        placeholder="Password"
        required
      />
      <button type="submit">Login</button>
    </form>
  );
}

Update file:web-ui/src/components/auth/SignupForm.tsx similarly.

Update file:web-ui/src/components/auth/ProtectedRoute.tsx:

'use client';

import { useAuth } from '@/contexts/AuthContext';
import { useRouter } from 'next/navigation';
import { useEffect } from 'react';

export function ProtectedRoute({ children }: { children: React.ReactNode }) {
  const { user, isLoading } = useAuth();
  const router = useRouter();

  useEffect(() => {
    if (!isLoading && !user) {
      router.push('/login');
    }
  }, [user, isLoading, router]);

  if (isLoading) {
    return <div>Loading...</div>;
  }

  if (!user) {
    return null;
  }

  return <>{children}</>;
}

---

Phase 7: Update API Calls to Include Auth Token

7.1 Create authenticated fetch wrapper in file:web-ui/src/lib/api-client.ts

Add helper function for authenticated requests:

export async function authenticatedFetch(
  url: string,
  options: RequestInit = {}
): Promise<Response> {
  const token = localStorage.getItem('auth_token');
  
  if (!token) {
    throw new Error('Not authenticated');
  }

  const headers = new Headers(options.headers);
  headers.set('Authorization', `Bearer ${token}`);

  return fetch(url, {
    ...options,
    headers,
  });
}

7.2 Update existing API calls

Update all API calls in components to use authenticatedFetch instead of plain fetch. For example, in project-related components:

// OLD:
const res = await fetch(`${API_URL}/api/projects`);

// NEW:
import { authenticatedFetch } from '@/lib/api-client';
const res = await authenticatedFetch(`${API_URL}/api/projects`);

---

Phase 8: Testing

8.1 Create backend auth tests in file:tests/auth/test_auth_endpoints.py

"""Tests for fastapi-users authentication endpoints."""
import pytest
from httpx import AsyncClient
from codeframe.ui.server import app

@pytest.mark.asyncio
async def test_register_user():
    async with AsyncClient(app=app, base_url="http://test") as client:
        response = await client.post(
            "/auth/register",
            json={
                "email": "test@example.com",
                "password": "securepassword123",
                "name": "Test User",
            },
        )
        assert response.status_code == 201
        data = response.json()
        assert data["email"] == "test@example.com"
        assert data["name"] == "Test User"
        assert "id" in data
        assert "hashed_password" not in data

@pytest.mark.asyncio
async def test_login_user():
    async with AsyncClient(app=app, base_url="http://test") as client:
        # Register first
        await client.post(
            "/auth/register",
            json={"email": "login@example.com", "password": "password123"},
        )
        
        # Login
        response = await client.post(
            "/auth/jwt/login",
            data={"username": "login@example.com", "password": "password123"},
            headers={"Content-Type": "application/x-www-form-urlencoded"},
        )
        assert response.status_code == 200
        data = response.json()
        assert "access_token" in data
        assert data["token_type"] == "bearer"

@pytest.mark.asyncio
async def test_get_current_user():
    async with AsyncClient(app=app, base_url="http://test") as client:
        # Register and login
        await client.post(
            "/auth/register",
            json={"email": "me@example.com", "password": "password123"},
        )
        login_response = await client.post(
            "/auth/jwt/login",
            data={"username": "me@example.com", "password": "password123"},
            headers={"Content-Type": "application/x-www-form-urlencoded"},
        )
        token = login_response.json()["access_token"]
        
        # Get current user
        response = await client.get(
            "/users/me",
            headers={"Authorization": f"Bearer {token}"},
        )
        assert response.status_code == 200
        assert response.json()["email"] == "me@example.com"

@pytest.mark.asyncio
async def test_protected_route_without_token():
    async with AsyncClient(app=app, base_url="http://test") as client:
        response = await client.get("/users/me")
        assert response.status_code == 401

8.2 Update E2E tests in file:tests/e2e/test_auth_flow.spec.ts

Update Playwright tests to use new auth flow:

import { test, expect } from '@playwright/test';

test('user can register and login', async ({ page }) => {
  // Navigate to register page
  await page.goto('http://localhost:3000/register');
  
  // Fill registration form
  await page.fill('input[type="email"]', 'test@example.com');
  await page.fill('input[type="password"]', 'securepassword123');
  await page.fill('input[name="name"]', 'Test User');
  await page.click('button[type="submit"]');
  
  // Should redirect to dashboard after auto-login
  await expect(page).toHaveURL('http://localhost:3000/dashboard');
  
  // Verify user is logged in
  await expect(page.locator('text=Test User')).toBeVisible();
});

test('protected route redirects to login', async ({ page }) => {
  // Try to access protected route without auth
  await page.goto('http://localhost:3000/dashboard');
  
  // Should redirect to login
  await expect(page).toHaveURL('http://localhost:3000/login');
});

---

Phase 9: Cleanup and Documentation

9.1 Remove deprecated files

After confirming migration works:

• Delete file:codeframe/ui/auth.py
• Delete Better-Auth database tables (run migration script)

9.2 Update documentation

Update file:README.md with new authentication setup:

## Authentication

CodeFRAME uses fastapi-users for authentication with JWT tokens.

### Environment Variables

- `AUTH_SECRET`: Secret key for JWT signing (required in production)
- `JWT_LIFETIME_SECONDS`: Token lifetime in seconds (default: 604800 = 7 days)
- `AUTH_REQUIRED`: Enable authentication requirement (default: false)

### API Endpoints

- `POST /auth/register` - Register new user
- `POST /auth/jwt/login` - Login (returns JWT token)
- `POST /auth/jwt/logout` - Logout
- `GET /users/me` - Get current user info
- `PATCH /users/me` - Update current user

### Frontend Usage

```typescript
import { useAuth } from '@/contexts/AuthContext';

function MyComponent() {
  const { user, login, logout } = useAuth();
  
  if (!user) {
    return <button onClick={() => login(email, password)}>Login</button>;
  }
  
  return <div>Welcome, {user.name}!</div>;
}

**9.3 Update `file:.env.example`**

Remove Better-Auth related variables, keep only fastapi-users variables (already added in Phase 1).

---

## Migration Sequence Diagram

```mermaid
sequenceDiagram
    participant FE as Next.js Frontend
    participant BA as Better-Auth (OLD)
    participant API as FastAPI Backend
    participant DB as SQLite Database
    participant FU as fastapi-users (NEW)

    Note over FE,DB: Current State (Better-Auth)
    FE->>BA: Login Request
    BA->>DB: Create Session
    DB-->>BA: Session Token
    BA-->>FE: Session Cookie
    FE->>API: API Request + Cookie
    API->>DB: Validate Session
    DB-->>API: User Data
    API-->>FE: Response

    Note over FE,DB: Migration Steps
    Note over API,FU: 1. Install fastapi-users
    Note over DB: 2. Add columns to users table
    Note over API,FU: 3. Mount auth routes
    Note over FE: 4. Remove Better-Auth
    Note over FE: 5. Create new auth client

    Note over FE,DB: New State (fastapi-users)
    FE->>API: POST /auth/jwt/login
    API->>FU: Validate Credentials
    FU->>DB: Check User
    DB-->>FU: User Data
    FU-->>API: JWT Token
    API-->>FE: {access_token, token_type}
    FE->>FE: Store JWT in localStorage
    FE->>API: API Request + Bearer Token
    API->>FU: Validate JWT
    FU-->>API: User Data
    API-->>FE: Response

File Changes Summary

File	Action	Description
file:pyproject.toml	Modify	Add fastapi-users dependencies
file:.env.example	Modify	Add AUTH_SECRET and JWT config
file:codeframe/auth/models.py	Create	SQLAlchemy User model
file:codeframe/auth/schemas.py	Create	Pydantic schemas
file:codeframe/auth/manager.py	Create	User manager and JWT backend
file:codeframe/auth/dependencies.py	Create	Auth dependencies
file:codeframe/auth/__init__.py	Create	Module exports
file:codeframe/persistence/schema_manager.py	Modify	Update users table schema
file:codeframe/persistence/migrations/migrate_to_fastapi_users.py	Create	Migration script
file:codeframe/ui/server.py	Modify	Mount auth routes
file:codeframe/ui/auth.py	Deprecate	Mark as deprecated
file:codeframe/ui/routers/*.py	Modify	Update imports
file:web-ui/package.json	Modify	Remove Better-Auth deps
file:web-ui/src/lib/auth.ts	Delete	Remove Better-Auth config
file:web-ui/src/lib/auth-client.ts	Delete	Remove Better-Auth client
file:web-ui/src/lib/db-schema.ts	Delete	Remove Drizzle schema
file:web-ui/src/app/api/auth/[...all]/route.ts	Delete	Remove Better-Auth API route
file:web-ui/src/lib/api-client.ts	Create	New auth API client
file:web-ui/src/contexts/AuthContext.tsx	Create	React auth context
file:web-ui/src/app/layout.tsx	Modify	Add AuthProvider
file:web-ui/src/components/auth/LoginForm.tsx	Modify	Use new auth client
file:web-ui/src/components/auth/SignupForm.tsx	Modify	Use new auth client
file:web-ui/src/components/auth/ProtectedRoute.tsx	Modify	Use new auth context
file:tests/auth/test_auth_endpoints.py	Create	Backend auth tests
file:tests/e2e/test_auth_flow.spec.ts	Modify	Update E2E tests

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase currently uses Better-Auth (JavaScript) with Drizzle ORM to manage authentication in a shared SQLite database. The backend Python code validates tokens by querying the `sessions` table directly. The database already has Better-Auth compatible tables (`users`, `accounts`, `sessions`, `verification`) created by `file:codeframe/persistence/schema_manager.py`. The `file:codeframe/ui/auth.py` module implements custom authentication that reads from these tables. Projects already have `user_id` foreign keys and a `project_users` table for multi-tenant access control. The `AUTH_REQUIRED` environment variable defaults to `false` for backward compatibility.

## Approach

Replace Better-Auth with fastapi-users to consolidate authentication ownership in the Python backend. The migration will preserve the existing `users` table structure but replace session-based authentication with JWT tokens. The frontend will become a stateless API client that stores JWTs and sends them via Authorization headers. The existing database schema requires minimal changes since fastapi-users can work with the current `users` table by defining a custom SQLAlchemy model. Remove all JavaScript auth dependencies (Better-Auth, Drizzle ORM) and replace with simple fetch-based API calls to FastAPI endpoints.

## Implementation Steps

### Phase 1: Backend - Install fastapi-users Dependencies

**1.1 Update `file:pyproject.toml` dependencies**

Add the following to the `dependencies` array:
```toml
"fastapi-users[sqlalchemy]==13.0.0",
"python-jose[cryptography]==3.3.0",
"passlib[bcrypt]==1.7.4",
```

Note: `aiosqlite>=0.19.0` is already present in dependencies.

Run `uv sync` to install new packages.

**1.2 Add environment variable to `file:.env.example`**

Add authentication configuration section:
```bash
# ============================================================================
# Authentication (fastapi-users)
# ============================================================================

# Secret key for JWT token signing (REQUIRED in production)
# Generate with: openssl rand -hex 32
AUTH_SECRET=your-secret-key-change-in-production

# JWT token lifetime in seconds (default: 7 days)
# JWT_LIFETIME_SECONDS=604800

# Enable authentication requirement (default: false for migration)
# Set to true in production to enforce authentication
# AUTH_REQUIRED=false
```

---

### Phase 2: Backend - Create Auth Module Structure

**2.1 Create auth module directory**

Create `file:codeframe/auth/` directory with the following files:
- `__init__.py`
- `models.py` - SQLAlchemy User model
- `schemas.py` - Pydantic schemas for API
- `manager.py` - User manager and auth backends
- `dependencies.py` - Dependency injection for routes

**2.2 Implement `file:codeframe/auth/models.py`**

Create SQLAlchemy User model that works with existing `users` table:

```python
"""SQLAlchemy User model for fastapi-users."""
from typing import Optional
from fastapi_users.db import SQLAlchemyBaseUserTable
from sqlalchemy import Integer, String, Boolean
from sqlalchemy.orm import Mapped, mapped_column, DeclarativeBase

class Base(DeclarativeBase):
    """SQLAlchemy declarative base."""
    pass

class User(SQLAlchemyBaseUserTable[int], Base):
    """User model compatible with existing users table.
    
    Uses integer primary key instead of UUID to match existing schema.
    Maps to existing 'users' table created by SchemaManager.
    """
    __tablename__ = "users"
    
    # Override id to use Integer instead of UUID
    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    
    # Required fastapi-users fields (already in schema)
    email: Mapped[str] = mapped_column(String(255), unique=True, nullable=False)
    hashed_password: Mapped[str] = mapped_column(String(1024), nullable=False)
    is_active: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
    is_superuser: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
    is_verified: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
    
    # Additional fields from existing schema
    name: Mapped[Optional[str]] = mapped_column(String(255), nullable=True)
```

**Important**: The existing `users` table doesn't have `hashed_password`, `is_active`, `is_superuser`, or `is_verified` columns. These need to be added via migration.

**2.3 Implement `file:codeframe/auth/schemas.py`**

Create Pydantic schemas for API requests/responses:

```python
"""Pydantic schemas for user operations."""
from typing import Optional
from fastapi_users import schemas

class UserRead(schemas.BaseUser[int]):
    """Schema for reading user data."""
    name: Optional[str] = None

class UserCreate(schemas.BaseUserCreate):
    """Schema for creating users."""
    name: Optional[str] = None

class UserUpdate(schemas.BaseUserUpdate):
    """Schema for updating users."""
    name: Optional[str] = None
```

**2.4 Implement `file:codeframe/auth/manager.py`**

Configure fastapi-users with JWT authentication:

```python
"""User manager and authentication backends."""
import os
from typing import Optional
from fastapi import Depends, Request
from fastapi_users import BaseUserManager, IntegerIDMixin, FastAPIUsers
from fastapi_users.authentication import (
    AuthenticationBackend,
    BearerTransport,
    JWTStrategy,
)
from fastapi_users.db import SQLAlchemyUserDatabase
from sqlalchemy.ext.asyncio import AsyncSession

from codeframe.auth.models import User
from codeframe.persistence.database import Database

# Get configuration from environment
SECRET = os.getenv("AUTH_SECRET", "CHANGE-ME-IN-PRODUCTION")
JWT_LIFETIME_SECONDS = int(os.getenv("JWT_LIFETIME_SECONDS", "604800"))  # 7 days

class UserManager(IntegerIDMixin, BaseUserManager[User, int]):
    """User manager for CodeFRAME."""
    
    reset_password_token_secret = SECRET
    verification_token_secret = SECRET

    async def on_after_register(self, user: User, request: Optional[Request] = None):
        """Called after successful registration."""
        print(f"User {user.id} ({user.email}) registered.")

    async def on_after_login(
        self, user: User, request: Optional[Request] = None, response=None
    ):
        """Called after successful login."""
        print(f"User {user.id} ({user.email}) logged in.")

async def get_async_session(request: Request) -> AsyncSession:
    """Get async database session from app state."""
    db: Database = request.app.state.db
    async_conn = await db._get_async_conn()
    # Create async session from connection
    from sqlalchemy.ext.asyncio import AsyncSession
    session = AsyncSession(bind=async_conn)
    try:
        yield session
    finally:
        await session.close()

async def get_user_db(session: AsyncSession = Depends(get_async_session)):
    """Get user database adapter."""
    yield SQLAlchemyUserDatabase(session, User)

async def get_user_manager(user_db: SQLAlchemyUserDatabase = Depends(get_user_db)):
    """Get user manager."""
    yield UserManager(user_db)

# JWT Bearer token transport
bearer_transport = BearerTransport(tokenUrl="auth/jwt/login")

def get_jwt_strategy() -> JWTStrategy:
    """JWT strategy for authentication."""
    return JWTStrategy(secret=SECRET, lifetime_seconds=JWT_LIFETIME_SECONDS)

# Authentication backend
auth_backend = AuthenticationBackend(
    name="jwt",
    transport=bearer_transport,
    get_strategy=get_jwt_strategy,
)

# FastAPIUsers instance
fastapi_users = FastAPIUsers[User, int](
    get_user_manager,
    [auth_backend],
)

# Dependencies for protected routes
current_active_user = fastapi_users.current_user(active=True)
current_superuser = fastapi_users.current_user(active=True, superuser=True)
```

**2.5 Implement `file:codeframe/auth/dependencies.py`**

Create dependency for backward compatibility with existing `file:codeframe/ui/auth.py`:

```python
"""Authentication dependencies for route handlers."""
from fastapi import Depends
from codeframe.auth.models import User
from codeframe.auth.manager import current_active_user

async def get_current_user(user: User = Depends(current_active_user)) -> User:
    """Get currently authenticated user.
    
    Replacement for codeframe.ui.auth.get_current_user.
    Returns fastapi-users User model instead of Pydantic User.
    """
    return user
```

**2.6 Create `file:codeframe/auth/__init__.py`**

Export public API:

```python
"""Authentication module for CodeFRAME."""
from codeframe.auth.models import User
from codeframe.auth.schemas import UserRead, UserCreate, UserUpdate
from codeframe.auth.manager import fastapi_users, auth_backend, current_active_user
from codeframe.auth.dependencies import get_current_user

__all__ = [
    "User",
    "UserRead",
    "UserCreate",
    "UserUpdate",
    "fastapi_users",
    "auth_backend",
    "current_active_user",
    "get_current_user",
]
```

---

### Phase 3: Backend - Database Migration

**3.1 Update `file:codeframe/persistence/schema_manager.py`**

Modify `_create_auth_tables` method to add fastapi-users required columns:

```python
def _create_auth_tables(self, cursor: sqlite3.Cursor) -> None:
    """Create authentication tables (fastapi-users compatible)."""
    cursor.execute(
        """
        CREATE TABLE IF NOT EXISTS users (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            email TEXT UNIQUE NOT NULL,
            name TEXT,
            hashed_password TEXT NOT NULL,
            is_active INTEGER DEFAULT 1,
            is_superuser INTEGER DEFAULT 0,
            is_verified INTEGER DEFAULT 0,
            email_verified INTEGER DEFAULT 0,
            image TEXT,
            created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
            updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
        )
        """
    )
```

**3.2 Create migration script `file:codeframe/persistence/migrations/migrate_to_fastapi_users.py`**

Create migration to add missing columns to existing `users` table:

```python
"""Migration: Add fastapi-users columns to users table."""
import sqlite3
import logging
from pathlib import Path

logger = logging.getLogger(__name__)

def migrate(db_path: Path) -> None:
    """Add fastapi-users required columns to users table.
    
    Adds:
    - hashed_password TEXT NOT NULL DEFAULT ''
    - is_active INTEGER DEFAULT 1
    - is_superuser INTEGER DEFAULT 0
    - is_verified INTEGER DEFAULT 0
    """
    conn = sqlite3.connect(str(db_path))
    cursor = conn.cursor()
    
    try:
        # Check if columns already exist
        cursor.execute("PRAGMA table_info(users)")
        columns = {row[1] for row in cursor.fetchall()}
        
        # Add missing columns
        if "hashed_password" not in columns:
            cursor.execute("ALTER TABLE users ADD COLUMN hashed_password TEXT NOT NULL DEFAULT ''")
            logger.info("Added hashed_password column to users table")
        
        if "is_active" not in columns:
            cursor.execute("ALTER TABLE users ADD COLUMN is_active INTEGER DEFAULT 1")
            logger.info("Added is_active column to users table")
        
        if "is_superuser" not in columns:
            cursor.execute("ALTER TABLE users ADD COLUMN is_superuser INTEGER DEFAULT 0")
            logger.info("Added is_superuser column to users table")
        
        if "is_verified" not in columns:
            cursor.execute("ALTER TABLE users ADD COLUMN is_verified INTEGER DEFAULT 0")
            logger.info("Added is_verified column to users table")
        
        conn.commit()
        logger.info("Migration completed successfully")
        
    except Exception as e:
        conn.rollback()
        logger.error(f"Migration failed: {e}")
        raise
    finally:
        conn.close()

if __name__ == "__main__":
    import sys
    if len(sys.argv) < 2:
        print("Usage: python migrate_to_fastapi_users.py <db_path>")
        sys.exit(1)
    
    db_path = Path(sys.argv[1])
    migrate(db_path)
```

Run migration: `python -m codeframe.persistence.migrations.migrate_to_fastapi_users .codeframe/state.db`

**3.3 Drop Better-Auth specific tables**

The `accounts`, `sessions`, and `verification` tables are no longer needed with JWT authentication. These can be dropped after migration is complete:

```sql
DROP TABLE IF EXISTS accounts;
DROP TABLE IF EXISTS sessions;
DROP TABLE IF EXISTS verification;
```

Add this to migration script or run manually after confirming JWT auth works.

---

### Phase 4: Backend - Mount Auth Routes

**4.1 Update `file:codeframe/ui/server.py`**

Import and mount fastapi-users routers:

```python
# Add to imports section
from codeframe.auth.manager import fastapi_users, auth_backend
from codeframe.auth.schemas import UserRead, UserCreate, UserUpdate

# Add after existing router mounts (around line 335)
# Mount authentication routes
app.include_router(
    fastapi_users.get_auth_router(auth_backend),
    prefix="/auth/jwt",
    tags=["auth"],
)

app.include_router(
    fastapi_users.get_register_router(UserRead, UserCreate),
    prefix="/auth",
    tags=["auth"],
)

app.include_router(
    fastapi_users.get_users_router(UserRead, UserUpdate),
    prefix="/users",
    tags=["users"],
)
```

This creates the following endpoints:
- `POST /auth/jwt/login` - Login with email/password, returns JWT
- `POST /auth/jwt/logout` - Logout (client-side token deletion)
- `POST /auth/register` - Register new user
- `GET /users/me` - Get current user info
- `PATCH /users/me` - Update current user

**4.2 Update existing protected routes**

Replace imports in route files (e.g., `file:codeframe/ui/routers/projects.py`):

```python
# OLD:
from codeframe.ui.auth import get_current_user, User

# NEW:
from codeframe.auth import get_current_user, User
```

The `User` type changes from Pydantic model to SQLAlchemy model, but the interface remains compatible (`user.id`, `user.email`, `user.name`).

**4.3 Deprecate `file:codeframe/ui/auth.py`**

Add deprecation notice at top of file:

```python
"""DEPRECATED: This module is deprecated in favor of codeframe.auth.

This module provided Better-Auth session validation. It has been replaced
by fastapi-users with JWT authentication in codeframe.auth.

Migration path:
- Replace: from codeframe.ui.auth import get_current_user
- With: from codeframe.auth import get_current_user

This file will be removed in a future release.
"""
```

---

### Phase 5: Frontend - Remove Better-Auth

**5.1 Remove Better-Auth dependencies from `file:web-ui/package.json`**

Remove the following packages:
- `better-auth`
- `better-sqlite3`
- `drizzle-orm`
- `@types/better-sqlite3`

Run: `npm uninstall better-auth better-sqlite3 drizzle-orm @types/better-sqlite3`

**5.2 Delete Better-Auth configuration files**

Remove the following files:
- `file:web-ui/src/lib/auth.ts`
- `file:web-ui/src/lib/auth-client.ts`
- `file:web-ui/src/lib/db-schema.ts`
- `file:web-ui/src/app/api/auth/[...all]/route.ts`

**5.3 Update `file:web-ui/.env.local` (or create if missing)**

Add FastAPI backend URL:

```bash
NEXT_PUBLIC_API_URL=http://localhost:8080
```

---

### Phase 6: Frontend - Create New Auth Client

**6.1 Create `file:web-ui/src/lib/api-client.ts`**

Create simple fetch-based API client:

```typescript
const API_URL = process.env.NEXT_PUBLIC_API_URL || 'http://localhost:8080';

export interface AuthTokens {
  access_token: string;
  token_type: string;
}

export interface User {
  id: number;
  email: string;
  name?: string;
  is_active: boolean;
  is_superuser: boolean;
  is_verified: boolean;
}

export interface LoginCredentials {
  username: string;  // fastapi-users expects 'username' field
  password: string;
}

export interface RegisterData {
  email: string;
  password: string;
  name?: string;
}

export async function login(email: string, password: string): Promise<AuthTokens> {
  const formData = new URLSearchParams();
  formData.append('username', email);
  formData.append('password', password);

  const res = await fetch(`${API_URL}/auth/jwt/login`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: formData,
  });

  if (!res.ok) {
    const error = await res.json().catch(() => ({ detail: 'Login failed' }));
    throw new Error(error.detail || 'Login failed');
  }
  
  return res.json();
}

export async function register(data: RegisterData): Promise<User> {
  const res = await fetch(`${API_URL}/auth/register`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(data),
  });

  if (!res.ok) {
    const error = await res.json().catch(() => ({ detail: 'Registration failed' }));
    throw new Error(error.detail || 'Registration failed');
  }
  
  return res.json();
}

export async function getCurrentUser(token: string): Promise<User> {
  const res = await fetch(`${API_URL}/users/me`, {
    headers: { Authorization: `Bearer ${token}` },
  });

  if (!res.ok) {
    throw new Error('Failed to get user');
  }
  
  return res.json();
}

export async function logout(token: string): Promise<void> {
  // JWT logout is client-side only (delete token)
  // Optional: call backend to invalidate token if using token blacklist
  await fetch(`${API_URL}/auth/jwt/logout`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${token}` },
  });
}
```

**6.2 Create `file:web-ui/src/contexts/AuthContext.tsx`**

Create React context for auth state management:

```typescript
'use client';

import { createContext, useContext, useEffect, useState, ReactNode } from 'react';
import { login as apiLogin, logout as apiLogout, getCurrentUser, register as apiRegister, User } from '@/lib/api-client';

interface AuthContextType {
  user: User | null;
  token: string | null;
  isLoading: boolean;
  login: (email: string, password: string) => Promise<void>;
  register: (email: string, password: string, name?: string) => Promise<void>;
  logout: () => Promise<void>;
}

const AuthContext = createContext<AuthContextType | undefined>(undefined);

export function AuthProvider({ children }: { children: ReactNode }) {
  const [user, setUser] = useState<User | null>(null);
  const [token, setToken] = useState<string | null>(null);
  const [isLoading, setIsLoading] = useState(true);

  useEffect(() => {
    // Check for existing token on mount
    const storedToken = localStorage.getItem('auth_token');
    if (storedToken) {
      getCurrentUser(storedToken)
        .then((userData) => {
          setUser(userData);
          setToken(storedToken);
        })
        .catch(() => {
          localStorage.removeItem('auth_token');
        })
        .finally(() => setIsLoading(false));
    } else {
      setIsLoading(false);
    }
  }, []);

  const login = async (email: string, password: string) => {
    const { access_token } = await apiLogin(email, password);
    localStorage.setItem('auth_token', access_token);
    setToken(access_token);
    const userData = await getCurrentUser(access_token);
    setUser(userData);
  };

  const register = async (email: string, password: string, name?: string) => {
    await apiRegister({ email, password, name });
    // Auto-login after registration
    await login(email, password);
  };

  const logout = async () => {
    if (token) {
      await apiLogout(token);
    }
    localStorage.removeItem('auth_token');
    setToken(null);
    setUser(null);
  };

  return (
    <AuthContext.Provider value={{ user, token, isLoading, login, register, logout }}>
      {children}
    </AuthContext.Provider>
  );
}

export function useAuth() {
  const context = useContext(AuthContext);
  if (context === undefined) {
    throw new Error('useAuth must be used within an AuthProvider');
  }
  return context;
}
```

**6.3 Update `file:web-ui/src/app/layout.tsx`**

Wrap app with AuthProvider:

```typescript
import { AuthProvider } from '@/contexts/AuthContext';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <AuthProvider>
          {children}
        </AuthProvider>
      </body>
    </html>
  );
}
```

**6.4 Update auth components**

Update `file:web-ui/src/components/auth/LoginForm.tsx`:

```typescript
'use client';

import { useState } from 'react';
import { useAuth } from '@/contexts/AuthContext';
import { useRouter } from 'next/navigation';

export function LoginForm() {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const [error, setError] = useState('');
  const { login } = useAuth();
  const router = useRouter();

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    setError('');
    
    try {
      await login(email, password);
      router.push('/dashboard');
    } catch (err) {
      setError(err instanceof Error ? err.message : 'Login failed');
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      {error && <div className="error">{error}</div>}
      <input
        type="email"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        placeholder="Email"
        required
      />
      <input
        type="password"
        value={password}
        onChange={(e) => setPassword(e.target.value)}
        placeholder="Password"
        required
      />
      <button type="submit">Login</button>
    </form>
  );
}
```

Update `file:web-ui/src/components/auth/SignupForm.tsx` similarly.

Update `file:web-ui/src/components/auth/ProtectedRoute.tsx`:

```typescript
'use client';

import { useAuth } from '@/contexts/AuthContext';
import { useRouter } from 'next/navigation';
import { useEffect } from 'react';

export function ProtectedRoute({ children }: { children: React.ReactNode }) {
  const { user, isLoading } = useAuth();
  const router = useRouter();

  useEffect(() => {
    if (!isLoading && !user) {
      router.push('/login');
    }
  }, [user, isLoading, router]);

  if (isLoading) {
    return <div>Loading...</div>;
  }

  if (!user) {
    return null;
  }

  return <>{children}</>;
}
```

---

### Phase 7: Update API Calls to Include Auth Token

**7.1 Create authenticated fetch wrapper in `file:web-ui/src/lib/api-client.ts`**

Add helper function for authenticated requests:

```typescript
export async function authenticatedFetch(
  url: string,
  options: RequestInit = {}
): Promise<Response> {
  const token = localStorage.getItem('auth_token');
  
  if (!token) {
    throw new Error('Not authenticated');
  }

  const headers = new Headers(options.headers);
  headers.set('Authorization', `Bearer ${token}`);

  return fetch(url, {
    ...options,
    headers,
  });
}
```

**7.2 Update existing API calls**

Update all API calls in components to use `authenticatedFetch` instead of plain `fetch`. For example, in project-related components:

```typescript
// OLD:
const res = await fetch(`${API_URL}/api/projects`);

// NEW:
import { authenticatedFetch } from '@/lib/api-client';
const res = await authenticatedFetch(`${API_URL}/api/projects`);
```

---

### Phase 8: Testing

**8.1 Create backend auth tests in `file:tests/auth/test_auth_endpoints.py`**

```python
"""Tests for fastapi-users authentication endpoints."""
import pytest
from httpx import AsyncClient
from codeframe.ui.server import app

@pytest.mark.asyncio
async def test_register_user():
    async with AsyncClient(app=app, base_url="http://test") as client:
        response = await client.post(
            "/auth/register",
            json={
                "email": "test@example.com",
                "password": "securepassword123",
                "name": "Test User",
            },
        )
        assert response.status_code == 201
        data = response.json()
        assert data["email"] == "test@example.com"
        assert data["name"] == "Test User"
        assert "id" in data
        assert "hashed_password" not in data

@pytest.mark.asyncio
async def test_login_user():
    async with AsyncClient(app=app, base_url="http://test") as client:
        # Register first
        await client.post(
            "/auth/register",
            json={"email": "login@example.com", "password": "password123"},
        )
        
        # Login
        response = await client.post(
            "/auth/jwt/login",
            data={"username": "login@example.com", "password": "password123"},
            headers={"Content-Type": "application/x-www-form-urlencoded"},
        )
        assert response.status_code == 200
        data = response.json()
        assert "access_token" in data
        assert data["token_type"] == "bearer"

@pytest.mark.asyncio
async def test_get_current_user():
    async with AsyncClient(app=app, base_url="http://test") as client:
        # Register and login
        await client.post(
            "/auth/register",
            json={"email": "me@example.com", "password": "password123"},
        )
        login_response = await client.post(
            "/auth/jwt/login",
            data={"username": "me@example.com", "password": "password123"},
            headers={"Content-Type": "application/x-www-form-urlencoded"},
        )
        token = login_response.json()["access_token"]
        
        # Get current user
        response = await client.get(
            "/users/me",
            headers={"Authorization": f"Bearer {token}"},
        )
        assert response.status_code == 200
        assert response.json()["email"] == "me@example.com"

@pytest.mark.asyncio
async def test_protected_route_without_token():
    async with AsyncClient(app=app, base_url="http://test") as client:
        response = await client.get("/users/me")
        assert response.status_code == 401
```

**8.2 Update E2E tests in `file:tests/e2e/test_auth_flow.spec.ts`**

Update Playwright tests to use new auth flow:

```typescript
import { test, expect } from '@playwright/test';

test('user can register and login', async ({ page }) => {
  // Navigate to register page
  await page.goto('http://localhost:3000/register');
  
  // Fill registration form
  await page.fill('input[type="email"]', 'test@example.com');
  await page.fill('input[type="password"]', 'securepassword123');
  await page.fill('input[name="name"]', 'Test User');
  await page.click('button[type="submit"]');
  
  // Should redirect to dashboard after auto-login
  await expect(page).toHaveURL('http://localhost:3000/dashboard');
  
  // Verify user is logged in
  await expect(page.locator('text=Test User')).toBeVisible();
});

test('protected route redirects to login', async ({ page }) => {
  // Try to access protected route without auth
  await page.goto('http://localhost:3000/dashboard');
  
  // Should redirect to login
  await expect(page).toHaveURL('http://localhost:3000/login');
});
```

---

### Phase 9: Cleanup and Documentation

**9.1 Remove deprecated files**

After confirming migration works:
- Delete `file:codeframe/ui/auth.py`
- Delete Better-Auth database tables (run migration script)

**9.2 Update documentation**

Update `file:README.md` with new authentication setup:

```markdown
## Authentication

CodeFRAME uses fastapi-users for authentication with JWT tokens.

### Environment Variables

- `AUTH_SECRET`: Secret key for JWT signing (required in production)
- `JWT_LIFETIME_SECONDS`: Token lifetime in seconds (default: 604800 = 7 days)
- `AUTH_REQUIRED`: Enable authentication requirement (default: false)

### API Endpoints

- `POST /auth/register` - Register new user
- `POST /auth/jwt/login` - Login (returns JWT token)
- `POST /auth/jwt/logout` - Logout
- `GET /users/me` - Get current user info
- `PATCH /users/me` - Update current user

### Frontend Usage

```typescript
import { useAuth } from '@/contexts/AuthContext';

function MyComponent() {
  const { user, login, logout } = useAuth();
  
  if (!user) {
    return <button onClick={() => login(email, password)}>Login</button>;
  }
  
  return <div>Welcome, {user.name}!</div>;
}
```
```

**9.3 Update `file:.env.example`**

Remove Better-Auth related variables, keep only fastapi-users variables (already added in Phase 1).

---

## Migration Sequence Diagram

```mermaid
sequenceDiagram
    participant FE as Next.js Frontend
    participant BA as Better-Auth (OLD)
    participant API as FastAPI Backend
    participant DB as SQLite Database
    participant FU as fastapi-users (NEW)

    Note over FE,DB: Current State (Better-Auth)
    FE->>BA: Login Request
    BA->>DB: Create Session
    DB-->>BA: Session Token
    BA-->>FE: Session Cookie
    FE->>API: API Request + Cookie
    API->>DB: Validate Session
    DB-->>API: User Data
    API-->>FE: Response

    Note over FE,DB: Migration Steps
    Note over API,FU: 1. Install fastapi-users
    Note over DB: 2. Add columns to users table
    Note over API,FU: 3. Mount auth routes
    Note over FE: 4. Remove Better-Auth
    Note over FE: 5. Create new auth client

    Note over FE,DB: New State (fastapi-users)
    FE->>API: POST /auth/jwt/login
    API->>FU: Validate Credentials
    FU->>DB: Check User
    DB-->>FU: User Data
    FU-->>API: JWT Token
    API-->>FE: {access_token, token_type}
    FE->>FE: Store JWT in localStorage
    FE->>API: API Request + Bearer Token
    API->>FU: Validate JWT
    FU-->>API: User Data
    API-->>FE: Response
```

## File Changes Summary

| File | Action | Description |
|------|--------|-------------|
| `file:pyproject.toml` | Modify | Add fastapi-users dependencies |
| `file:.env.example` | Modify | Add AUTH_SECRET and JWT config |
| `file:codeframe/auth/models.py` | Create | SQLAlchemy User model |
| `file:codeframe/auth/schemas.py` | Create | Pydantic schemas |
| `file:codeframe/auth/manager.py` | Create | User manager and JWT backend |
| `file:codeframe/auth/dependencies.py` | Create | Auth dependencies |
| `file:codeframe/auth/__init__.py` | Create | Module exports |
| `file:codeframe/persistence/schema_manager.py` | Modify | Update users table schema |
| `file:codeframe/persistence/migrations/migrate_to_fastapi_users.py` | Create | Migration script |
| `file:codeframe/ui/server.py` | Modify | Mount auth routes |
| `file:codeframe/ui/auth.py` | Deprecate | Mark as deprecated |
| `file:codeframe/ui/routers/*.py` | Modify | Update imports |
| `file:web-ui/package.json` | Modify | Remove Better-Auth deps |
| `file:web-ui/src/lib/auth.ts` | Delete | Remove Better-Auth config |
| `file:web-ui/src/lib/auth-client.ts` | Delete | Remove Better-Auth client |
| `file:web-ui/src/lib/db-schema.ts` | Delete | Remove Drizzle schema |
| `file:web-ui/src/app/api/auth/[...all]/route.ts` | Delete | Remove Better-Auth API route |
| `file:web-ui/src/lib/api-client.ts` | Create | New auth API client |
| `file:web-ui/src/contexts/AuthContext.tsx` | Create | React auth context |
| `file:web-ui/src/app/layout.tsx` | Modify | Add AuthProvider |
| `file:web-ui/src/components/auth/LoginForm.tsx` | Modify | Use new auth client |
| `file:web-ui/src/components/auth/SignupForm.tsx` | Modify | Use new auth client |
| `file:web-ui/src/components/auth/ProtectedRoute.tsx` | Modify | Use new auth context |
| `file:tests/auth/test_auth_endpoints.py` | Create | Backend auth tests |
| `file:tests/e2e/test_auth_flow.spec.ts` | Modify | Update E2E tests |

---

Execution Information

Branch: main
Commit: 0c96591

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Similar Issues

Possible Duplicates

• Align BetterAuth with CodeFRAME Authentication System #158

Related Issues

• [P1] Implement user authentication and authorization with Better Auth #132
• Add critical user journey E2E tests (login, project creation, start agent) #157
• BetterAuth Authentication Failure: Database Connection Timing Issue #161
• Miscellaneous backend test failures #145

🔗 Related PRs

#38 - fix(e2e): Improve Playwright test pass rate from 18% to 57% [merged]
#139 - feat: Add authentication & authorization infrastructure (Issue #132) [merged]
#155 - Reduce mocking in unit tests for better coverage [merged]
#159 - feat: Implement E2E user journey tests with auth bypass [merged]
#160 - BetterAuth Integration: Account Table Migration & E2E Test Infrastructure [closed]

👤 Suggested Assignees

• frankbria

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!