[V2] Implement comprehensive credential management system

[frankbria]

🎯 Overview

Implement comprehensive credential management system to address the critical authentication gap identified in the enhanced MVP. This is the second most critical blocker that would prevent users from reliably using CodeFRAME CLI workflow.

🚨 Critical Blocker Details

Current State: Basic auth commands exist but lack comprehensive management
Problem: Users would encounter authentication failures at multiple workflow points:

• PRD generation (LLM API keys)
• Task execution (LLM provider access)
• Git/PR operations (GitHub tokens)
• CI/CD integration (deployment credentials)

📋 Implementation Requirements

Phase 1: Secure Credential Storage

• Create `codeframe/core/credentials.py` module with encrypted storage
• Support for multiple credential providers:
  • LLM providers (Anthropic, OpenAI, etc.)
  • Git providers (GitHub, GitLab, etc.)
  • CI/CD providers (deployment tokens)
  • Database providers (connection strings)
• Platform-native keyring integration when available
• Fallback encrypted file storage with access controls

Phase 2: CLI Management Interface

• Add `codeframe auth setup` command for interactive configuration
• Implement `codeframe auth list` to show configured providers/keys
• Add `codeframe auth validate ` for credential health checking
• Create `codeframe auth rotate ` for secure key rotation
• Add `codeframe auth remove ` for credential removal
• Support for environment variable overrides and validation

Phase 3: Integration Framework

• Integrate credential manager with existing LLM adapters
• Add GitHub token validation and usage in git integration
• Ensure credential validation before workflow operations
• Add credential health monitoring and expiration alerts
• Support for different authentication scopes and permissions

Phase 4: Security & Validation

• Implement credential encryption at rest and in transit
• Add access controls and permission validation
• Support for credential sharing policies and restrictions
• Implement audit logging for credential access and changes
• Add security best practices compliance checking

🔗 Dependencies

• Critical for all enhanced MVP features that require external APIs
• Must integrate with existing config system
• Should work with current workspace state management
• Needs to support multiple environments (dev/staging/prod)

✅ Acceptance Criteria

• Users can run `codeframe auth setup` and configure all required providers
• Credentials are stored securely and encrypted at rest
• `codeframe auth validate` can test credential health before workflow execution
• Credential failures are prevented with proactive validation
• Support for credential rotation without workflow interruption
• Comprehensive test coverage for all credential management scenarios
• Security audit passes all compliance requirements
• Integration with all existing LLM and Git provider implementations

🎯 Success Metrics

• Eliminates authentication failures across entire workflow
• Improves user onboarding and setup experience
• Enables reliable batch execution without authentication interruptions
• Provides secure credential lifecycle management
• Reduces support burden from credential-related issues

📚 References

• Enhanced MVP specification: `docs/GOLDEN_PATH.md`
• Gap analysis: `docs/GAP_ANALYSIS_SUMMARY.md`
• Implementation plan: `docs/CRITICAL_GAP_IMPLEMENTATION_PLAN.md`
• Security requirements: `docs/GAP_ANALYSIS_SUMMARY.md`
• Current auth system: `codeframe/cli/auth_commands.py`

This is the second highest priority implementation as it prevents authentication failures that would block the entire enhanced workflow.

[traycerai]

Plan

Observations

The codebase currently has basic JWT authentication for user sessions stored in ~/.codeframe/credentials.json with file permissions (600). LLM provider API keys (Anthropic, OpenAI) and GitHub tokens are read directly from environment variables via file:codeframe/core/config.py. No encryption, keyring integration, or comprehensive credential management exists. The project already includes python-jose[cryptography] for JWT handling, which can be leveraged for encryption. The existing auth module at file:codeframe/cli/auth.py provides a foundation for credential storage patterns.

Approach

The implementation will create a new credential management system in file:codeframe/core/credentials.py that provides encrypted storage with platform-native keyring integration as the primary method and encrypted file storage as fallback. New CLI commands under codeframe auth will manage credentials for multiple provider types (LLM, Git, CI/CD, Database). The system will integrate with existing components by modifying file:codeframe/core/config.py to use the credential manager, updating LLM providers (file:codeframe/providers/anthropic.py, file:codeframe/providers/sdk_client.py) and Git integration (file:codeframe/git/github_integration.py) to retrieve credentials through the manager. This approach maintains backward compatibility with environment variables while adding comprehensive management capabilities.

Implementation Steps

Phase 1: Secure Credential Storage

1.1 Create Core Credential Manager Module

Create file:codeframe/core/credentials.py with the following components:

CredentialProvider Enum

• Define provider types: LLM_ANTHROPIC, LLM_OPENAI, GIT_GITHUB, GIT_GITLAB, CICD_GENERIC, DATABASE
• Each provider type maps to specific credential requirements

Credential Model

• Use Pydantic model with fields: provider, name, value, metadata, created_at, expires_at
• Support for credential scopes and permissions in metadata
• Validation for required fields per provider type

CredentialStore Class

• Primary storage: Platform-native keyring using keyring library
• Fallback storage: Encrypted JSON file at ~/.codeframe/credentials.encrypted
• Encryption using cryptography.fernet with key derived from machine-specific identifier
• Methods: store(), retrieve(), delete(), list_providers()
• Automatic fallback detection: Try keyring first, fall back to encrypted file if unavailable

Encryption Implementation

• Generate encryption key from machine ID + salt stored in ~/.codeframe/salt
• Use Fernet symmetric encryption for credential values
• Store encrypted credentials with IV/nonce for security
• File permissions: 600 (owner read/write only)

1.2 Add Dependencies

Update file:pyproject.toml dependencies:

• Add keyring>=24.0.0 for platform-native credential storage
• Add cryptography>=41.0.0 for Fernet encryption (already included via python-jose, but make explicit)
• These libraries provide cross-platform secure storage

1.3 Implement Credential Manager

Create CredentialManager class in file:codeframe/core/credentials.py:

Initialization

• Detect available storage backend (keyring vs encrypted file)
• Initialize encryption keys if using file storage
• Create credential directory structure if needed

Core Methods

• set_credential(provider, name, value, metadata): Store credential with validation
• get_credential(provider, name): Retrieve credential with environment variable override
• delete_credential(provider, name): Remove credential securely
• list_credentials(): Return list of configured providers (not values)
• validate_credential(provider, name): Test credential health
• rotate_credential(provider, name, new_value): Secure rotation with audit trail

Environment Variable Override

• Check environment variables first (e.g., ANTHROPIC_API_KEY)
• Fall back to stored credentials if env var not set
• Log source of credential for debugging

Phase 2: CLI Management Interface

2.1 Extend Auth Commands Module

Modify file:codeframe/cli/auth_commands.py to add new credential management commands:

codeframe auth setup Command

• Interactive wizard for configuring credentials
• Prompt for provider type selection (LLM, Git, CI/CD, Database)
• Provider-specific prompts (e.g., API key for Anthropic, token for GitHub)
• Validate credentials immediately after entry
• Store securely using CredentialManager
• Display success confirmation with masked credential preview

codeframe auth list Command

• Display table of configured providers using Rich library
• Show: provider type, name, status (valid/expired/unknown), last validated
• Mask credential values (show only first/last 4 characters)
• Indicate source (environment variable vs stored)
• Group by provider type for clarity

codeframe auth validate <provider> Command

• Test credential health for specific provider
• For LLM providers: Make test API call with minimal token usage
• For GitHub: Verify token scopes and permissions
• Display validation results with detailed error messages
• Update last validated timestamp in metadata
• Exit code 0 for valid, 1 for invalid

codeframe auth rotate <provider> Command

• Prompt for new credential value
• Validate new credential before replacing old one
• Atomic replacement (store new, delete old only if successful)
• Log rotation event for audit trail
• Support for --force flag to skip validation

codeframe auth remove <provider> Command

• Confirm deletion with prompt (unless --yes flag)
• Remove credential from storage
• Clear any cached values
• Log removal event for audit trail

2.2 Add Validation Helpers

Create validation functions in file:codeframe/core/credentials.py:

LLM Provider Validation

• validate_anthropic_key(): Test with minimal API call (e.g., list models)
• validate_openai_key(): Test with minimal API call
• Return validation result with error details

Git Provider Validation

• validate_github_token(): Check token validity and scopes via GitHub API
• validate_gitlab_token(): Similar for GitLab
• Verify required permissions (repo access, PR creation)

Generic Validation

• validate_credential_format(): Check format/pattern requirements
• check_expiration(): Verify credential hasn't expired

Phase 3: Integration Framework

3.1 Integrate with Configuration System

Modify file:codeframe/core/config.py:

GlobalConfig Class Updates

• Add _credential_manager property
• Modify property accessors for API keys to use CredentialManager
• anthropic_api_key property: Check env var first, then credential manager
• openai_api_key property: Same pattern
• github_token property: Same pattern
• Maintain backward compatibility with direct environment variable access

Credential Manager Integration

• Initialize CredentialManager in GlobalConfig.__init__()
• Add get_credential(provider, name) method to GlobalConfig
• Add validate_credentials_for_sprint(sprint) method
• Extend validate_required_for_sprint() to check credential availability

3.2 Update LLM Provider Adapters

Modify file:codeframe/providers/anthropic.py:

AnthropicProvider Constructor

• Accept optional credential_manager parameter
• If not provided, fall back to direct API key parameter
• Retrieve API key from credential manager if available
• Maintain backward compatibility with existing code

Error Handling Enhancement

• Catch AuthenticationError and provide helpful message
• Suggest running codeframe auth setup if credential invalid
• Log credential source for debugging

Modify file:codeframe/providers/sdk_client.py:

• Similar integration pattern for SDK client
• Ensure environment variable is set from credential manager

3.3 Update Git Integration

Modify file:codeframe/git/github_integration.py:

GitHubIntegration Constructor

• Accept optional credential_manager parameter
• Retrieve GitHub token from credential manager if available
• Fall back to direct token parameter for backward compatibility

Token Validation

• Add validate_token() method to check token before operations
• Call validation before creating PRs or other operations
• Provide clear error messages if token invalid or lacks permissions

3.4 Add Proactive Validation

Create file:codeframe/core/credential_validator.py:

Pre-Workflow Validation

• validate_workflow_credentials(workflow_type): Check all required credentials
• For PRD generation: Validate LLM provider credentials
• For task execution: Validate LLM and Git credentials
• For PR operations: Validate GitHub token and permissions
• Return validation report with missing/invalid credentials

Integration Points

• Call validation in codeframe work start before launching agents
• Call validation in codeframe tasks generate before PRD processing
• Call validation in PR creation commands
• Fail fast with clear error messages if credentials missing

Phase 4: Security & Validation

4.1 Implement Encryption at Rest

In file:codeframe/core/credentials.py:

Encryption Key Management

• Generate machine-specific encryption key on first use
• Store salt in ~/.codeframe/salt with 600 permissions
• Derive key using PBKDF2 with machine ID + salt
• Never store raw encryption key on disk

Encrypted File Format

• JSON structure: {"version": 1, "credentials": [...]}
• Each credential encrypted individually with Fernet
• Include IV/nonce for each encrypted value
• File permissions enforced on every write

4.2 Add Access Controls

Permission Validation

• Check file permissions on credential files (must be 600)
• Warn if permissions too permissive
• Auto-fix permissions on write operations

Scope Validation

• Store required scopes in credential metadata
• Validate actual scopes match required scopes
• For GitHub: Check token has repo scope for PR operations

4.3 Implement Audit Logging

Create file:codeframe/core/credential_audit.py:

Audit Log Structure

• Log file: ~/.codeframe/logs/credential_audit.log
• Entries: timestamp, action, provider, user, result
• Actions: store, retrieve, delete, rotate, validate
• Never log credential values, only metadata

Audit Events

• Log all credential operations
• Include success/failure status
• Include source IP/hostname for remote operations
• Rotate log files to prevent unbounded growth

4.4 Security Best Practices

Compliance Checks

• Validate credential strength (e.g., minimum length)
• Check for common patterns (e.g., test keys, placeholder values)
• Warn about credentials in environment variables in production
• Recommend keyring over file storage when available

Secure Deletion

• Overwrite credential values before deletion
• Use os.urandom() to overwrite file contents
• Multiple overwrite passes for sensitive data

Phase 5: Testing & Documentation

5.1 Comprehensive Test Coverage

Create test files:

tests/core/test_credentials.py

• Test credential storage and retrieval
• Test encryption/decryption
• Test keyring fallback behavior
• Test environment variable override
• Test credential validation
• Test rotation and deletion
• Mock keyring availability for testing both paths

tests/cli/test_auth_credential_commands.py

• Test all CLI commands with mocked credential manager
• Test interactive prompts
• Test validation flows
• Test error handling

tests/integration/test_credential_integration.py

• Test integration with LLM providers
• Test integration with Git operations
• Test end-to-end workflow with credentials
• Test credential validation before operations

5.2 Documentation Updates

Update README.md

• Add credential management section
• Document codeframe auth commands
• Provide setup examples for different providers

Create docs/CREDENTIAL_MANAGEMENT.md

• Comprehensive guide to credential management
• Security best practices
• Troubleshooting common issues
• Migration guide from environment variables

Update .env.example

• Add comments about credential manager as alternative
• Document environment variable override behavior

Sequence Diagram

sequenceDiagram
    participant User
    participant CLI as CLI Commands
    participant CM as CredentialManager
    participant Store as Storage Backend
    participant Provider as LLM/Git Provider
    
    User->>CLI: codeframe auth setup
    CLI->>User: Prompt for provider & credentials
    User->>CLI: Enter credentials
    CLI->>CM: validate_credential(provider, value)
    CM->>Provider: Test API call
    Provider-->>CM: Validation result
    CM-->>CLI: Valid/Invalid
    CLI->>CM: set_credential(provider, value)
    CM->>Store: Encrypt & store
    Store-->>CM: Success
    CM-->>CLI: Stored
    CLI-->>User: ✓ Credentials configured
    
    User->>CLI: codeframe work start <task>
    CLI->>CM: validate_workflow_credentials()
    CM->>Store: Retrieve credentials
    Store-->>CM: Encrypted credentials
    CM->>CM: Decrypt credentials
    CM->>Provider: Validate each credential
    Provider-->>CM: All valid
    CM-->>CLI: Validation passed
    CLI->>Provider: Execute workflow with credentials
    Provider-->>CLI: Workflow results
    CLI-->>User: Task completed

Loading

Integration Points

Existing Components to Modify

1. file:codeframe/core/config.py

   • Add CredentialManager integration
   • Update property accessors for API keys
   • Add credential validation methods

2. file:codeframe/providers/anthropic.py

   • Accept credential_manager parameter
   • Retrieve API key from credential manager
   • Enhanced error messages

3. file:codeframe/providers/sdk_client.py

   • Similar integration as AnthropicProvider
   • Ensure environment variable set from credential manager

4. file:codeframe/git/github_integration.py

   • Accept credential_manager parameter
   • Add token validation method
   • Retrieve token from credential manager

5. file:codeframe/cli/auth_commands.py

   • Add new credential management commands
   • Extend existing auth command group

New Components to Create

1. file:codeframe/core/credentials.py

   • CredentialProvider enum
   • Credential model
   • CredentialStore class
   • CredentialManager class
   • Validation functions

2. file:codeframe/core/credential_validator.py

   • Pre-workflow validation
   • Provider-specific validators
   • Validation reporting

3. file:codeframe/core/credential_audit.py

   • Audit logging
   • Log rotation
   • Security event tracking

Backward Compatibility

• Environment variables continue to work and take precedence
• Existing code using direct API key parameters remains functional
• Credential manager is optional dependency for existing workflows
• Migration path: Users can continue using env vars or adopt credential manager

Security Considerations

• Platform-native keyring preferred over file storage
• Fernet encryption for file-based storage
• File permissions enforced (600)
• Audit logging for all credential operations
• No credential values in logs
• Secure deletion with overwrite
• Environment variable override for CI/CD compatibility

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase currently has basic JWT authentication for user sessions stored in `~/.codeframe/credentials.json` with file permissions (600). LLM provider API keys (Anthropic, OpenAI) and GitHub tokens are read directly from environment variables via `file:codeframe/core/config.py`. No encryption, keyring integration, or comprehensive credential management exists. The project already includes `python-jose[cryptography]` for JWT handling, which can be leveraged for encryption. The existing auth module at `file:codeframe/cli/auth.py` provides a foundation for credential storage patterns.

## Approach

The implementation will create a new credential management system in `file:codeframe/core/credentials.py` that provides encrypted storage with platform-native keyring integration as the primary method and encrypted file storage as fallback. New CLI commands under `codeframe auth` will manage credentials for multiple provider types (LLM, Git, CI/CD, Database). The system will integrate with existing components by modifying `file:codeframe/core/config.py` to use the credential manager, updating LLM providers (`file:codeframe/providers/anthropic.py`, `file:codeframe/providers/sdk_client.py`) and Git integration (`file:codeframe/git/github_integration.py`) to retrieve credentials through the manager. This approach maintains backward compatibility with environment variables while adding comprehensive management capabilities.

## Implementation Steps

### Phase 1: Secure Credential Storage

#### 1.1 Create Core Credential Manager Module

Create `file:codeframe/core/credentials.py` with the following components:

**CredentialProvider Enum**
- Define provider types: `LLM_ANTHROPIC`, `LLM_OPENAI`, `GIT_GITHUB`, `GIT_GITLAB`, `CICD_GENERIC`, `DATABASE`
- Each provider type maps to specific credential requirements

**Credential Model**
- Use Pydantic model with fields: `provider`, `name`, `value`, `metadata`, `created_at`, `expires_at`
- Support for credential scopes and permissions in metadata
- Validation for required fields per provider type

**CredentialStore Class**
- Primary storage: Platform-native keyring using `keyring` library
- Fallback storage: Encrypted JSON file at `~/.codeframe/credentials.encrypted`
- Encryption using `cryptography.fernet` with key derived from machine-specific identifier
- Methods: `store()`, `retrieve()`, `delete()`, `list_providers()`
- Automatic fallback detection: Try keyring first, fall back to encrypted file if unavailable

**Encryption Implementation**
- Generate encryption key from machine ID + salt stored in `~/.codeframe/salt`
- Use Fernet symmetric encryption for credential values
- Store encrypted credentials with IV/nonce for security
- File permissions: 600 (owner read/write only)

#### 1.2 Add Dependencies

Update `file:pyproject.toml` dependencies:
- Add `keyring>=24.0.0` for platform-native credential storage
- Add `cryptography>=41.0.0` for Fernet encryption (already included via python-jose, but make explicit)
- These libraries provide cross-platform secure storage

#### 1.3 Implement Credential Manager

Create `CredentialManager` class in `file:codeframe/core/credentials.py`:

**Initialization**
- Detect available storage backend (keyring vs encrypted file)
- Initialize encryption keys if using file storage
- Create credential directory structure if needed

**Core Methods**
- `set_credential(provider, name, value, metadata)`: Store credential with validation
- `get_credential(provider, name)`: Retrieve credential with environment variable override
- `delete_credential(provider, name)`: Remove credential securely
- `list_credentials()`: Return list of configured providers (not values)
- `validate_credential(provider, name)`: Test credential health
- `rotate_credential(provider, name, new_value)`: Secure rotation with audit trail

**Environment Variable Override**
- Check environment variables first (e.g., `ANTHROPIC_API_KEY`)
- Fall back to stored credentials if env var not set
- Log source of credential for debugging

### Phase 2: CLI Management Interface

#### 2.1 Extend Auth Commands Module

Modify `file:codeframe/cli/auth_commands.py` to add new credential management commands:

**`codeframe auth setup` Command**
- Interactive wizard for configuring credentials
- Prompt for provider type selection (LLM, Git, CI/CD, Database)
- Provider-specific prompts (e.g., API key for Anthropic, token for GitHub)
- Validate credentials immediately after entry
- Store securely using CredentialManager
- Display success confirmation with masked credential preview

**`codeframe auth list` Command**
- Display table of configured providers using Rich library
- Show: provider type, name, status (valid/expired/unknown), last validated
- Mask credential values (show only first/last 4 characters)
- Indicate source (environment variable vs stored)
- Group by provider type for clarity

**`codeframe auth validate <provider>` Command**
- Test credential health for specific provider
- For LLM providers: Make test API call with minimal token usage
- For GitHub: Verify token scopes and permissions
- Display validation results with detailed error messages
- Update last validated timestamp in metadata
- Exit code 0 for valid, 1 for invalid

**`codeframe auth rotate <provider>` Command**
- Prompt for new credential value
- Validate new credential before replacing old one
- Atomic replacement (store new, delete old only if successful)
- Log rotation event for audit trail
- Support for `--force` flag to skip validation

**`codeframe auth remove <provider>` Command**
- Confirm deletion with prompt (unless `--yes` flag)
- Remove credential from storage
- Clear any cached values
- Log removal event for audit trail

#### 2.2 Add Validation Helpers

Create validation functions in `file:codeframe/core/credentials.py`:

**LLM Provider Validation**
- `validate_anthropic_key()`: Test with minimal API call (e.g., list models)
- `validate_openai_key()`: Test with minimal API call
- Return validation result with error details

**Git Provider Validation**
- `validate_github_token()`: Check token validity and scopes via GitHub API
- `validate_gitlab_token()`: Similar for GitLab
- Verify required permissions (repo access, PR creation)

**Generic Validation**
- `validate_credential_format()`: Check format/pattern requirements
- `check_expiration()`: Verify credential hasn't expired

### Phase 3: Integration Framework

#### 3.1 Integrate with Configuration System

Modify `file:codeframe/core/config.py`:

**GlobalConfig Class Updates**
- Add `_credential_manager` property
- Modify property accessors for API keys to use CredentialManager
- `anthropic_api_key` property: Check env var first, then credential manager
- `openai_api_key` property: Same pattern
- `github_token` property: Same pattern
- Maintain backward compatibility with direct environment variable access

**Credential Manager Integration**
- Initialize CredentialManager in `GlobalConfig.__init__()`
- Add `get_credential(provider, name)` method to GlobalConfig
- Add `validate_credentials_for_sprint(sprint)` method
- Extend `validate_required_for_sprint()` to check credential availability

#### 3.2 Update LLM Provider Adapters

Modify `file:codeframe/providers/anthropic.py`:

**AnthropicProvider Constructor**
- Accept optional `credential_manager` parameter
- If not provided, fall back to direct API key parameter
- Retrieve API key from credential manager if available
- Maintain backward compatibility with existing code

**Error Handling Enhancement**
- Catch `AuthenticationError` and provide helpful message
- Suggest running `codeframe auth setup` if credential invalid
- Log credential source for debugging

Modify `file:codeframe/providers/sdk_client.py`:
- Similar integration pattern for SDK client
- Ensure environment variable is set from credential manager

#### 3.3 Update Git Integration

Modify `file:codeframe/git/github_integration.py`:

**GitHubIntegration Constructor**
- Accept optional `credential_manager` parameter
- Retrieve GitHub token from credential manager if available
- Fall back to direct token parameter for backward compatibility

**Token Validation**
- Add `validate_token()` method to check token before operations
- Call validation before creating PRs or other operations
- Provide clear error messages if token invalid or lacks permissions

#### 3.4 Add Proactive Validation

Create `file:codeframe/core/credential_validator.py`:

**Pre-Workflow Validation**
- `validate_workflow_credentials(workflow_type)`: Check all required credentials
- For PRD generation: Validate LLM provider credentials
- For task execution: Validate LLM and Git credentials
- For PR operations: Validate GitHub token and permissions
- Return validation report with missing/invalid credentials

**Integration Points**
- Call validation in `codeframe work start` before launching agents
- Call validation in `codeframe tasks generate` before PRD processing
- Call validation in PR creation commands
- Fail fast with clear error messages if credentials missing

### Phase 4: Security & Validation

#### 4.1 Implement Encryption at Rest

In `file:codeframe/core/credentials.py`:

**Encryption Key Management**
- Generate machine-specific encryption key on first use
- Store salt in `~/.codeframe/salt` with 600 permissions
- Derive key using PBKDF2 with machine ID + salt
- Never store raw encryption key on disk

**Encrypted File Format**
- JSON structure: `{"version": 1, "credentials": [...]}`
- Each credential encrypted individually with Fernet
- Include IV/nonce for each encrypted value
- File permissions enforced on every write

#### 4.2 Add Access Controls

**Permission Validation**
- Check file permissions on credential files (must be 600)
- Warn if permissions too permissive
- Auto-fix permissions on write operations

**Scope Validation**
- Store required scopes in credential metadata
- Validate actual scopes match required scopes
- For GitHub: Check token has `repo` scope for PR operations

#### 4.3 Implement Audit Logging

Create `file:codeframe/core/credential_audit.py`:

**Audit Log Structure**
- Log file: `~/.codeframe/logs/credential_audit.log`
- Entries: timestamp, action, provider, user, result
- Actions: store, retrieve, delete, rotate, validate
- Never log credential values, only metadata

**Audit Events**
- Log all credential operations
- Include success/failure status
- Include source IP/hostname for remote operations
- Rotate log files to prevent unbounded growth

#### 4.4 Security Best Practices

**Compliance Checks**
- Validate credential strength (e.g., minimum length)
- Check for common patterns (e.g., test keys, placeholder values)
- Warn about credentials in environment variables in production
- Recommend keyring over file storage when available

**Secure Deletion**
- Overwrite credential values before deletion
- Use `os.urandom()` to overwrite file contents
- Multiple overwrite passes for sensitive data

### Phase 5: Testing & Documentation

#### 5.1 Comprehensive Test Coverage

Create test files:

**`tests/core/test_credentials.py`**
- Test credential storage and retrieval
- Test encryption/decryption
- Test keyring fallback behavior
- Test environment variable override
- Test credential validation
- Test rotation and deletion
- Mock keyring availability for testing both paths

**`tests/cli/test_auth_credential_commands.py`**
- Test all CLI commands with mocked credential manager
- Test interactive prompts
- Test validation flows
- Test error handling

**`tests/integration/test_credential_integration.py`**
- Test integration with LLM providers
- Test integration with Git operations
- Test end-to-end workflow with credentials
- Test credential validation before operations

#### 5.2 Documentation Updates

**Update `README.md`**
- Add credential management section
- Document `codeframe auth` commands
- Provide setup examples for different providers

**Create `docs/CREDENTIAL_MANAGEMENT.md`**
- Comprehensive guide to credential management
- Security best practices
- Troubleshooting common issues
- Migration guide from environment variables

**Update `.env.example`**
- Add comments about credential manager as alternative
- Document environment variable override behavior

## Sequence Diagram

```mermaid
sequenceDiagram
    participant User
    participant CLI as CLI Commands
    participant CM as CredentialManager
    participant Store as Storage Backend
    participant Provider as LLM/Git Provider
    
    User->>CLI: codeframe auth setup
    CLI->>User: Prompt for provider & credentials
    User->>CLI: Enter credentials
    CLI->>CM: validate_credential(provider, value)
    CM->>Provider: Test API call
    Provider-->>CM: Validation result
    CM-->>CLI: Valid/Invalid
    CLI->>CM: set_credential(provider, value)
    CM->>Store: Encrypt & store
    Store-->>CM: Success
    CM-->>CLI: Stored
    CLI-->>User: ✓ Credentials configured
    
    User->>CLI: codeframe work start <task>
    CLI->>CM: validate_workflow_credentials()
    CM->>Store: Retrieve credentials
    Store-->>CM: Encrypted credentials
    CM->>CM: Decrypt credentials
    CM->>Provider: Validate each credential
    Provider-->>CM: All valid
    CM-->>CLI: Validation passed
    CLI->>Provider: Execute workflow with credentials
    Provider-->>CLI: Workflow results
    CLI-->>User: Task completed
```

## Integration Points

### Existing Components to Modify

1. **`file:codeframe/core/config.py`**
   - Add CredentialManager integration
   - Update property accessors for API keys
   - Add credential validation methods

2. **`file:codeframe/providers/anthropic.py`**
   - Accept credential_manager parameter
   - Retrieve API key from credential manager
   - Enhanced error messages

3. **`file:codeframe/providers/sdk_client.py`**
   - Similar integration as AnthropicProvider
   - Ensure environment variable set from credential manager

4. **`file:codeframe/git/github_integration.py`**
   - Accept credential_manager parameter
   - Add token validation method
   - Retrieve token from credential manager

5. **`file:codeframe/cli/auth_commands.py`**
   - Add new credential management commands
   - Extend existing auth command group

### New Components to Create

1. **`file:codeframe/core/credentials.py`**
   - CredentialProvider enum
   - Credential model
   - CredentialStore class
   - CredentialManager class
   - Validation functions

2. **`file:codeframe/core/credential_validator.py`**
   - Pre-workflow validation
   - Provider-specific validators
   - Validation reporting

3. **`file:codeframe/core/credential_audit.py`**
   - Audit logging
   - Log rotation
   - Security event tracking

### Backward Compatibility

- Environment variables continue to work and take precedence
- Existing code using direct API key parameters remains functional
- Credential manager is optional dependency for existing workflows
- Migration path: Users can continue using env vars or adopt credential manager

### Security Considerations

- Platform-native keyring preferred over file storage
- Fernet encryption for file-based storage
- File permissions enforced (600)
- Audit logging for all credential operations
- No credential values in logs
- Secure deletion with overwrite
- Environment variable override for CI/CD compatibility

---

Execution Information

Branch: main
Commit: 81fdeee

---

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

Warning

Something went wrong while processing your request.

Reference ID: dc45e5b0-c76e-4edf-a978-b1b1d3ff8d90

Please try again or contact support if the issue persists, referencing this ID.

[frankbria]

Closed via PR #294