stack/docs/scratchpads/360-federation-isolation.md

# Issue #360: Federation Credential Isolation

## Objective

Ensure user credentials never leak across federation boundaries by adding explicit deny-lists in federation query and command services.

## Current Architecture

### Federation System

- **QueryService**: Handles federated queries (tasks, events, projects)
- **CommandService**: Handles federated commands (agent spawning)
- **CryptoService**: AES-256-GCM encryption for federation private keys
- **Instance Model**: Stores federation instance identity with encrypted private keys

### Credential System

- **UserCredential Model**: Stores encrypted credentials with VaultService
- **VaultService**: OpenBao Transit encryption with fallback to CryptoService
- **TransitKey.CREDENTIALS**: Separate key for user credentials
- **TransitKey.FEDERATION**: Separate key for federation keys

## Implementation Plan

### Phase 1: QueryService Isolation

1. Add deny-list to prevent UserCredential queries
2. Test that credential queries are blocked
3. Test that other entity types still work

### Phase 2: CommandService Isolation

1. Add deny-list to prevent credential operations
2. Test that credential commands are blocked
3. Test that agent commands still work

### Phase 3: Message Payload Verification

1. Review FederationMessage payloads
2. Ensure no credential data in transit
3. Add integration tests

### Phase 4: Documentation

1. Document isolation guarantees
2. Document Transit key separation
3. Update security architecture docs

## Progress

- [x] Read issue details
- [x] Review existing federation code
- [x] Review VaultService integration
- [x] Create scratchpad
- [x] Implement QueryService deny-list
- [x] Implement CommandService deny-list
- [x] Add integration tests
- [x] Document guarantees
- [x] Run full test suite (377 tests pass)

## Key Findings

1. **Transit Key Separation Already in Place**:
   - `TransitKey.CREDENTIALS` for user credentials
   - `TransitKey.FEDERATION` for federation private keys
   - Each federated instance has its own OpenBao instance
   - Even if one key is compromised, credentials are isolated

2. **Current Federation Capabilities**:
   - QueryService: tasks, events, projects (NO credential queries)
   - CommandService: agent.\* commands only (NO CRUD operations)

3. **No Existing Credential Exposure**:
   - Federation private keys use CryptoService (old implementation)
   - User credentials use VaultService with TransitKey.CREDENTIALS
   - No overlap in encryption keys or services

## Testing Strategy

### Unit Tests

1. QueryService rejects credential entity type
2. CommandService rejects credential operations
3. Verify existing queries still work

### Integration Tests

1. Federated query for credentials returns denied
2. Federated command for credentials returns denied
3. Federation messages contain no credential data

## Notes

- Issue correctly identifies that the transit key isolation already provides defense-in-depth
- Implementation adds explicit application-layer deny-lists as additional protection
- Federation system currently has NO access to credentials module - adding explicit blocks as safety

## Implementation Summary

### Files Modified

1. **apps/api/src/federation/query.service.ts**
   - Added `isCredentialQuery()` method to detect credential-related keywords
   - Modified `processQuery()` to block credential queries before routing
   - Throws error: "Credential queries are not allowed via federation"

2. **apps/api/src/federation/command.service.ts**
   - Added `isCredentialCommand()` method to detect credential operation commands
   - Modified `handleIncomingCommand()` to block credential commands before execution
   - Throws CommandProcessingError: "Credential operations are not allowed via federation"

3. **apps/api/src/federation/query.service.spec.ts**
   - Added 2 test cases for credential query blocking
   - Tests single and multiple credential-related keywords
   - Verifies case-insensitive matching

4. **apps/api/src/federation/command.service.spec.ts**
   - Added 3 test cases for credential command blocking
   - Tests multiple credential operations
   - Verifies case-insensitive matching and agent commands still work

5. **apps/api/src/federation/credential-isolation.integration.spec.ts** (NEW)
   - 8 integration tests covering end-to-end isolation
   - Tests query isolation, command isolation, and defense-in-depth architecture
   - Documents architectural guarantees

6. **docs/security/federation-credential-isolation.md** (NEW)
   - Comprehensive security documentation
   - 4 security guarantees (G1-G4)
   - Testing strategy and incident response procedures

### Test Coverage

- **Unit Tests**: 22 tests in query.service.spec.ts (all passing)
- **Unit Tests**: 22 tests in command.service.spec.ts (all passing)
- **Integration Tests**: 8 tests in credential-isolation.integration.spec.ts (all passing)
- **Regression Tests**: 377 total federation tests (all passing)

### Security Guarantees Implemented

1. **G1: Credential Confidentiality** - Credentials never leave instance in plaintext
2. **G2: Cross-Instance Isolation** - Compromised key on one instance doesn't affect others
3. **G3: Query/Command Isolation** - Federated instances cannot query/modify credentials
4. **G4: Accidental Exposure Prevention** - Credentials cannot leak via messages

### Blocked Operations

**Queries:**

- Any query containing: credential, user_credential, api_key, secret, token, password, oauth, access_token

**Commands:**

- Any command starting with: credential., credentials.

### Allowed Operations (Unchanged)

**Queries:**

- tasks
- events
- projects

**Commands:**

- agent.\* (spawn, terminate, etc.)