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

• Read issue details
• Review existing federation code
• Review VaultService integration
• Create scratchpad
• Implement QueryService deny-list
• Implement CommandService deny-list
• Add integration tests
• Document guarantees
• 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.)