[Phase 2] API key authentication for server endpoints

[frankbria]

Overview

Implement API key authentication for server endpoints. This provides a simpler alternative to JWT tokens for programmatic API access while maintaining security.

Background

The current server uses JWT-based authentication via FastAPI Users. For Phase 2, we need to support:

1. API keys for programmatic/automation access (CI/CD, scripts, integrations)
2. JWT tokens retained for web UI sessions

API keys are preferred for server-to-server communication because:

• No expiration/refresh complexity
• Easier to rotate
• Can be scoped to specific permissions
• Works better with webhooks and integrations

Deliverables

1. API Key Model

class APIKey(BaseModel):
    id: str
    name: str  # Human-readable name (e.g., "CI Pipeline", "Slack Bot")
    key_hash: str  # bcrypt hash of the actual key
    prefix: str  # First 8 chars for identification (e.g., "cf_live_")
    scopes: list[str]  # ["read", "write", "admin"]
    created_at: datetime
    last_used_at: datetime | None
    expires_at: datetime | None  # Optional expiration
    is_active: bool

2. Key Generation

# Format: cf_{environment}_{random_32_chars}
# Examples:
#   cf_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
#   cf_test_x9y8z7w6v5u4t3s2r1q0p9o8n7m6l5k4

def generate_api_key(environment: str = "live") -> tuple[str, str]:
    """Returns (full_key, key_hash) - full_key shown once, hash stored."""
    random_part = secrets.token_hex(16)
    full_key = f"cf_{environment}_{random_part}"
    key_hash = bcrypt.hash(full_key)
    return full_key, key_hash

3. Authentication Middleware

from fastapi import Security, HTTPException
from fastapi.security import APIKeyHeader

api_key_header = APIKeyHeader(name="X-API-Key", auto_error=False)

async def get_api_key(
    api_key: str = Security(api_key_header),
) -> APIKey | None:
    if not api_key:
        return None
    
    # Look up by prefix for efficiency
    prefix = api_key[:12]  # "cf_live_" + first 4 of random
    key_record = await db.get_api_key_by_prefix(prefix)
    
    if key_record and bcrypt.verify(api_key, key_record.key_hash):
        await db.update_last_used(key_record.id)
        return key_record
    
    return None

async def require_auth(
    api_key: APIKey | None = Depends(get_api_key),
    jwt_user: User | None = Depends(get_current_user_optional),
):
    """Accept either API key or JWT token."""
    if api_key:
        return {"type": "api_key", "principal": api_key}
    if jwt_user:
        return {"type": "jwt", "principal": jwt_user}
    raise HTTPException(status_code=401, detail="Authentication required")

4. CLI Commands

# Create API key
cf auth api-key create --name "CI Pipeline" --scopes read,write
# Output: Your API key (shown once): cf_live_a1b2c3d4...

# List API keys
cf auth api-key list
# Output: 
#   ID          NAME           SCOPES        LAST USED
#   cf_live_a1  CI Pipeline    read,write    2 hours ago
#   cf_live_x9  Slack Bot      read          Never

# Revoke API key
cf auth api-key revoke cf_live_a1

# Rotate API key (revoke old, create new with same name/scopes)
cf auth api-key rotate cf_live_a1

5. Server Endpoints

@router.post("/api/auth/api-keys")
async def create_api_key(name: str, scopes: list[str], auth = Depends(require_auth)):
    """Create a new API key (requires admin or JWT auth)."""

@router.get("/api/auth/api-keys")
async def list_api_keys(auth = Depends(require_auth)):
    """List API keys (hashes not included)."""

@router.delete("/api/auth/api-keys/{key_id}")
async def revoke_api_key(key_id: str, auth = Depends(require_auth)):
    """Revoke an API key."""

6. Scope Definitions

Scope	Permissions
read	List tasks, view status, stream output
write	Create tasks, answer blockers, execute
admin	Manage API keys, delete projects

Acceptance Criteria

• API keys can be created, listed, and revoked via CLI
• API keys authenticate server requests via X-API-Key header
• API keys support scope-based permissions
• API keys work alongside existing JWT authentication
• Keys are stored as bcrypt hashes (never plaintext)
• Last-used timestamp tracked for auditing
• Documentation for API key usage

Security Considerations

• Keys shown only once at creation
• Keys stored as bcrypt hashes
• Rate limiting applies to API key auth ([Phase 2] Implement API Rate Limiting for Security #167)
• Audit log for key creation/revocation
• Optional expiration for time-limited access

Related Issues

• [Phase 2] Implement API Rate Limiting for Security #167 - Rate limiting
• [Phase 2] Server audit and refactor - routes delegating to core modules #322 - Server audit (authentication applies to all routes)
• [Phase 2] Complete OpenAPI documentation for all endpoints #119 - OpenAPI documentation (document auth schemes)

References

• docs/authentication.md - Current auth documentation
• Stripe API keys as reference design

[traycerai]

Plan

Observations

The codebase uses FastAPI Users for JWT-based authentication with SQLAlchemy models, bcrypt password hashing via passlib, and a well-structured router pattern. The database uses SQLite with a SchemaManager for migrations, and the CLI uses Typer with a modular command structure. All necessary dependencies (passlib, fastapi-users, python-jose) are already installed. The authentication system is centralized in file:codeframe/auth/ with dependencies in file:codeframe/auth/dependencies.py and routers in file:codeframe/auth/router.py.

Approach

The implementation will extend the existing authentication system to support dual authentication (API keys + JWT tokens) while maintaining backward compatibility. API keys will be stored as bcrypt hashes in a new api_keys table, with a prefix-based lookup optimization. A new authentication dependency will check both X-API-Key header and JWT Bearer tokens, returning a unified principal object. CLI commands will follow the existing Typer pattern under the auth subcommand, and server endpoints will use the existing router pattern. Scope-based permissions will be enforced at the dependency level.

Implementation Steps

1. Database Schema - API Keys Table

File: file:codeframe/persistence/schema_manager.py

Add API keys table creation in the _create_auth_tables method:

• Create api_keys table with columns: id (TEXT PRIMARY KEY), user_id (INTEGER FK to users), name (TEXT), key_hash (TEXT), prefix (TEXT for fast lookup), scopes (JSON array), created_at (TIMESTAMP), last_used_at (TIMESTAMP), expires_at (TIMESTAMP nullable), is_active (BOOLEAN)
• Add index on prefix column for efficient lookups: CREATE INDEX idx_api_keys_prefix ON api_keys(prefix)
• Add index on user_id for user-specific queries: CREATE INDEX idx_api_keys_user_id ON api_keys(user_id)
• Add index on is_active for filtering active keys: CREATE INDEX idx_api_keys_active ON api_keys(is_active) WHERE is_active = TRUE

2. API Key Generation Utilities

File: file:codeframe/auth/api_keys.py (new file)

Create utility functions for API key management:

• generate_api_key(environment: str = "live") -> tuple[str, str, str]: Generate random API key with format cf_{environment}_{32_hex_chars}, return (full_key, key_hash, prefix)
  • Use secrets.token_hex(16) for random part
  • Use passlib.hash.bcrypt.hash() for hashing (consistent with existing password hashing)
  • Extract prefix as first 12 characters: cf_{env}_xxxx
• verify_api_key(key: str, key_hash: str) -> bool: Verify key against bcrypt hash using passlib.hash.bcrypt.verify()
• extract_prefix(key: str) -> str: Extract prefix from full key for database lookup
• Define scope constants: SCOPE_READ, SCOPE_WRITE, SCOPE_ADMIN as string literals
• validate_scopes(scopes: list[str]) -> bool: Validate scope list against allowed values

3. API Key Database Repository

File: file:codeframe/persistence/repositories/api_key_repository.py (new file)

Create repository for API key CRUD operations following the existing repository pattern in file:codeframe/persistence/repositories/:

• create_api_key(user_id: int, name: str, key_hash: str, prefix: str, scopes: list[str], expires_at: datetime | None) -> str: Insert new API key, return generated ID
• get_api_key_by_prefix(prefix: str) -> dict | None: Lookup by prefix for authentication
• list_user_api_keys(user_id: int) -> list[dict]: List all keys for a user (exclude key_hash)
• update_last_used(key_id: str) -> None: Update last_used_at timestamp
• revoke_api_key(key_id: str, user_id: int) -> bool: Set is_active=False, verify ownership
• delete_api_key(key_id: str, user_id: int) -> bool: Hard delete, verify ownership
• get_api_key_by_id(key_id: str) -> dict | None: Get full key record by ID

Integrate repository into file:codeframe/persistence/database.py:

• Add api_keys: Optional[APIKeyRepository] property
• Initialize in _initialize_repositories() method
• Add delegation methods: create_api_key(), get_api_key_by_prefix(), etc.

4. Unified Authentication Dependency

File: file:codeframe/auth/dependencies.py

Extend authentication to support both API keys and JWT tokens:

• Import APIKeyHeader from fastapi.security
• Create api_key_header = APIKeyHeader(name="X-API-Key", auto_error=False)
• Add async def get_api_key_auth(api_key: str = Security(api_key_header), request: Request) -> dict | None:
  • If no API key header, return None
  • Extract prefix using extract_prefix(api_key)
  • Query database: db.get_api_key_by_prefix(prefix)
  • Verify hash using verify_api_key(api_key, record.key_hash)
  • Check is_active and expires_at
  • Update last_used_at asynchronously
  • Return {"type": "api_key", "user_id": record.user_id, "scopes": record.scopes, "key_id": record.id}
• Add async def require_auth(api_key_auth: dict | None = Depends(get_api_key_auth), jwt_user: User | None = Depends(get_current_user_optional)) -> dict:
  • If api_key_auth exists, return it
  • If jwt_user exists, return {"type": "jwt", "user_id": jwt_user.id, "scopes": ["read", "write", "admin"], "user": jwt_user}
  • Otherwise raise HTTPException(401, "Authentication required")
• Add scope checking helper: def require_scope(required_scope: str) -> Callable: Returns dependency that checks if principal has required scope

5. API Key Management Endpoints

File: file:codeframe/auth/api_key_router.py (new file)

Create FastAPI router for API key management:

• router = APIRouter(prefix="/api/auth/api-keys", tags=["auth", "api-keys"])
• POST /api/auth/api-keys: Create new API key
  • Require JWT authentication (not API key auth to prevent privilege escalation)
  • Request body: {"name": str, "scopes": list[str], "expires_at": datetime | None}
  • Generate key using generate_api_key()
  • Store in database via db.create_api_key()
  • Return {"key": full_key, "id": key_id, "prefix": prefix, "created_at": timestamp} (key shown only once)
• GET /api/auth/api-keys: List user's API keys
  • Use require_auth dependency
  • Query db.list_user_api_keys(user_id)
  • Return list with masked keys (show prefix only)
• DELETE /api/auth/api-keys/{key_id}: Revoke API key
  • Use require_auth dependency
  • Call db.revoke_api_key(key_id, user_id)
  • Return success confirmation

Mount router in file:codeframe/auth/router.py:

• Import api_key_router
• Add router.include_router(api_key_router.router)

6. CLI Commands for API Key Management

File: file:codeframe/cli/auth_commands.py

Add new commands to the existing auth_app Typer instance:

• @auth_app.command("api-key-create"): Create API key
  • Options: --name (required), --scopes (comma-separated, default="read,write")
  • Use APIClient to POST to /api/auth/api-keys
  • Display full key with warning: "Save this key - it won't be shown again"
  • Show prefix for identification
• @auth_app.command("api-key-list"): List API keys
  • Use APIClient to GET /api/auth/api-keys
  • Display table with columns: ID (prefix), Name, Scopes, Last Used, Created
  • Use Rich table formatting (already imported)
• @auth_app.command("api-key-revoke"): Revoke API key
  • Argument: key_id (prefix or full ID)
  • Option: --yes to skip confirmation
  • Use APIClient to DELETE /api/auth/api-keys/{key_id}
  • Show confirmation message
• @auth_app.command("api-key-rotate"): Rotate API key (convenience command)
  • Argument: key_id
  • Revoke old key and create new one with same name/scopes
  • Atomic operation: only revoke if new key creation succeeds

7. Update Existing Endpoints for Dual Auth

Files: All routers in file:codeframe/ui/routers/

Update authentication dependencies in existing endpoints:

• Replace current_user: User = Depends(get_current_user) with auth: dict = Depends(require_auth)
• Access user ID via auth["user_id"] instead of current_user.id
• For endpoints requiring specific scopes, use auth: dict = Depends(require_scope("write"))
• Maintain backward compatibility: JWT tokens continue to work with full permissions

Example pattern for file:codeframe/ui/routers/projects.py:

• @router.post(""): Change to auth: dict = Depends(require_scope("write"))
• @router.get(""): Change to auth: dict = Depends(require_auth) (read-only)
• @router.delete("/{project_id}"): Change to auth: dict = Depends(require_scope("admin"))

8. Scope-Based Authorization Logic

File: file:codeframe/auth/scopes.py (new file)

Define scope hierarchy and validation:

• Define scope enum: class Scope(str, Enum): READ = "read", WRITE = "write", ADMIN = "admin"
• Define scope hierarchy: SCOPE_HIERARCHY = {"admin": ["read", "write", "admin"], "write": ["read", "write"], "read": ["read"]}
• def has_scope(principal: dict, required_scope: str) -> bool: Check if principal has required scope based on hierarchy
• def get_scope_permissions(scope: str) -> list[str]: Return all permissions granted by a scope

Integrate into file:codeframe/auth/dependencies.py:

• Use has_scope() in require_scope() dependency
• JWT users get all scopes by default (backward compatibility)
• API keys get scopes from database record

9. Security Enhancements

File: file:codeframe/auth/api_keys.py

Add security features:

• Rate limiting: Track failed authentication attempts per prefix
• Key rotation: Add rotated_from field to track key lineage
• Audit logging: Log all API key operations (create, revoke, authentication)

File: file:codeframe/persistence/repositories/audit_repository.py

Extend audit logging:

• Add event types: API_KEY_CREATED, API_KEY_REVOKED, API_KEY_AUTH_SUCCESS, API_KEY_AUTH_FAILED
• Log user_id, key_id, IP address, timestamp

10. Documentation Updates

File: file:docs/authentication.md (update existing or create new)

Document API key authentication:

• Overview of dual authentication (JWT + API keys)
• When to use API keys vs JWT tokens
• How to create and manage API keys via CLI
• How to use API keys in HTTP requests (X-API-Key header)
• Scope definitions and permissions
• Security best practices (key rotation, expiration, least privilege)
• Example curl commands with API keys

11. Testing Considerations

While not writing tests, note areas requiring test coverage:

• API key generation and verification (bcrypt hashing)
• Prefix-based lookup performance
• Dual authentication flow (API key + JWT)
• Scope-based authorization
• Key revocation and expiration
• Concurrent authentication requests
• Invalid key handling
• Rate limiting for failed attempts

Sequence Diagram

sequenceDiagram
    participant CLI as CLI Client
    participant API as FastAPI Server
    participant Auth as Auth Dependency
    participant DB as Database
    participant BCrypt as BCrypt

    Note over CLI,BCrypt: API Key Creation Flow
    CLI->>API: POST /api/auth/api-keys<br/>{name, scopes}
    API->>Auth: Verify JWT token
    Auth->>DB: Validate user
    DB-->>Auth: User valid
    Auth-->>API: User authenticated
    API->>BCrypt: Generate key & hash
    BCrypt-->>API: (key, hash, prefix)
    API->>DB: Store key record
    DB-->>API: Key ID
    API-->>CLI: {key, id, prefix}<br/>(key shown once)

    Note over CLI,BCrypt: API Key Authentication Flow
    CLI->>API: GET /api/projects<br/>X-API-Key: cf_live_xxx
    API->>Auth: Check X-API-Key header
    Auth->>DB: Lookup by prefix
    DB-->>Auth: Key record (hash, scopes)
    Auth->>BCrypt: Verify key against hash
    BCrypt-->>Auth: Valid
    Auth->>DB: Update last_used_at
    Auth-->>API: {type: api_key, user_id, scopes}
    API->>DB: Query projects for user
    DB-->>API: Projects data
    API-->>CLI: Projects response

Loading

Implementation Notes

• Backward Compatibility: All existing JWT authentication continues to work unchanged. API keys are additive.
• Security: API keys use bcrypt hashing (same as passwords), stored hashes never exposed via API.
• Performance: Prefix-based lookup (indexed) avoids full table scans during authentication.
• Scope Hierarchy: Admin scope includes write and read; write includes read. JWT tokens get all scopes for backward compatibility.
• Key Format: cf_{environment}_{32_hex} provides visual identification and environment separation.
• Audit Trail: All API key operations logged to audit_logs table for security monitoring.
• Expiration: Optional expires_at field allows time-limited keys for temporary access.
• CLI Integration: Commands follow existing Typer pattern in file:codeframe/cli/auth_commands.py.
• Database Migration: New table added via SchemaManager._create_auth_tables(), idempotent with CREATE TABLE IF NOT EXISTS.

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase uses FastAPI Users for JWT-based authentication with SQLAlchemy models, bcrypt password hashing via passlib, and a well-structured router pattern. The database uses SQLite with a SchemaManager for migrations, and the CLI uses Typer with a modular command structure. All necessary dependencies (passlib, fastapi-users, python-jose) are already installed. The authentication system is centralized in `file:codeframe/auth/` with dependencies in `file:codeframe/auth/dependencies.py` and routers in `file:codeframe/auth/router.py`.

## Approach

The implementation will extend the existing authentication system to support dual authentication (API keys + JWT tokens) while maintaining backward compatibility. API keys will be stored as bcrypt hashes in a new `api_keys` table, with a prefix-based lookup optimization. A new authentication dependency will check both `X-API-Key` header and JWT Bearer tokens, returning a unified principal object. CLI commands will follow the existing Typer pattern under the `auth` subcommand, and server endpoints will use the existing router pattern. Scope-based permissions will be enforced at the dependency level.

## Implementation Steps

### 1. Database Schema - API Keys Table

**File:** `file:codeframe/persistence/schema_manager.py`

Add API keys table creation in the `_create_auth_tables` method:

- Create `api_keys` table with columns: `id` (TEXT PRIMARY KEY), `user_id` (INTEGER FK to users), `name` (TEXT), `key_hash` (TEXT), `prefix` (TEXT for fast lookup), `scopes` (JSON array), `created_at` (TIMESTAMP), `last_used_at` (TIMESTAMP), `expires_at` (TIMESTAMP nullable), `is_active` (BOOLEAN)
- Add index on `prefix` column for efficient lookups: `CREATE INDEX idx_api_keys_prefix ON api_keys(prefix)`
- Add index on `user_id` for user-specific queries: `CREATE INDEX idx_api_keys_user_id ON api_keys(user_id)`
- Add index on `is_active` for filtering active keys: `CREATE INDEX idx_api_keys_active ON api_keys(is_active) WHERE is_active = TRUE`

### 2. API Key Generation Utilities

**File:** `file:codeframe/auth/api_keys.py` (new file)

Create utility functions for API key management:

- `generate_api_key(environment: str = "live") -> tuple[str, str, str]`: Generate random API key with format `cf_{environment}_{32_hex_chars}`, return (full_key, key_hash, prefix)
  - Use `secrets.token_hex(16)` for random part
  - Use `passlib.hash.bcrypt.hash()` for hashing (consistent with existing password hashing)
  - Extract prefix as first 12 characters: `cf_{env}_xxxx`
- `verify_api_key(key: str, key_hash: str) -> bool`: Verify key against bcrypt hash using `passlib.hash.bcrypt.verify()`
- `extract_prefix(key: str) -> str`: Extract prefix from full key for database lookup
- Define scope constants: `SCOPE_READ`, `SCOPE_WRITE`, `SCOPE_ADMIN` as string literals
- `validate_scopes(scopes: list[str]) -> bool`: Validate scope list against allowed values

### 3. API Key Database Repository

**File:** `file:codeframe/persistence/repositories/api_key_repository.py` (new file)

Create repository for API key CRUD operations following the existing repository pattern in `file:codeframe/persistence/repositories/`:

- `create_api_key(user_id: int, name: str, key_hash: str, prefix: str, scopes: list[str], expires_at: datetime | None) -> str`: Insert new API key, return generated ID
- `get_api_key_by_prefix(prefix: str) -> dict | None`: Lookup by prefix for authentication
- `list_user_api_keys(user_id: int) -> list[dict]`: List all keys for a user (exclude key_hash)
- `update_last_used(key_id: str) -> None`: Update last_used_at timestamp
- `revoke_api_key(key_id: str, user_id: int) -> bool`: Set is_active=False, verify ownership
- `delete_api_key(key_id: str, user_id: int) -> bool`: Hard delete, verify ownership
- `get_api_key_by_id(key_id: str) -> dict | None`: Get full key record by ID

Integrate repository into `file:codeframe/persistence/database.py`:

- Add `api_keys: Optional[APIKeyRepository]` property
- Initialize in `_initialize_repositories()` method
- Add delegation methods: `create_api_key()`, `get_api_key_by_prefix()`, etc.

### 4. Unified Authentication Dependency

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

Extend authentication to support both API keys and JWT tokens:

- Import `APIKeyHeader` from `fastapi.security`
- Create `api_key_header = APIKeyHeader(name="X-API-Key", auto_error=False)`
- Add `async def get_api_key_auth(api_key: str = Security(api_key_header), request: Request) -> dict | None`:
  - If no API key header, return None
  - Extract prefix using `extract_prefix(api_key)`
  - Query database: `db.get_api_key_by_prefix(prefix)`
  - Verify hash using `verify_api_key(api_key, record.key_hash)`
  - Check `is_active` and `expires_at`
  - Update `last_used_at` asynchronously
  - Return `{"type": "api_key", "user_id": record.user_id, "scopes": record.scopes, "key_id": record.id}`
- Add `async def require_auth(api_key_auth: dict | None = Depends(get_api_key_auth), jwt_user: User | None = Depends(get_current_user_optional)) -> dict`:
  - If `api_key_auth` exists, return it
  - If `jwt_user` exists, return `{"type": "jwt", "user_id": jwt_user.id, "scopes": ["read", "write", "admin"], "user": jwt_user}`
  - Otherwise raise `HTTPException(401, "Authentication required")`
- Add scope checking helper: `def require_scope(required_scope: str) -> Callable`: Returns dependency that checks if principal has required scope

### 5. API Key Management Endpoints

**File:** `file:codeframe/auth/api_key_router.py` (new file)

Create FastAPI router for API key management:

- `router = APIRouter(prefix="/api/auth/api-keys", tags=["auth", "api-keys"])`
- `POST /api/auth/api-keys`: Create new API key
  - Require JWT authentication (not API key auth to prevent privilege escalation)
  - Request body: `{"name": str, "scopes": list[str], "expires_at": datetime | None}`
  - Generate key using `generate_api_key()`
  - Store in database via `db.create_api_key()`
  - Return `{"key": full_key, "id": key_id, "prefix": prefix, "created_at": timestamp}` (key shown only once)
- `GET /api/auth/api-keys`: List user's API keys
  - Use `require_auth` dependency
  - Query `db.list_user_api_keys(user_id)`
  - Return list with masked keys (show prefix only)
- `DELETE /api/auth/api-keys/{key_id}`: Revoke API key
  - Use `require_auth` dependency
  - Call `db.revoke_api_key(key_id, user_id)`
  - Return success confirmation

Mount router in `file:codeframe/auth/router.py`:

- Import `api_key_router`
- Add `router.include_router(api_key_router.router)`

### 6. CLI Commands for API Key Management

**File:** `file:codeframe/cli/auth_commands.py`

Add new commands to the existing `auth_app` Typer instance:

- `@auth_app.command("api-key-create")`: Create API key
  - Options: `--name` (required), `--scopes` (comma-separated, default="read,write")
  - Use `APIClient` to POST to `/api/auth/api-keys`
  - Display full key with warning: "Save this key - it won't be shown again"
  - Show prefix for identification
- `@auth_app.command("api-key-list")`: List API keys
  - Use `APIClient` to GET `/api/auth/api-keys`
  - Display table with columns: ID (prefix), Name, Scopes, Last Used, Created
  - Use Rich table formatting (already imported)
- `@auth_app.command("api-key-revoke")`: Revoke API key
  - Argument: `key_id` (prefix or full ID)
  - Option: `--yes` to skip confirmation
  - Use `APIClient` to DELETE `/api/auth/api-keys/{key_id}`
  - Show confirmation message
- `@auth_app.command("api-key-rotate")`: Rotate API key (convenience command)
  - Argument: `key_id`
  - Revoke old key and create new one with same name/scopes
  - Atomic operation: only revoke if new key creation succeeds

### 7. Update Existing Endpoints for Dual Auth

**Files:** All routers in `file:codeframe/ui/routers/`

Update authentication dependencies in existing endpoints:

- Replace `current_user: User = Depends(get_current_user)` with `auth: dict = Depends(require_auth)`
- Access user ID via `auth["user_id"]` instead of `current_user.id`
- For endpoints requiring specific scopes, use `auth: dict = Depends(require_scope("write"))`
- Maintain backward compatibility: JWT tokens continue to work with full permissions

Example pattern for `file:codeframe/ui/routers/projects.py`:
- `@router.post("")`: Change to `auth: dict = Depends(require_scope("write"))`
- `@router.get("")`: Change to `auth: dict = Depends(require_auth)` (read-only)
- `@router.delete("/{project_id}")`: Change to `auth: dict = Depends(require_scope("admin"))`

### 8. Scope-Based Authorization Logic

**File:** `file:codeframe/auth/scopes.py` (new file)

Define scope hierarchy and validation:

- Define scope enum: `class Scope(str, Enum): READ = "read", WRITE = "write", ADMIN = "admin"`
- Define scope hierarchy: `SCOPE_HIERARCHY = {"admin": ["read", "write", "admin"], "write": ["read", "write"], "read": ["read"]}`
- `def has_scope(principal: dict, required_scope: str) -> bool`: Check if principal has required scope based on hierarchy
- `def get_scope_permissions(scope: str) -> list[str]`: Return all permissions granted by a scope

Integrate into `file:codeframe/auth/dependencies.py`:

- Use `has_scope()` in `require_scope()` dependency
- JWT users get all scopes by default (backward compatibility)
- API keys get scopes from database record

### 9. Security Enhancements

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

Add security features:

- Rate limiting: Track failed authentication attempts per prefix
- Key rotation: Add `rotated_from` field to track key lineage
- Audit logging: Log all API key operations (create, revoke, authentication)

**File:** `file:codeframe/persistence/repositories/audit_repository.py`

Extend audit logging:

- Add event types: `API_KEY_CREATED`, `API_KEY_REVOKED`, `API_KEY_AUTH_SUCCESS`, `API_KEY_AUTH_FAILED`
- Log user_id, key_id, IP address, timestamp

### 10. Documentation Updates

**File:** `file:docs/authentication.md` (update existing or create new)

Document API key authentication:

- Overview of dual authentication (JWT + API keys)
- When to use API keys vs JWT tokens
- How to create and manage API keys via CLI
- How to use API keys in HTTP requests (X-API-Key header)
- Scope definitions and permissions
- Security best practices (key rotation, expiration, least privilege)
- Example curl commands with API keys

### 11. Testing Considerations

While not writing tests, note areas requiring test coverage:

- API key generation and verification (bcrypt hashing)
- Prefix-based lookup performance
- Dual authentication flow (API key + JWT)
- Scope-based authorization
- Key revocation and expiration
- Concurrent authentication requests
- Invalid key handling
- Rate limiting for failed attempts

## Sequence Diagram

```mermaid
sequenceDiagram
    participant CLI as CLI Client
    participant API as FastAPI Server
    participant Auth as Auth Dependency
    participant DB as Database
    participant BCrypt as BCrypt

    Note over CLI,BCrypt: API Key Creation Flow
    CLI->>API: POST /api/auth/api-keys<br/>{name, scopes}
    API->>Auth: Verify JWT token
    Auth->>DB: Validate user
    DB-->>Auth: User valid
    Auth-->>API: User authenticated
    API->>BCrypt: Generate key & hash
    BCrypt-->>API: (key, hash, prefix)
    API->>DB: Store key record
    DB-->>API: Key ID
    API-->>CLI: {key, id, prefix}<br/>(key shown once)

    Note over CLI,BCrypt: API Key Authentication Flow
    CLI->>API: GET /api/projects<br/>X-API-Key: cf_live_xxx
    API->>Auth: Check X-API-Key header
    Auth->>DB: Lookup by prefix
    DB-->>Auth: Key record (hash, scopes)
    Auth->>BCrypt: Verify key against hash
    BCrypt-->>Auth: Valid
    Auth->>DB: Update last_used_at
    Auth-->>API: {type: api_key, user_id, scopes}
    API->>DB: Query projects for user
    DB-->>API: Projects data
    API-->>CLI: Projects response
```

## Implementation Notes

- **Backward Compatibility**: All existing JWT authentication continues to work unchanged. API keys are additive.
- **Security**: API keys use bcrypt hashing (same as passwords), stored hashes never exposed via API.
- **Performance**: Prefix-based lookup (indexed) avoids full table scans during authentication.
- **Scope Hierarchy**: Admin scope includes write and read; write includes read. JWT tokens get all scopes for backward compatibility.
- **Key Format**: `cf_{environment}_{32_hex}` provides visual identification and environment separation.
- **Audit Trail**: All API key operations logged to `audit_logs` table for security monitoring.
- **Expiration**: Optional `expires_at` field allows time-limited keys for temporary access.
- **CLI Integration**: Commands follow existing Typer pattern in `file:codeframe/cli/auth_commands.py`.
- **Database Migration**: New table added via `SchemaManager._create_auth_tables()`, idempotent with `CREATE TABLE IF NOT EXISTS`.

---

Execution Information

Branch: main
Commit: 7fc6a53

---

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