[Phase 2] Add authentication to all v2 API routers

[frankbria]

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]

📝 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

---

🔗 Related PRs

#139 - feat: Add authentication & authorization infrastructure (Issue #132) [merged]

---

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