# Boundary Enforcement Design

This document describes the boundary enforcement system that ensures strict separation between work and family agents.

## Overview

The boundary enforcement system prevents:
- Family agent from accessing work-related data or repositories
- Work agent from modifying family-specific data
- Cross-contamination of credentials and configuration
- Unauthorized network access

## Components

### 1. Path Whitelisting

Each agent has a whitelist of allowed file system paths:

**Family Agent Allowed Paths**:
- `data/tasks/home/` - Home task Kanban board
- `data/notes/home/` - Family notes and files
- `data/conversations.db` - Conversation history
- `data/timers.db` - Timers and reminders

**Family Agent Forbidden Paths**:
- Any work repository paths
- Work-specific data directories
- System configuration outside allowed areas

**Work Agent Allowed Paths**:
- All family paths (read-only access)
- Work-specific data directories
- Broader file system access

**Work Agent Forbidden Paths**:
- Family notes (should not modify)

### 2. Tool Access Control

Tools are restricted based on agent type:

**Family Agent Tools**:
- Time/date tools
- Weather tool
- Timers and reminders
- Home task management
- Notes and files (home directory only)

**Forbidden for Family Agent**:
- Work-specific tools (email to work addresses, work calendar, etc.)
- Tools that access work repositories

### 3. Network Separation

Network access is controlled per agent:

**Family Agent Network Access**:
- Localhost only (by default)
- Can be configured for specific local networks
- No access to work-specific services

**Work Agent Network Access**:
- Localhost
- GPU VM (10.0.30.63)
- Broader network access for work needs

### 4. Config Separation

Configuration files are separated:

- **Family Agent Config**: `family-agent-config/` (separate repo)
- **Work Agent Config**: `home-voice-agent/config/work/`
- Different `.env` files with separate credentials
- No shared secrets between agents

## Implementation

### Policy Enforcement

The `BoundaryEnforcer` class provides methods to check:
- `check_path_access()` - Validate file system access
- `check_tool_access()` - Validate tool usage
- `check_network_access()` - Validate network access
- `validate_config_separation()` - Validate config isolation

### Integration Points

1. **MCP Tools**: Tools check boundaries before execution
2. **Router**: Network boundaries enforced during routing
3. **File Operations**: All file operations validated against whitelist
4. **Tool Registry**: Tools filtered based on agent type

## Static Policy Checks

For CI/CD, implement checks that:
- Validate config files don't mix work/family paths
- Reject code that grants cross-access
- Ensure path whitelists are properly enforced
- Check for hardcoded paths that bypass boundaries

## Network-Level Separation

Future enhancements:
- Container/namespace isolation
- Firewall rules preventing cross-access
- VLAN separation for work vs family networks
- Service mesh with policy enforcement

## Audit Logging

All boundary checks should be logged:
- Successful access attempts
- Denied access attempts (with reason)
- Policy violations
- Config validation results

## Security Considerations

1. **Default Deny**: Family agent defaults to deny unless explicitly allowed
2. **Principle of Least Privilege**: Each agent gets minimum required access
3. **Defense in Depth**: Multiple layers of enforcement (code, network, filesystem)
4. **Audit Trail**: All boundary checks logged for security review

## Testing

Test cases:
- Family agent accessing allowed paths ✅
- Family agent accessing forbidden paths ❌
- Work agent accessing family paths (read-only) ✅
- Work agent modifying family data ❌
- Tool access restrictions ✅
- Network access restrictions ✅
- Config separation validation ✅

## Future Enhancements

- Runtime monitoring and alerting
- Automatic policy generation from config
- Integration with container orchestration
- Advanced network policy (CIDR matching, service mesh)
- Machine learning for anomaly detection