Enforce authentication across the v2 API (routers, WS/SSE, and web-UI login)

[frankbria]

Important

Refreshed 2026-06-04 (post #609) — the lists below are stale (projects_v2.py is gone; 6 routers added; now 22 REST + 2 WS routers; frontend has no login flow). See the refreshed assessment & sub-task breakdown in the comments for the current plan of record.

---

Summary

The v2 API routers are missing authentication enforcement despite documentation stating "All endpoints require authentication."

Current State

• 18 v2 routers have no auth dependencies
• Only api_key_router.py (for managing API keys) uses require_auth
• Documentation in server.py line 261 claims auth is required
• Frontend uses withCredentials: true but doesn't send API keys

Routers Requiring Auth

All files in codeframe/ui/routers/*_v2.py:

• batches_v2.py
• blockers_v2.py
• checkpoints_v2.py
• diagnose_v2.py
• discovery_v2.py
• environment_v2.py
• events_v2.py
• gates_v2.py
• git_v2.py
• pr_v2.py
• prd_v2.py
• projects_v2.py
• review_v2.py
• schedule_v2.py
• streaming_v2.py
• tasks_v2.py
• templates_v2.py
• workspace_v2.py

Implementation

1. Add require_auth dependency to all v2 router endpoints
2. Update frontend to send API key or session token
3. Consider read-only endpoints that might allow optional auth
4. Update tests to include auth headers

References

• Discovered during PR feat: Phase 3 Workspace View with activity feed #335 code review
• Auth dependencies defined in codeframe/auth/dependencies.py

[traycerai]

Plan

Observations

The v2 API routers currently lack authentication enforcement despite documentation claiming "All endpoints require authentication." Out of 17 v2 routers, only file:codeframe/ui/routers/streaming_v2.py currently uses authentication (get_current_user). The authentication infrastructure is already in place via file:codeframe/auth/dependencies.py with dual auth support (JWT tokens and API keys). The frontend uses JWT tokens stored in localStorage but doesn't send them to v2 endpoints. Tests for v2 routers don't include authentication headers.

Approach

Add the require_auth dependency to all unprotected v2 router endpoints to enforce dual authentication (JWT or API key). Use scope-based permissions where appropriate: require_scope("read") for GET endpoints and require_scope("write") for POST/PUT/PATCH/DELETE endpoints. Update frontend API client to include authentication headers for v2 endpoints. Update existing tests to include authentication headers. This approach maintains backward compatibility with existing JWT authentication while enabling API key access for programmatic clients.

Implementation Steps

1. Backend: Add Authentication to V2 Routers

Add authentication dependencies to all endpoints in the following 16 router files:

Read-Only Endpoints (use require_scope("read")):

• GET endpoints in all routers

Write Endpoints (use require_scope("write")):

• POST, PUT, PATCH, DELETE endpoints in all routers

Router Files to Update:

1. file:codeframe/ui/routers/batches_v2.py

   • Import: from codeframe.auth.dependencies import require_scope
   • Add auth: dict = Depends(require_scope("read")) to GET endpoints
   • Add auth: dict = Depends(require_scope("write")) to POST/DELETE endpoints

2. file:codeframe/ui/routers/blockers_v2.py

   • Import: from codeframe.auth.dependencies import require_scope
   • GET /api/v2/blockers and /api/v2/blockers/{id}: add auth: dict = Depends(require_scope("read"))
   • POST /api/v2/blockers, /api/v2/blockers/{id}/answer, /api/v2/blockers/{id}/resolve: add auth: dict = Depends(require_scope("write"))

3. file:codeframe/ui/routers/checkpoints_v2.py

   • Import: from codeframe.auth.dependencies import require_scope
   • GET endpoints: require_scope("read")
   • POST/DELETE endpoints: require_scope("write")

4. file:codeframe/ui/routers/diagnose_v2.py

   • Import: from codeframe.auth.dependencies import require_scope
   • All endpoints: require_scope("read") (diagnostic endpoints are read-only)

5. file:codeframe/ui/routers/discovery_v2.py

   • Import: from codeframe.auth.dependencies import require_scope
   • GET endpoints: require_scope("read")
   • POST endpoints: require_scope("write")

6. file:codeframe/ui/routers/environment_v2.py

   • Import: from codeframe.auth.dependencies import require_scope
   • GET endpoints: require_scope("read")
   • POST/PUT/PATCH endpoints: require_scope("write")

7. file:codeframe/ui/routers/gates_v2.py

   • Import: from codeframe.auth.dependencies import require_scope
   • GET endpoints: require_scope("read")
   • POST endpoints: require_scope("write")

8. file:codeframe/ui/routers/git_v2.py

   • Import: from codeframe.auth.dependencies import require_scope
   • GET endpoints: require_scope("read")
   • POST endpoints (commit, push, etc.): require_scope("write")

9. file:codeframe/ui/routers/pr_v2.py

   • Import: from codeframe.auth.dependencies import require_scope
   • GET endpoints: require_scope("read")
   • POST endpoints: require_scope("write")

10. file:codeframe/ui/routers/prd_v2.py

    • Import: from codeframe.auth.dependencies import require_scope
    • GET endpoints: require_scope("read")
    • POST/DELETE endpoints: require_scope("write")

11. file:codeframe/ui/routers/projects_v2.py

    • Import: from codeframe.auth.dependencies import require_scope
    • GET /api/v2/projects/status, /api/v2/projects/progress, /api/v2/projects/task-counts, /api/v2/projects/session: add auth: dict = Depends(require_scope("read"))
    • DELETE /api/v2/projects/session: add auth: dict = Depends(require_scope("write"))

12. file:codeframe/ui/routers/review_v2.py

    • Import: from codeframe.auth.dependencies import require_scope
    • GET endpoints: require_scope("read")
    • POST endpoints: require_scope("write")

13. file:codeframe/ui/routers/schedule_v2.py

    • Import: from codeframe.auth.dependencies import require_scope
    • All endpoints: require_scope("read") (schedule analysis is read-only)

14. file:codeframe/ui/routers/tasks_v2.py

    • Import: from codeframe.auth.dependencies import require_scope
    • GET /api/v2/tasks, /api/v2/tasks/{id}, /api/v2/tasks/assignment-status, /api/v2/tasks/{id}/run, /api/v2/tasks/{id}/stream: add auth: dict = Depends(require_scope("read"))
    • POST /api/v2/tasks/approve, /api/v2/tasks/execute, /api/v2/tasks/{id}/start, /api/v2/tasks/{id}/resume: add auth: dict = Depends(require_scope("write"))
    • PATCH /api/v2/tasks/{id}: add auth: dict = Depends(require_scope("write"))
    • DELETE /api/v2/tasks/{id}: add auth: dict = Depends(require_scope("write"))
    • POST /api/v2/tasks/{id}/stop: add auth: dict = Depends(require_scope("write"))

15. file:codeframe/ui/routers/templates_v2.py

    • Import: from codeframe.auth.dependencies import require_scope
    • GET endpoints: require_scope("read")
    • POST endpoints: require_scope("write")

16. file:codeframe/ui/routers/workspace_v2.py

    • Import: from codeframe.auth.dependencies import require_scope
    • GET /api/v2/workspaces/current, /api/v2/workspaces/exists: add auth: dict = Depends(require_scope("read"))
    • POST /api/v2/workspaces: add auth: dict = Depends(require_scope("write"))
    • PATCH /api/v2/workspaces/current: add auth: dict = Depends(require_scope("write"))

Pattern for Each Endpoint:

# Before
async def endpoint_name(
    request: Request,
    workspace: Workspace = Depends(get_v2_workspace),
) -> ResponseModel:

# After (for read endpoints)
async def endpoint_name(
    request: Request,
    workspace: Workspace = Depends(get_v2_workspace),
    auth: dict = Depends(require_scope("read")),
) -> ResponseModel:

# After (for write endpoints)
async def endpoint_name(
    request: Request,
    workspace: Workspace = Depends(get_v2_workspace),
    auth: dict = Depends(require_scope("write")),
) -> ResponseModel:

2. Frontend: Update API Client

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

The authFetch helper already includes JWT tokens in the Authorization header. Ensure all v2 API calls use this helper:

• Verify all API calls to /api/v2/* endpoints use authFetch or authenticatedFetch
• If any calls use plain fetch, replace with authFetch

Example pattern:

// Ensure v2 endpoints use authFetch
const response = await authFetch<TaskListResponse>(
  `${API_URL}/api/v2/tasks`,
  { method: 'GET' }
);

3. Tests: Update Test Fixtures and Cases

file:tests/ui/test_v2_routers_integration.py

Add authentication to all test requests:

1. Add JWT token creation helper (similar to file:tests/auth/test_api_key_endpoints.py):

   def create_jwt_token(user_id: int = 1) -> str:
       """Create a JWT token for testing."""
       from codeframe.auth.manager import JWT_ALGORITHM, JWT_AUDIENCE, JWT_LIFETIME_SECONDS
       # ... implementation from test_api_key_endpoints.py

2. Update test fixtures to create test users in database:

   @pytest.fixture
   def test_workspace():
       # ... existing workspace setup
       # Add user creation
       db = workspace.db
       db.conn.execute("""
           INSERT OR REPLACE INTO users (
               id, email, name, hashed_password,
               is_active, is_superuser, is_verified, email_verified
           )
           VALUES (1, 'test@example.com', 'Test User', '!DISABLED!', 1, 0, 1, 1)
       """)
       db.conn.commit()

3. Update all test requests to include auth headers:

   # Before
   response = test_client.get("/api/v2/blockers")
   
   # After
   token = create_jwt_token(user_id=1)
   response = test_client.get(
       "/api/v2/blockers",
       headers={"Authorization": f"Bearer {token}"}
   )

4. Add new test cases for authentication:

   • Test that endpoints return 401 without authentication
   • Test that API key authentication works
   • Test that JWT authentication works
   • Test scope-based permissions (read vs write)

Example new test class:

class TestV2Authentication:
    """Tests for v2 router authentication."""
    
    def test_endpoint_requires_auth(self, test_client):
        """V2 endpoints return 401 without authentication."""
        response = test_client.get("/api/v2/tasks")
        assert response.status_code == 401
    
    def test_endpoint_accepts_jwt(self, test_client):
        """V2 endpoints accept JWT authentication."""
        token = create_jwt_token(user_id=1)
        response = test_client.get(
            "/api/v2/tasks",
            headers={"Authorization": f"Bearer {token}"}
        )
        assert response.status_code == 200
    
    def test_endpoint_accepts_api_key(self, test_client, db):
        """V2 endpoints accept API key authentication."""
        full_key, key_hash, prefix = generate_api_key()
        db.api_keys.create(
            user_id=1,
            name="Test Key",
            key_hash=key_hash,
            prefix=prefix,
            scopes=["read", "write"],
            expires_at=None,
        )
        response = test_client.get(
            "/api/v2/tasks",
            headers={"X-API-Key": full_key}
        )
        assert response.status_code == 200
    
    def test_read_endpoint_requires_read_scope(self, test_client, db):
        """Read endpoints require read scope."""
        # Create API key with write-only scope
        full_key, key_hash, prefix = generate_api_key()
        db.api_keys.create(
            user_id=1,
            name="Write Only",
            key_hash=key_hash,
            prefix=prefix,
            scopes=["write"],  # write implies read
            expires_at=None,
        )
        response = test_client.get(
            "/api/v2/tasks",
            headers={"X-API-Key": full_key}
        )
        assert response.status_code == 200
    
    def test_write_endpoint_requires_write_scope(self, test_client, db):
        """Write endpoints require write scope."""
        # Create API key with read-only scope
        full_key, key_hash, prefix = generate_api_key()
        db.api_keys.create(
            user_id=1,
            name="Read Only",
            key_hash=key_hash,
            prefix=prefix,
            scopes=["read"],
            expires_at=None,
        )
        response = test_client.post(
            "/api/v2/blockers",
            json={"question": "Test"},
            headers={"X-API-Key": full_key}
        )
        assert response.status_code == 403  # Forbidden

4. Documentation Updates

file:codeframe/ui/server.py (lines 343-348)

The documentation already states authentication is required. Verify it mentions both authentication methods:

## Authentication

All endpoints require authentication. The API supports two authentication methods:

1. **API Key** - Include `X-API-Key` header with your API key
2. **Session Token** - Use JWT token from login endpoint in `Authorization: Bearer <token>` header

API keys support scope-based permissions:
- `read`: Read-only access to all GET endpoints
- `write`: Read and write access (includes read permissions)
- `admin`: Full access including administrative operations

5. Migration Considerations

Backward Compatibility:

• Existing JWT-based authentication continues to work unchanged
• JWT tokens automatically get all scopes (read, write, admin) for backward compatibility
• No breaking changes for existing web UI users

API Key Adoption:

• Users can create API keys via POST /api/auth/api-keys (requires JWT)
• API keys enable programmatic access without session management
• Scope-based permissions allow fine-grained access control

Testing Strategy:

1. Update all existing v2 router tests to include authentication
2. Add new authentication-specific test cases
3. Verify both JWT and API key authentication work
4. Test scope-based permission enforcement
5. Ensure 401 responses for unauthenticated requests
6. Ensure 403 responses for insufficient permissions

Sequence Diagram

sequenceDiagram
    participant Client
    participant Router as V2 Router
    participant Auth as require_scope()
    participant APIKey as get_api_key_auth()
    participant JWT as get_current_user_optional()
    participant DB as Database
    participant Core as Core Module

    Client->>Router: GET /api/v2/tasks<br/>(with X-API-Key or Bearer token)
    Router->>Auth: Check authentication
    
    alt API Key provided
        Auth->>APIKey: Extract & verify API key
        APIKey->>DB: Lookup key by prefix
        DB-->>APIKey: Return key record
        APIKey->>APIKey: Verify hash
        APIKey-->>Auth: Return auth dict with scopes
    else JWT Token provided
        Auth->>JWT: Verify JWT token
        JWT->>DB: Lookup user by ID
        DB-->>JWT: Return user
        JWT-->>Auth: Return user with all scopes
    else No auth provided
        Auth-->>Router: Raise 401 Unauthorized
        Router-->>Client: 401 Response
    end
    
    Auth->>Auth: Check scope (read/write)
    
    alt Insufficient scope
        Auth-->>Router: Raise 403 Forbidden
        Router-->>Client: 403 Response
    else Scope OK
        Auth-->>Router: Return auth dict
        Router->>Core: Call core module function
        Core-->>Router: Return data
        Router-->>Client: 200 Response with data
    end

Loading

Summary

This implementation adds authentication to 16 unprotected v2 routers using the existing dual authentication system (JWT + API keys) with scope-based permissions. The changes are minimal and follow established patterns from file:codeframe/auth/api_key_router.py. Frontend changes are minimal since the API client already sends JWT tokens. Tests require updates to include authentication headers and verify permission enforcement. The implementation maintains backward compatibility while enabling secure programmatic access via API keys.

Import In IDE

🤖 Prompt for AI Agents

## Observations

The v2 API routers currently lack authentication enforcement despite documentation claiming "All endpoints require authentication." Out of 17 v2 routers, only `file:codeframe/ui/routers/streaming_v2.py` currently uses authentication (`get_current_user`). The authentication infrastructure is already in place via `file:codeframe/auth/dependencies.py` with dual auth support (JWT tokens and API keys). The frontend uses JWT tokens stored in localStorage but doesn't send them to v2 endpoints. Tests for v2 routers don't include authentication headers.

## Approach

Add the `require_auth` dependency to all unprotected v2 router endpoints to enforce dual authentication (JWT or API key). Use scope-based permissions where appropriate: `require_scope("read")` for GET endpoints and `require_scope("write")` for POST/PUT/PATCH/DELETE endpoints. Update frontend API client to include authentication headers for v2 endpoints. Update existing tests to include authentication headers. This approach maintains backward compatibility with existing JWT authentication while enabling API key access for programmatic clients.

## Implementation Steps

### 1. Backend: Add Authentication to V2 Routers

Add authentication dependencies to all endpoints in the following 16 router files:

**Read-Only Endpoints (use `require_scope("read")`):**
- GET endpoints in all routers

**Write Endpoints (use `require_scope("write")`):**
- POST, PUT, PATCH, DELETE endpoints in all routers

**Router Files to Update:**

1. **file:codeframe/ui/routers/batches_v2.py**
   - Import: `from codeframe.auth.dependencies import require_scope`
   - Add `auth: dict = Depends(require_scope("read"))` to GET endpoints
   - Add `auth: dict = Depends(require_scope("write"))` to POST/DELETE endpoints

2. **file:codeframe/ui/routers/blockers_v2.py**
   - Import: `from codeframe.auth.dependencies import require_scope`
   - GET `/api/v2/blockers` and `/api/v2/blockers/{id}`: add `auth: dict = Depends(require_scope("read"))`
   - POST `/api/v2/blockers`, `/api/v2/blockers/{id}/answer`, `/api/v2/blockers/{id}/resolve`: add `auth: dict = Depends(require_scope("write"))`

3. **file:codeframe/ui/routers/checkpoints_v2.py**
   - Import: `from codeframe.auth.dependencies import require_scope`
   - GET endpoints: `require_scope("read")`
   - POST/DELETE endpoints: `require_scope("write")`

4. **file:codeframe/ui/routers/diagnose_v2.py**
   - Import: `from codeframe.auth.dependencies import require_scope`
   - All endpoints: `require_scope("read")` (diagnostic endpoints are read-only)

5. **file:codeframe/ui/routers/discovery_v2.py**
   - Import: `from codeframe.auth.dependencies import require_scope`
   - GET endpoints: `require_scope("read")`
   - POST endpoints: `require_scope("write")`

6. **file:codeframe/ui/routers/environment_v2.py**
   - Import: `from codeframe.auth.dependencies import require_scope`
   - GET endpoints: `require_scope("read")`
   - POST/PUT/PATCH endpoints: `require_scope("write")`

7. **file:codeframe/ui/routers/gates_v2.py**
   - Import: `from codeframe.auth.dependencies import require_scope`
   - GET endpoints: `require_scope("read")`
   - POST endpoints: `require_scope("write")`

8. **file:codeframe/ui/routers/git_v2.py**
   - Import: `from codeframe.auth.dependencies import require_scope`
   - GET endpoints: `require_scope("read")`
   - POST endpoints (commit, push, etc.): `require_scope("write")`

9. **file:codeframe/ui/routers/pr_v2.py**
   - Import: `from codeframe.auth.dependencies import require_scope`
   - GET endpoints: `require_scope("read")`
   - POST endpoints: `require_scope("write")`

10. **file:codeframe/ui/routers/prd_v2.py**
    - Import: `from codeframe.auth.dependencies import require_scope`
    - GET endpoints: `require_scope("read")`
    - POST/DELETE endpoints: `require_scope("write")`

11. **file:codeframe/ui/routers/projects_v2.py**
    - Import: `from codeframe.auth.dependencies import require_scope`
    - GET `/api/v2/projects/status`, `/api/v2/projects/progress`, `/api/v2/projects/task-counts`, `/api/v2/projects/session`: add `auth: dict = Depends(require_scope("read"))`
    - DELETE `/api/v2/projects/session`: add `auth: dict = Depends(require_scope("write"))`

12. **file:codeframe/ui/routers/review_v2.py**
    - Import: `from codeframe.auth.dependencies import require_scope`
    - GET endpoints: `require_scope("read")`
    - POST endpoints: `require_scope("write")`

13. **file:codeframe/ui/routers/schedule_v2.py**
    - Import: `from codeframe.auth.dependencies import require_scope`
    - All endpoints: `require_scope("read")` (schedule analysis is read-only)

14. **file:codeframe/ui/routers/tasks_v2.py**
    - Import: `from codeframe.auth.dependencies import require_scope`
    - GET `/api/v2/tasks`, `/api/v2/tasks/{id}`, `/api/v2/tasks/assignment-status`, `/api/v2/tasks/{id}/run`, `/api/v2/tasks/{id}/stream`: add `auth: dict = Depends(require_scope("read"))`
    - POST `/api/v2/tasks/approve`, `/api/v2/tasks/execute`, `/api/v2/tasks/{id}/start`, `/api/v2/tasks/{id}/resume`: add `auth: dict = Depends(require_scope("write"))`
    - PATCH `/api/v2/tasks/{id}`: add `auth: dict = Depends(require_scope("write"))`
    - DELETE `/api/v2/tasks/{id}`: add `auth: dict = Depends(require_scope("write"))`
    - POST `/api/v2/tasks/{id}/stop`: add `auth: dict = Depends(require_scope("write"))`

15. **file:codeframe/ui/routers/templates_v2.py**
    - Import: `from codeframe.auth.dependencies import require_scope`
    - GET endpoints: `require_scope("read")`
    - POST endpoints: `require_scope("write")`

16. **file:codeframe/ui/routers/workspace_v2.py**
    - Import: `from codeframe.auth.dependencies import require_scope`
    - GET `/api/v2/workspaces/current`, `/api/v2/workspaces/exists`: add `auth: dict = Depends(require_scope("read"))`
    - POST `/api/v2/workspaces`: add `auth: dict = Depends(require_scope("write"))`
    - PATCH `/api/v2/workspaces/current`: add `auth: dict = Depends(require_scope("write"))`

**Pattern for Each Endpoint:**

```python
# Before
async def endpoint_name(
    request: Request,
    workspace: Workspace = Depends(get_v2_workspace),
) -> ResponseModel:

# After (for read endpoints)
async def endpoint_name(
    request: Request,
    workspace: Workspace = Depends(get_v2_workspace),
    auth: dict = Depends(require_scope("read")),
) -> ResponseModel:

# After (for write endpoints)
async def endpoint_name(
    request: Request,
    workspace: Workspace = Depends(get_v2_workspace),
    auth: dict = Depends(require_scope("write")),
) -> ResponseModel:
```

### 2. Frontend: Update API Client

**file:legacy/web-ui/src/lib/api-client.ts**

The `authFetch` helper already includes JWT tokens in the `Authorization` header. Ensure all v2 API calls use this helper:

- Verify all API calls to `/api/v2/*` endpoints use `authFetch` or `authenticatedFetch`
- If any calls use plain `fetch`, replace with `authFetch`

**Example pattern:**
```typescript
// Ensure v2 endpoints use authFetch
const response = await authFetch<TaskListResponse>(
  `${API_URL}/api/v2/tasks`,
  { method: 'GET' }
);
```

### 3. Tests: Update Test Fixtures and Cases

**file:tests/ui/test_v2_routers_integration.py**

Add authentication to all test requests:

1. **Add JWT token creation helper** (similar to `file:tests/auth/test_api_key_endpoints.py`):
   ```python
   def create_jwt_token(user_id: int = 1) -> str:
       """Create a JWT token for testing."""
       from codeframe.auth.manager import JWT_ALGORITHM, JWT_AUDIENCE, JWT_LIFETIME_SECONDS
       # ... implementation from test_api_key_endpoints.py
   ```

2. **Update test fixtures** to create test users in database:
   ```python
   @pytest.fixture
   def test_workspace():
       # ... existing workspace setup
       # Add user creation
       db = workspace.db
       db.conn.execute("""
           INSERT OR REPLACE INTO users (
               id, email, name, hashed_password,
               is_active, is_superuser, is_verified, email_verified
           )
           VALUES (1, 'test@example.com', 'Test User', '!DISABLED!', 1, 0, 1, 1)
       """)
       db.conn.commit()
   ```

3. **Update all test requests** to include auth headers:
   ```python
   # Before
   response = test_client.get("/api/v2/blockers")
   
   # After
   token = create_jwt_token(user_id=1)
   response = test_client.get(
       "/api/v2/blockers",
       headers={"Authorization": f"Bearer {token}"}
   )
   ```

4. **Add new test cases** for authentication:
   - Test that endpoints return 401 without authentication
   - Test that API key authentication works
   - Test that JWT authentication works
   - Test scope-based permissions (read vs write)

**Example new test class:**
```python
class TestV2Authentication:
    """Tests for v2 router authentication."""
    
    def test_endpoint_requires_auth(self, test_client):
        """V2 endpoints return 401 without authentication."""
        response = test_client.get("/api/v2/tasks")
        assert response.status_code == 401
    
    def test_endpoint_accepts_jwt(self, test_client):
        """V2 endpoints accept JWT authentication."""
        token = create_jwt_token(user_id=1)
        response = test_client.get(
            "/api/v2/tasks",
            headers={"Authorization": f"Bearer {token}"}
        )
        assert response.status_code == 200
    
    def test_endpoint_accepts_api_key(self, test_client, db):
        """V2 endpoints accept API key authentication."""
        full_key, key_hash, prefix = generate_api_key()
        db.api_keys.create(
            user_id=1,
            name="Test Key",
            key_hash=key_hash,
            prefix=prefix,
            scopes=["read", "write"],
            expires_at=None,
        )
        response = test_client.get(
            "/api/v2/tasks",
            headers={"X-API-Key": full_key}
        )
        assert response.status_code == 200
    
    def test_read_endpoint_requires_read_scope(self, test_client, db):
        """Read endpoints require read scope."""
        # Create API key with write-only scope
        full_key, key_hash, prefix = generate_api_key()
        db.api_keys.create(
            user_id=1,
            name="Write Only",
            key_hash=key_hash,
            prefix=prefix,
            scopes=["write"],  # write implies read
            expires_at=None,
        )
        response = test_client.get(
            "/api/v2/tasks",
            headers={"X-API-Key": full_key}
        )
        assert response.status_code == 200
    
    def test_write_endpoint_requires_write_scope(self, test_client, db):
        """Write endpoints require write scope."""
        # Create API key with read-only scope
        full_key, key_hash, prefix = generate_api_key()
        db.api_keys.create(
            user_id=1,
            name="Read Only",
            key_hash=key_hash,
            prefix=prefix,
            scopes=["read"],
            expires_at=None,
        )
        response = test_client.post(
            "/api/v2/blockers",
            json={"question": "Test"},
            headers={"X-API-Key": full_key}
        )
        assert response.status_code == 403  # Forbidden
```

### 4. Documentation Updates

**file:codeframe/ui/server.py** (lines 343-348)

The documentation already states authentication is required. Verify it mentions both authentication methods:

```python
## Authentication

All endpoints require authentication. The API supports two authentication methods:

1. **API Key** - Include `X-API-Key` header with your API key
2. **Session Token** - Use JWT token from login endpoint in `Authorization: Bearer <token>` header

API keys support scope-based permissions:
- `read`: Read-only access to all GET endpoints
- `write`: Read and write access (includes read permissions)
- `admin`: Full access including administrative operations
```

### 5. Migration Considerations

**Backward Compatibility:**
- Existing JWT-based authentication continues to work unchanged
- JWT tokens automatically get all scopes (read, write, admin) for backward compatibility
- No breaking changes for existing web UI users

**API Key Adoption:**
- Users can create API keys via `POST /api/auth/api-keys` (requires JWT)
- API keys enable programmatic access without session management
- Scope-based permissions allow fine-grained access control

**Testing Strategy:**
1. Update all existing v2 router tests to include authentication
2. Add new authentication-specific test cases
3. Verify both JWT and API key authentication work
4. Test scope-based permission enforcement
5. Ensure 401 responses for unauthenticated requests
6. Ensure 403 responses for insufficient permissions

## Sequence Diagram

```mermaid
sequenceDiagram
    participant Client
    participant Router as V2 Router
    participant Auth as require_scope()
    participant APIKey as get_api_key_auth()
    participant JWT as get_current_user_optional()
    participant DB as Database
    participant Core as Core Module

    Client->>Router: GET /api/v2/tasks<br/>(with X-API-Key or Bearer token)
    Router->>Auth: Check authentication
    
    alt API Key provided
        Auth->>APIKey: Extract & verify API key
        APIKey->>DB: Lookup key by prefix
        DB-->>APIKey: Return key record
        APIKey->>APIKey: Verify hash
        APIKey-->>Auth: Return auth dict with scopes
    else JWT Token provided
        Auth->>JWT: Verify JWT token
        JWT->>DB: Lookup user by ID
        DB-->>JWT: Return user
        JWT-->>Auth: Return user with all scopes
    else No auth provided
        Auth-->>Router: Raise 401 Unauthorized
        Router-->>Client: 401 Response
    end
    
    Auth->>Auth: Check scope (read/write)
    
    alt Insufficient scope
        Auth-->>Router: Raise 403 Forbidden
        Router-->>Client: 403 Response
    else Scope OK
        Auth-->>Router: Return auth dict
        Router->>Core: Call core module function
        Core-->>Router: Return data
        Router-->>Client: 200 Response with data
    end
```

## Summary

This implementation adds authentication to 16 unprotected v2 routers using the existing dual authentication system (JWT + API keys) with scope-based permissions. The changes are minimal and follow established patterns from `file:codeframe/auth/api_key_router.py`. Frontend changes are minimal since the API client already sends JWT tokens. Tests require updates to include authentication headers and verify permission enforcement. The implementation maintains backward compatibility while enabling secure programmatic access via API keys.

---

Execution Information

Branch: main
Commit: b252361

---

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

🔗 Related PRs

#82 - Review FastAPI server file refactoring strategy [merged]
#131 - Implement database-backed tasks endpoint with security fixes [merged]
#139 - feat: Add authentication & authorization infrastructure (Issue #132) [merged]
#238 - fix(auth): migrate lint API to authenticated axios and harden E2E tests [merged]
#459 - feat(api): PROOF9 REST API router — /api/v2/proof endpoints [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

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!

[frankbria]

🔄 Refreshed assessment — 2026-06-04 (post #609)

The original body predates a lot of development. The gap is still fully open (0 v2 routers enforce auth), but the specifics below have changed. Use this comment as the current plan of record.

Current state

• Auth infrastructure exists and is unused. require_auth (JWT or codeframe API key → 401) and require_scope("read"|"write"|"admin") live in codeframe/auth/dependencies.py. JWT login (/auth/jwt/login, /users, Migrate Authentication from BetterAuth to FastAPI Users #163) and codeframe API keys (/api/auth/api-keys, feat(auth): add API key authentication for CLI and REST API #326) are wired. The only consumer is auth/api_key_router.py.
• 0 of 22 v2 REST routers + 2 WS routers enforce auth. Server middleware is CORS + rate-limiting only. (Architecture note: "18 v2 routers currently lack auth — see Enforce authentication across the v2 API (routers, WS/SSE, and web-UI login) #336.")
• Frontend has no auth path. No login page exists; web-ui/src/lib/api.ts sends only withCredentials: true, no Authorization header. The API Keys settings tab ([Phase 5.1] Settings page: API key management #555) is for LLM-provider keys (Anthropic/OpenAI/GitHub), not codeframe-API auth — it does not help here.

Corrected router inventory (the body's list is stale)

• ❌ projects_v2.py no longer exists — remove from scope.
• ➕ New since the issue: costs_v2, settings_v2, proof_v2, github_integrations_v2, interactive_sessions_v2, schedule_v2.
• Total: 22 *_v2.py REST routers + 2 WebSocket routers (session_chat_ws.py, terminal_ws.py). SSE lives on streaming_v2.py.

Work breakdown (suggest splitting into sub-issues)

A. Backend enforcement (~1 hr, low risk)

• Apply auth centrally via dependencies=[Depends(require_auth)] on each include_router(...) in server.py (~22 lines), rather than editing every endpoint.
• Keep public: /, /health, OpenAPI docs, and the /auth/* login/register/api-key endpoints.
• Decide blanket require_auth vs require_scope (GET=read, mutate=write).

B. WebSocket / SSE auth (separate — different mechanism)

• session_chat_ws, terminal_ws, and SSE (streaming_v2, EventSource) can't use header Depends cleanly. Use a query-param/subprotocol token (prior art: commit "Include auth token in WebSocket connection URL").

C. Frontend auth path ⚠️ (largest / new work — gating blocker)

• There is no login UI and no token on requests, so enabling A without C locks users out of the web UI.
• Add a JWT login page + an axios request interceptor attaching Authorization: Bearer <jwt> (+ refresh/expiry handling), or an API-key bootstrap flow. EventSource/WS clients must pass the token too.

D. Test migration (broad, mechanical)

• ~17 test files / ~25 TestClient setups hit /api/v2; app-wide auth → all 401. Add a shared fixture using app.dependency_overrides[require_auth] (or an injected token) so existing tests pass, plus new tests asserting 401-without-auth.

Open decisions (needed before building)

1. Always-on vs env-gated AUTH_REQUIRED (default off for local/self-host, on for deployments). ⚠️ Note: feat(security): Remove AUTH_REQUIRED bypass - authentication now mandatory #168 deliberately removed an AUTH_REQUIRED bypass to make auth mandatory for the v1 stack — confirm product intent for v2.
2. Web-UI mechanism: JWT login page vs codeframe API key.
3. Scoping: blanket require_auth vs read/write scopes.
4. WS/SSE token transport.

Notes

• CLI golden path is unaffected (it needs no server).
• phase-6 = pre-launch hardening: this is required before public release, not necessarily for current local use.
• Original "References: discovered during PR feat: Phase 3 Workspace View with activity feed #335" — feat: Phase 3 Workspace View with activity feed #335 is long merged; this was never addressed.