Align BetterAuth with CodeFRAME Authentication System

[frankbria]

Problem

Dual Authentication Systems: The codebase currently has two separate authentication implementations that don't integrate:

• Frontend: BetterAuth (third-party library) expecting its own table schema (user, session, account, etc.)
• Backend: CodeFRAME custom auth (uses users and sessions tables with bcrypt hashing)

Impact:

• E2E tests cannot validate the login UI flow (currently bypass with session cookies)
• Login form uses BetterAuth's signIn() but test users exist in CodeFRAME's tables
• Dual systems increase maintenance complexity and security attack surface

Root Cause

1. Schema Mismatch: BetterAuth creates user (singular), CodeFRAME uses users (plural)
2. Password Hashing: Different implementations (BetterAuth vs bcrypt)
3. Session Management: Separate cookie/token strategies

Evidence

# E2E test logs
[BetterAuthError]: Failed to initialize database adapter

// Frontend: web-ui/src/lib/auth.ts
export const auth = betterAuth({
  database: {
    url: `file:${resolve(process.cwd(), "../.codeframe/state.db")}`,
    type: "sqlite",
  },
  // ...
});

# Backend: tests/e2e/seed-test-data.py
cursor.execute("""
    INSERT OR REPLACE INTO users (id, email, password_hash, ...)
    VALUES (?, ?, ?, ...)
""", (1, "test@example.com", bcrypt_hash, ...))

Solution Options

Option A: Custom BetterAuth Adapter (Recommended)

Effort: ~4 hours
Approach: Create a custom database adapter that makes BetterAuth use CodeFRAME's existing tables

Pros:

• Keeps BetterAuth features (OAuth, 2FA, etc.)
• Single source of truth for user data
• Minimal frontend changes

Cons:

• Requires understanding BetterAuth internals
• Adapter maintenance burden

Option B: Replace BetterAuth with CodeFRAME Auth

Effort: ~6 hours
Approach: Remove BetterAuth, use CodeFRAME's auth API directly in LoginForm.tsx

Pros:

• Complete control over auth flow
• Simpler architecture
• No third-party dependency

Cons:

• Lose BetterAuth features
• More frontend API integration code
• Need to implement OAuth manually if needed later

Option C: Migrate CodeFRAME to BetterAuth Schema

Effort: ~8 hours
Approach: Change backend to use BetterAuth's schema, migrate existing users

Pros:

• Standardized auth solution
• Full BetterAuth feature set
• Good documentation

Cons:

• Breaking change for existing deployments
• Migration complexity
• Backend tightly coupled to frontend choice

Acceptance Criteria

• Single authentication system (frontend + backend aligned)
• E2E tests validate login flow via UI (no session bypass)
• Existing test user (test@example.com) can login through the UI
• tests/e2e/auth-bypass.ts deleted (no longer needed)
• All E2E tests pass using real login flow
• No [BetterAuthError] in logs

Current Workaround

E2E tests use setTestUserSession() to bypass login by setting session cookies directly. This works for testing post-login flows but doesn't validate the login UI.

Migration path documented in test files:

// Replace setTestUserSession() with loginUser() after auth alignment
test.beforeEach(async ({ page }) => {
  await loginUser(page); // Will work once auth is fixed
});

Related Files

• web-ui/src/lib/auth.ts - BetterAuth configuration
• web-ui/src/components/auth/LoginForm.tsx - Login UI (uses BetterAuth)
• codeframe/persistence/database.py - CodeFRAME users/sessions tables
• tests/e2e/auth-bypass.ts - Temporary bypass (delete after fix)
• tests/e2e/test_auth_flow.spec.ts - Auth tests (1/4 passing)

Priority

P2 - High: Blocks full E2E test coverage and creates security/maintenance debt, but workaround exists for core user journey tests.

[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

• [P1] Implement user authentication and authorization with Better Auth #132

Related Issues

• Update E2E test expectations to match current Dashboard design #88
• Add data-testid attributes to Dashboard tabs for E2E testing #84
• [P2] Replace mocked unit tests with real integration tests #113
• Consolidate Task type definitions across codebase #53

🔗 Related PRs

#35 - fix: Resolve E2E test timeout failures in GitHub Actions [merged]
#38 - fix(e2e): Improve Playwright test pass rate from 18% to 57% [merged]
#90 - fix(e2e): E2E test database isolation - Fixes #89 [merged]
#155 - Reduce mocking in unit tests for better coverage [merged]

👤 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!

[traycerai]

Plan

Observations

The codebase has two separate authentication systems: BetterAuth (frontend, expecting user/session tables) and CodeFRAME custom auth (backend, using users/sessions tables with bcrypt). E2E tests bypass login UI by directly setting session cookies (E2E_TEST_SESSION_TOKEN). The schema mismatch prevents BetterAuth from working with CodeFRAME's existing tables. BetterAuth supports schema customization via usePlural option and custom adapters, making Option A (Custom Adapter) the most viable solution.

Approach

Implement Option A: Custom BetterAuth Adapter to align BetterAuth with CodeFRAME's existing authentication tables. This approach leverages BetterAuth's built-in schema customization (usePlural: true) to use plural table names (users, sessions) and ensures password compatibility by configuring BetterAuth to use bcrypt hashing. This maintains BetterAuth's features (OAuth, 2FA extensibility) while using CodeFRAME's single source of truth for user data. E2E tests will then use the real login flow instead of session bypasses.

Implementation Steps

1. Configure BetterAuth to Use Plural Table Names

File: file:web-ui/src/lib/auth.ts

Modify the BetterAuth configuration to use CodeFRAME's existing plural table names:

• Add usePlural: true to the database adapter configuration
• This tells BetterAuth to use users instead of user and sessions instead of session
• Verify the database path points to the same SQLite file used by the backend (../.codeframe/state.db)

2. Verify Password Hashing Compatibility

Files: file:web-ui/src/lib/auth.ts, file:codeframe/ui/auth.py

Ensure password hashing is compatible between systems:

• BetterAuth uses bcrypt by default for password hashing (same as CodeFRAME backend)
• Verify that the emailAndPassword configuration in BetterAuth doesn't override the default bcrypt implementation
• Test that passwords hashed by BetterAuth can be verified by CodeFRAME's backend auth system (file:codeframe/ui/auth.py uses bcrypt)

3. Update Test User Seeding for BetterAuth Compatibility

File: file:tests/e2e/seed-test-data.py

Modify the test user seeding to ensure compatibility with BetterAuth's expected schema:

• Keep the existing users table structure (already compatible with plural naming)
• Ensure the password_hash field uses bcrypt format (already implemented: $2b$12$...)
• Update session token generation to match BetterAuth's session token format if needed
• Verify that the sessions table structure matches BetterAuth's expectations (token, user_id, expires_at, created_at)

4. Create Login Helper for E2E Tests

File: file:tests/e2e/test-utils.ts

Add a new helper function to perform real login via the UI:

• Create loginUser(page: Page, email?: string, password?: string) function
• Default credentials: test@example.com / testpassword123 (from environment variables)
• Navigate to /login page
• Fill in email and password fields
• Submit the form
• Wait for redirect to dashboard
• Verify successful authentication by checking for session cookie or user indicator

5. Update E2E Test Setup to Use Real Login

File: file:tests/e2e/test_dashboard.spec.ts

Replace session cookie injection with real login flow:

• Remove the addCookies() call that sets better-auth.session_token directly
• Replace with await loginUser(page) call in beforeEach hook
• This validates the entire login flow including BetterAuth API endpoints
• Keep fallback to session token for debugging if login fails

6. Verify BetterAuth API Routes

File: file:web-ui/src/app/api/auth/[...all]/route.ts

Confirm the BetterAuth API route handler is properly configured:

• Verify it exports both GET and POST handlers via toNextJsHandler(auth)
• This handles /api/auth/sign-in, /api/auth/sign-up, /api/auth/sign-out, etc.
• Test that these endpoints work with the plural table names configuration

7. Update Backend Auth to Support BetterAuth Sessions

File: file:codeframe/ui/auth.py

Ensure the backend auth dependency can validate BetterAuth-created sessions:

• The existing get_current_user() function already queries the sessions table with token field
• Verify that BetterAuth session tokens are stored in the same format
• Test that sessions created by BetterAuth can be validated by the backend
• Ensure expires_at timestamp format is compatible (ISO 8601)

8. Remove Auth Bypass Mechanism

Files: file:tests/e2e/global-setup.ts, file:tests/e2e/test_dashboard.spec.ts

Clean up temporary auth bypass code:

• Remove loadTestUserSession() function from global-setup.ts
• Remove session token file creation from seed-test-data.py (lines 92-96)
• Remove E2E_TEST_SESSION_TOKEN environment variable usage
• Remove cookie injection code from test files
• Update all E2E tests to use loginUser() helper instead

9. Test Authentication Flow End-to-End

New File: file:tests/e2e/test_auth_flow.spec.ts

Create comprehensive authentication tests:

• Test successful login with valid credentials
• Test login failure with invalid credentials
• Test logout functionality
• Test session persistence across page reloads
• Test protected route access (redirect to login when not authenticated)
• Test authenticated route access (dashboard loads successfully)

10. Update Documentation

Files: file:tests/e2e/README.md, file:TESTING.md

Document the unified authentication system:

• Explain that BetterAuth now uses CodeFRAME's users and sessions tables
• Document test user credentials (test@example.com / testpassword123)
• Remove references to auth bypass mechanism
• Add troubleshooting section for authentication issues

Architecture Diagram

sequenceDiagram
    participant UI as LoginForm (React)
    participant BA as BetterAuth API
    participant DB as SQLite (state.db)
    participant BE as Backend API
    
    Note over UI,DB: Frontend Authentication Flow
    UI->>BA: POST /api/auth/sign-in<br/>{email, password}
    BA->>DB: Query users table<br/>(plural naming)
    DB-->>BA: User record with bcrypt hash
    BA->>BA: Verify password (bcrypt)
    BA->>DB: Insert session token<br/>into sessions table
    DB-->>BA: Session created
    BA-->>UI: Session cookie set
    
    Note over UI,BE: Backend API Access
    UI->>BE: GET /api/projects<br/>Authorization: Bearer {token}
    BE->>DB: Query sessions table<br/>JOIN users
    DB-->>BE: User + session data
    BE->>BE: Validate expiry
    BE-->>UI: Protected resource
    
    Note over BA,BE: Single Source of Truth
    Note over DB: users table (plural)<br/>sessions table (plural)<br/>bcrypt password hashing

Loading

Configuration Summary

Component	Table Names	Password Hash	Session Token
BetterAuth	users, sessions (via usePlural: true)	bcrypt (default)	Stored in sessions.token
CodeFRAME Backend	users, sessions	bcrypt	Validated from sessions.token
E2E Tests	Same tables	Same bcrypt hash	Created via real login flow

Acceptance Criteria Validation

• ✅ Single authentication system: BetterAuth configured to use CodeFRAME's tables
• ✅ E2E tests validate login flow: New loginUser() helper performs real UI login
• ✅ Test user can login: Existing test@example.com works with BetterAuth
• ✅ Auth bypass deleted: Session token injection removed from tests
• ✅ All E2E tests pass: Tests use real authentication flow
• ✅ No BetterAuthError: Plural table names resolve schema mismatch

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has two separate authentication systems: **BetterAuth** (frontend, expecting `user`/`session` tables) and **CodeFRAME custom auth** (backend, using `users`/`sessions` tables with bcrypt). E2E tests bypass login UI by directly setting session cookies (`E2E_TEST_SESSION_TOKEN`). The schema mismatch prevents BetterAuth from working with CodeFRAME's existing tables. BetterAuth supports schema customization via `usePlural` option and custom adapters, making Option A (Custom Adapter) the most viable solution.

## Approach

Implement **Option A: Custom BetterAuth Adapter** to align BetterAuth with CodeFRAME's existing authentication tables. This approach leverages BetterAuth's built-in schema customization (`usePlural: true`) to use plural table names (`users`, `sessions`) and ensures password compatibility by configuring BetterAuth to use bcrypt hashing. This maintains BetterAuth's features (OAuth, 2FA extensibility) while using CodeFRAME's single source of truth for user data. E2E tests will then use the real login flow instead of session bypasses.

## Implementation Steps

### 1. Configure BetterAuth to Use Plural Table Names

**File:** `file:web-ui/src/lib/auth.ts`

Modify the BetterAuth configuration to use CodeFRAME's existing plural table names:

- Add `usePlural: true` to the database adapter configuration
- This tells BetterAuth to use `users` instead of `user` and `sessions` instead of `session`
- Verify the database path points to the same SQLite file used by the backend (`../.codeframe/state.db`)

### 2. Verify Password Hashing Compatibility

**Files:** `file:web-ui/src/lib/auth.ts`, `file:codeframe/ui/auth.py`

Ensure password hashing is compatible between systems:

- BetterAuth uses bcrypt by default for password hashing (same as CodeFRAME backend)
- Verify that the `emailAndPassword` configuration in BetterAuth doesn't override the default bcrypt implementation
- Test that passwords hashed by BetterAuth can be verified by CodeFRAME's backend auth system (file:codeframe/ui/auth.py uses bcrypt)

### 3. Update Test User Seeding for BetterAuth Compatibility

**File:** `file:tests/e2e/seed-test-data.py`

Modify the test user seeding to ensure compatibility with BetterAuth's expected schema:

- Keep the existing `users` table structure (already compatible with plural naming)
- Ensure the `password_hash` field uses bcrypt format (already implemented: `$2b$12$...`)
- Update session token generation to match BetterAuth's session token format if needed
- Verify that the `sessions` table structure matches BetterAuth's expectations (token, user_id, expires_at, created_at)

### 4. Create Login Helper for E2E Tests

**File:** `file:tests/e2e/test-utils.ts`

Add a new helper function to perform real login via the UI:

- Create `loginUser(page: Page, email?: string, password?: string)` function
- Default credentials: `test@example.com` / `testpassword123` (from environment variables)
- Navigate to `/login` page
- Fill in email and password fields
- Submit the form
- Wait for redirect to dashboard
- Verify successful authentication by checking for session cookie or user indicator

### 5. Update E2E Test Setup to Use Real Login

**File:** `file:tests/e2e/test_dashboard.spec.ts`

Replace session cookie injection with real login flow:

- Remove the `addCookies()` call that sets `better-auth.session_token` directly
- Replace with `await loginUser(page)` call in `beforeEach` hook
- This validates the entire login flow including BetterAuth API endpoints
- Keep fallback to session token for debugging if login fails

### 6. Verify BetterAuth API Routes

**File:** `file:web-ui/src/app/api/auth/[...all]/route.ts`

Confirm the BetterAuth API route handler is properly configured:

- Verify it exports both GET and POST handlers via `toNextJsHandler(auth)`
- This handles `/api/auth/sign-in`, `/api/auth/sign-up`, `/api/auth/sign-out`, etc.
- Test that these endpoints work with the plural table names configuration

### 7. Update Backend Auth to Support BetterAuth Sessions

**File:** `file:codeframe/ui/auth.py`

Ensure the backend auth dependency can validate BetterAuth-created sessions:

- The existing `get_current_user()` function already queries the `sessions` table with `token` field
- Verify that BetterAuth session tokens are stored in the same format
- Test that sessions created by BetterAuth can be validated by the backend
- Ensure `expires_at` timestamp format is compatible (ISO 8601)

### 8. Remove Auth Bypass Mechanism

**Files:** `file:tests/e2e/global-setup.ts`, `file:tests/e2e/test_dashboard.spec.ts`

Clean up temporary auth bypass code:

- Remove `loadTestUserSession()` function from global-setup.ts
- Remove session token file creation from seed-test-data.py (lines 92-96)
- Remove `E2E_TEST_SESSION_TOKEN` environment variable usage
- Remove cookie injection code from test files
- Update all E2E tests to use `loginUser()` helper instead

### 9. Test Authentication Flow End-to-End

**New File:** `file:tests/e2e/test_auth_flow.spec.ts`

Create comprehensive authentication tests:

- Test successful login with valid credentials
- Test login failure with invalid credentials
- Test logout functionality
- Test session persistence across page reloads
- Test protected route access (redirect to login when not authenticated)
- Test authenticated route access (dashboard loads successfully)

### 10. Update Documentation

**Files:** `file:tests/e2e/README.md`, `file:TESTING.md`

Document the unified authentication system:

- Explain that BetterAuth now uses CodeFRAME's `users` and `sessions` tables
- Document test user credentials (`test@example.com` / `testpassword123`)
- Remove references to auth bypass mechanism
- Add troubleshooting section for authentication issues

## Architecture Diagram

```mermaid
sequenceDiagram
    participant UI as LoginForm (React)
    participant BA as BetterAuth API
    participant DB as SQLite (state.db)
    participant BE as Backend API
    
    Note over UI,DB: Frontend Authentication Flow
    UI->>BA: POST /api/auth/sign-in<br/>{email, password}
    BA->>DB: Query users table<br/>(plural naming)
    DB-->>BA: User record with bcrypt hash
    BA->>BA: Verify password (bcrypt)
    BA->>DB: Insert session token<br/>into sessions table
    DB-->>BA: Session created
    BA-->>UI: Session cookie set
    
    Note over UI,BE: Backend API Access
    UI->>BE: GET /api/projects<br/>Authorization: Bearer {token}
    BE->>DB: Query sessions table<br/>JOIN users
    DB-->>BE: User + session data
    BE->>BE: Validate expiry
    BE-->>UI: Protected resource
    
    Note over BA,BE: Single Source of Truth
    Note over DB: users table (plural)<br/>sessions table (plural)<br/>bcrypt password hashing
```

## Configuration Summary

| Component | Table Names | Password Hash | Session Token |
|-----------|-------------|---------------|---------------|
| **BetterAuth** | `users`, `sessions` (via `usePlural: true`) | bcrypt (default) | Stored in `sessions.token` |
| **CodeFRAME Backend** | `users`, `sessions` | bcrypt | Validated from `sessions.token` |
| **E2E Tests** | Same tables | Same bcrypt hash | Created via real login flow |

## Acceptance Criteria Validation

- ✅ Single authentication system: BetterAuth configured to use CodeFRAME's tables
- ✅ E2E tests validate login flow: New `loginUser()` helper performs real UI login
- ✅ Test user can login: Existing `test@example.com` works with BetterAuth
- ✅ Auth bypass deleted: Session token injection removed from tests
- ✅ All E2E tests pass: Tests use real authentication flow
- ✅ No BetterAuthError: Plural table names resolve schema mismatch

---

Execution Information

Branch: main
Commit: 52e78e0

---

💡 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.