empathy-framework 3.8.3__py3-none-any.whl → 3.9.1__py3-none-any.whl

empathy_os/config.py

@@ -26,6 +26,48 @@ except ImportError:
 from empathy_os.workflows.config import ModelConfig
 
 
+def _validate_file_path(path: str, allowed_dir: str | None = None) -> Path:
+    """Validate file path to prevent path traversal and arbitrary writes.
+
+    Args:
+        path: File path to validate
+        allowed_dir: Optional directory to restrict writes to
+
+    Returns:
+        Validated Path object
+
+    Raises:
+        ValueError: If path is invalid or unsafe
+    """
+    if not path or not isinstance(path, str):
+        raise ValueError("path must be a non-empty string")
+
+    # Check for null bytes
+    if "\x00" in path:
+        raise ValueError("path contains null bytes")
+
+    try:
+        resolved = Path(path).resolve()
+    except (OSError, RuntimeError) as e:
+        raise ValueError(f"Invalid path: {e}")
+
+    # Check if within allowed directory
+    if allowed_dir:
+        try:
+            allowed = Path(allowed_dir).resolve()
+            resolved.relative_to(allowed)
+        except ValueError:
+            raise ValueError(f"path must be within {allowed_dir}")
+
+    # Check for dangerous system paths
+    dangerous_paths = ["/etc", "/sys", "/proc", "/dev"]
+    for dangerous in dangerous_paths:
+        if str(resolved).startswith(dangerous):
+            raise ValueError(f"Cannot write to system directory: {dangerous}")
+
+    return resolved
+
+
 @dataclass
 class EmpathyConfig:
     """Configuration for EmpathyOS instance
@@ -300,9 +342,10 @@ class EmpathyConfig:
                 "PyYAML is required for YAML export. Install with: pip install pyyaml",
             )
 
+        validated_path = _validate_file_path(filepath)
         data = asdict(self)
 
-        with open(filepath, "w") as f:
+        with open(validated_path, "w") as f:
             yaml.dump(data, f, default_flow_style=False, sort_keys=False)
 
     def to_json(self, filepath: str, indent: int = 2):
@@ -317,9 +360,10 @@ class EmpathyConfig:
             >>> config.to_json("my-config.json")
 
         """
+        validated_path = _validate_file_path(filepath)
         data = asdict(self)
 
-        with open(filepath, "w") as f:
+        with open(validated_path, "w") as f:
             json.dump(data, f, indent=indent)
 
     def to_dict(self) -> dict[str, Any]:

empathy_os/memory/control_panel.py

@@ -124,8 +124,9 @@ def _validate_agent_id(agent_id: str) -> bool:
     if not agent_id or not isinstance(agent_id, str):
         return False
 
-    # Check for dangerous characters
-    if any(c in agent_id for c in [".", "/", "\\", "\x00", ";", "|", "&"]):
+    # Check for dangerous characters (path separators, null bytes, command injection)
+    # Note: "." and "@" are allowed for email-style user IDs
+    if any(c in agent_id for c in ["/", "\\", "\x00", ";", "|", "&"]):
         return False
 
     # Check length bounds
@@ -153,10 +154,70 @@ def _validate_classification(classification: str | None) -> bool:
     return classification.upper() in ("PUBLIC", "INTERNAL", "SENSITIVE")
 
 
+def _validate_file_path(path: str, allowed_dir: str | None = None) -> Path:
+    """Validate file path to prevent path traversal and arbitrary writes.
+
+    Args:
+        path: Path to validate
+        allowed_dir: Optional directory that must contain the path
+
+    Returns:
+        Resolved absolute Path object
+
+    Raises:
+        ValueError: If path is invalid or outside allowed directory
+
+    """
+    if not path or not isinstance(path, str):
+        raise ValueError("path must be a non-empty string")
+
+    # Check for null bytes
+    if "\x00" in path:
+        raise ValueError("path contains null bytes")
+
+    try:
+        # Resolve to absolute path
+        resolved = Path(path).resolve()
+    except (OSError, RuntimeError) as e:
+        raise ValueError(f"Invalid path: {e}")
+
+    # Check if within allowed directory
+    if allowed_dir:
+        try:
+            allowed = Path(allowed_dir).resolve()
+            resolved.relative_to(allowed)
+        except ValueError:
+            raise ValueError(f"path must be within {allowed_dir}")
+
+    # Check for dangerous system paths
+    dangerous_paths = ["/etc", "/sys", "/proc", "/dev"]
+    for dangerous in dangerous_paths:
+        if str(resolved).startswith(dangerous):
+            raise ValueError(f"Cannot write to system directory: {dangerous}")
+
+    return resolved
+
+
 class RateLimiter:
     """Simple in-memory rate limiter by IP address."""
 
     def __init__(self, window_seconds: int = 60, max_requests: int = 100):
+        """Initialize rate limiter.
+
+        Args:
+            window_seconds: Time window in seconds
+            max_requests: Maximum requests allowed per window
+
+        Raises:
+            ValueError: If window_seconds or max_requests is invalid
+
+        """
+        if window_seconds < 1:
+            raise ValueError(f"window_seconds must be positive, got {window_seconds}")
+
+        if max_requests < 1:
+            raise ValueError(f"max_requests must be positive, got {max_requests}")
+
         self.window_seconds = window_seconds
         self.max_requests = max_requests
         self._requests: dict[str, list[float]] = defaultdict(list)
@@ -406,8 +467,9 @@ class MemoryControlPanel:
                 stats.storage_bytes = sum(
                     f.stat().st_size for f in storage_path.glob("**/*") if f.is_file()
                 )
-            except Exception:
-                pass
+            except Exception as e:
+                logger.debug("storage_size_calculation_failed", error=str(e))
+                stats.storage_bytes = 0
 
             try:
                 long_term = self._get_long_term()
@@ -439,7 +501,24 @@ class MemoryControlPanel:
         Returns:
             List of pattern summaries
 
+        Raises:
+            ValueError: If classification is invalid or limit is out of range
+
         """
+        # Validate classification
+        if not _validate_classification(classification):
+            raise ValueError(
+                f"Invalid classification '{classification}'. "
+                f"Must be PUBLIC, INTERNAL, or SENSITIVE."
+            )
+
+        # Validate limit range
+        if limit < 1:
+            raise ValueError(f"limit must be positive, got {limit}")
+
+        if limit > 10000:
+            raise ValueError(f"limit too large (max 10000), got {limit}")
+
         long_term = self._get_long_term()
 
         class_filter = None
@@ -464,13 +543,24 @@ class MemoryControlPanel:
         Returns:
             True if deleted
 
+        Raises:
+            ValueError: If pattern_id or user_id format is invalid
+
         """
+        # Validate pattern_id
+        if not _validate_pattern_id(pattern_id):
+            raise ValueError(f"Invalid pattern_id format: {pattern_id}")
+
+        # Validate user_id (reuse agent_id validation - same format)
+        if not _validate_agent_id(user_id):
+            raise ValueError(f"Invalid user_id format: {user_id}")
+
         long_term = self._get_long_term()
         try:
             return long_term.delete_pattern(pattern_id, user_id)
         except Exception as e:
             logger.error("delete_pattern_failed", pattern_id=pattern_id, error=str(e))
-            return False
+            return False  # Graceful degradation - validation errors raise, storage errors return False
 
     def clear_short_term(self, agent_id: str = "admin") -> int:
         """Clear all short-term memory for an agent.
@@ -481,7 +571,14 @@ class MemoryControlPanel:
         Returns:
             Number of keys deleted
 
+        Raises:
+            ValueError: If agent_id format is invalid
+
         """
+        # Validate agent_id
+        if not _validate_agent_id(agent_id):
+            raise ValueError(f"Invalid agent_id format: {agent_id}")
+
         memory = self._get_short_term()
         creds = AgentCredentials(agent_id=agent_id, tier=AccessTier.STEWARD)
         return memory.clear_working_memory(creds)
@@ -496,7 +593,20 @@ class MemoryControlPanel:
         Returns:
             Number of patterns exported
 
+        Raises:
+            ValueError: If output_path is invalid, classification invalid, or path is unsafe
+
         """
+        # Validate file path to prevent path traversal attacks
+        validated_path = _validate_file_path(output_path)
+
+        # Validate classification (list_patterns will also validate, but do it early)
+        if not _validate_classification(classification):
+            raise ValueError(
+                f"Invalid classification '{classification}'. "
+                f"Must be PUBLIC, INTERNAL, or SENSITIVE."
+            )
+
         patterns = self.list_patterns(classification=classification)
 
         export_data = {
@@ -506,7 +616,7 @@ class MemoryControlPanel:
             "patterns": patterns,
         }
 
-        with open(output_path, "w") as f:
+        with open(validated_path, "w") as f:
             json.dump(export_data, f, indent=2)
 
         return len(patterns)
@@ -605,11 +715,21 @@ class MemoryControlPanel:
         return self._long_term
 
     def _count_patterns(self) -> int:
-        """Count patterns in storage."""
+        """Count patterns in storage.
+
+        Returns:
+            Number of pattern files, or 0 if counting fails
+
+        """
         storage_path = Path(self.config.storage_dir)
         if not storage_path.exists():
             return 0
-        return len(list(storage_path.glob("*.json")))
+
+        try:
+            return len(list(storage_path.glob("*.json")))
+        except (OSError, PermissionError) as e:
+            logger.debug("pattern_count_failed", error=str(e))
+            return 0
 
 
 def print_status(panel: MemoryControlPanel):

empathy_os/memory/long_term.py

@@ -540,7 +540,8 @@ class SecureMemDocsIntegration:
 
         Raises:
             SecurityError: If secrets detected or security policy violated
-            ValueError: If invalid classification specified
+            ValueError: If content/pattern_type/user_id empty or invalid classification
+            TypeError: If custom_metadata is not dict
 
         Example:
             >>> result = integration.store_pattern(
@@ -559,9 +560,17 @@ class SecureMemDocsIntegration:
         )
 
         try:
-            # Validate content
+            # Pattern 1: String ID validation
             if not content or not content.strip():
-                raise ValueError("Content cannot be empty")
+                raise ValueError("content cannot be empty")
+            if not pattern_type or not pattern_type.strip():
+                raise ValueError("pattern_type cannot be empty")
+            if not user_id or not user_id.strip():
+                raise ValueError("user_id cannot be empty")
+
+            # Pattern 5: Type validation
+            if custom_metadata is not None and not isinstance(custom_metadata, dict):
+                raise TypeError(f"custom_metadata must be dict, got {type(custom_metadata).__name__}")
 
             # Step 1 & 2: PII Scrubbing + Secrets Detection (PARALLEL for performance)
             # Run both operations in parallel since they're independent
@@ -759,7 +768,7 @@ class SecureMemDocsIntegration:
 
         Raises:
             PermissionError: If access denied
-            ValueError: If pattern not found or retention expired
+            ValueError: If pattern_id/user_id empty, pattern not found, or retention expired
             SecurityError: If decryption fails
 
         Example:
@@ -770,6 +779,12 @@ class SecureMemDocsIntegration:
             >>> print(pattern["content"])
 
         """
+        # Pattern 1: String ID validation
+        if not pattern_id or not pattern_id.strip():
+            raise ValueError("pattern_id cannot be empty")
+        if not user_id or not user_id.strip():
+            raise ValueError("user_id cannot be empty")
+
         logger.info(
             "retrieve_pattern_started",
             pattern_id=pattern_id,
@@ -1108,8 +1123,15 @@ class SecureMemDocsIntegration:
 
         Raises:
             PermissionError: If user doesn't have permission to delete
+            ValueError: If pattern_id or user_id is empty
 
         """
+        # Pattern 1: String ID validation
+        if not pattern_id or not pattern_id.strip():
+            raise ValueError("pattern_id cannot be empty")
+        if not user_id or not user_id.strip():
+            raise ValueError("user_id cannot be empty")
+
         # Retrieve pattern to check permissions
         pattern_data = self.storage.retrieve(pattern_id)
 

empathy_os/memory/short_term.py

@@ -295,6 +295,26 @@ class StagedPattern:
     staged_at: datetime = field(default_factory=datetime.now)
     interests: list[str] = field(default_factory=list)  # For negotiation
 
+    def __post_init__(self):
+        """Validate fields after initialization"""
+        # Pattern 1: String ID validation
+        if not self.pattern_id or not self.pattern_id.strip():
+            raise ValueError("pattern_id cannot be empty")
+        if not self.agent_id or not self.agent_id.strip():
+            raise ValueError("agent_id cannot be empty")
+        if not self.pattern_type or not self.pattern_type.strip():
+            raise ValueError("pattern_type cannot be empty")
+
+        # Pattern 4: Range validation for confidence
+        if not 0.0 <= self.confidence <= 1.0:
+            raise ValueError(f"confidence must be between 0.0 and 1.0, got {self.confidence}")
+
+        # Pattern 5: Type validation
+        if not isinstance(self.context, dict):
+            raise TypeError(f"context must be dict, got {type(self.context).__name__}")
+        if not isinstance(self.interests, list):
+            raise TypeError(f"interests must be list, got {type(self.interests).__name__}")
+
     def to_dict(self) -> dict:
         return {
             "pattern_id": self.pattern_id,
@@ -619,10 +639,18 @@ class RedisShortTermMemory:
         Returns:
             True if successful
 
+        Raises:
+            ValueError: If key is empty or invalid
+            PermissionError: If credentials lack write access
+
         Example:
             >>> memory.stash("analysis_v1", {"findings": [...]}, creds)
 
         """
+        # Pattern 1: String ID validation
+        if not key or not key.strip():
+            raise ValueError("key cannot be empty")
+
         if not credentials.can_stage():
             raise PermissionError(
                 f"Agent {credentials.agent_id} (Tier {credentials.tier.name}) "
@@ -653,10 +681,17 @@ class RedisShortTermMemory:
         Returns:
             Retrieved data or None if not found
 
+        Raises:
+            ValueError: If key is empty or invalid
+
         Example:
             >>> data = memory.retrieve("analysis_v1", creds)
 
         """
+        # Pattern 1: String ID validation
+        if not key or not key.strip():
+            raise ValueError("key cannot be empty")
+
         owner = agent_id or credentials.agent_id
         full_key = f"{self.PREFIX_WORKING}{owner}:{key}"
         raw = self._get(full_key)
@@ -704,7 +739,15 @@ class RedisShortTermMemory:
         Returns:
             True if staged successfully
 
+        Raises:
+            TypeError: If pattern is not StagedPattern
+            PermissionError: If credentials lack staging access
+
         """
+        # Pattern 5: Type validation
+        if not isinstance(pattern, StagedPattern):
+            raise TypeError(f"pattern must be StagedPattern, got {type(pattern).__name__}")
+
         if not credentials.can_stage():
             raise PermissionError(
                 f"Agent {credentials.agent_id} cannot stage patterns. "
@@ -732,7 +775,14 @@ class RedisShortTermMemory:
         Returns:
             StagedPattern or None
 
+        Raises:
+            ValueError: If pattern_id is empty
+
         """
+        # Pattern 1: String ID validation
+        if not pattern_id or not pattern_id.strip():
+            raise ValueError("pattern_id cannot be empty")
+
         key = f"{self.PREFIX_STAGED}{pattern_id}"
         raw = self._get(key)
 
@@ -844,7 +894,22 @@ class RedisShortTermMemory:
         Returns:
             ConflictContext for resolution
 
+        Raises:
+            ValueError: If conflict_id is empty
+            TypeError: If positions or interests are not dicts
+            PermissionError: If credentials lack permission
+
         """
+        # Pattern 1: String ID validation
+        if not conflict_id or not conflict_id.strip():
+            raise ValueError("conflict_id cannot be empty")
+
+        # Pattern 5: Type validation
+        if not isinstance(positions, dict):
+            raise TypeError(f"positions must be dict, got {type(positions).__name__}")
+        if not isinstance(interests, dict):
+            raise TypeError(f"interests must be dict, got {type(interests).__name__}")
+
         if not credentials.can_stage():
             raise PermissionError(
                 f"Agent {credentials.agent_id} cannot create conflict context. "
@@ -881,7 +946,14 @@ class RedisShortTermMemory:
         Returns:
             ConflictContext or None
 
+        Raises:
+            ValueError: If conflict_id is empty
+
         """
+        # Pattern 1: String ID validation
+        if not conflict_id or not conflict_id.strip():
+            raise ValueError("conflict_id cannot be empty")
+
         key = f"{self.PREFIX_CONFLICT}{conflict_id}"
         raw = self._get(key)
 
@@ -1014,7 +1086,19 @@ class RedisShortTermMemory:
         Returns:
             True if created
 
+        Raises:
+            ValueError: If session_id is empty
+            TypeError: If metadata is not dict
+
         """
+        # Pattern 1: String ID validation
+        if not session_id or not session_id.strip():
+            raise ValueError("session_id cannot be empty")
+
+        # Pattern 5: Type validation
+        if metadata is not None and not isinstance(metadata, dict):
+            raise TypeError(f"metadata must be dict, got {type(metadata).__name__}")
+
         key = f"{self.PREFIX_SESSION}{session_id}"
         payload = {
             "session_id": session_id,
@@ -1039,7 +1123,14 @@ class RedisShortTermMemory:
         Returns:
             True if joined
 
+        Raises:
+            ValueError: If session_id is empty
+
         """
+        # Pattern 1: String ID validation
+        if not session_id or not session_id.strip():
+            raise ValueError("session_id cannot be empty")
+
         key = f"{self.PREFIX_SESSION}{session_id}"
         raw = self._get(key)
 
@@ -1164,11 +1255,19 @@ class RedisShortTermMemory:
         Returns:
             Number of items successfully stashed
 
+        Raises:
+            TypeError: If items is not a list
+            PermissionError: If credentials lack write access
+
         Example:
             >>> items = [("key1", {"a": 1}), ("key2", {"b": 2})]
             >>> count = memory.stash_batch(items, creds)
 
         """
+        # Pattern 5: Type validation
+        if not isinstance(items, list):
+            raise TypeError(f"items must be list, got {type(items).__name__}")
+
         if not credentials.can_stage():
             raise PermissionError(
                 f"Agent {credentials.agent_id} cannot write to memory. "
@@ -2042,12 +2141,23 @@ class RedisShortTermMemory:
         Returns:
             Tuple of (success, pattern, message)
 
+        Raises:
+            ValueError: If pattern_id is empty or min_confidence out of range
+
         Example:
             >>> success, pattern, msg = memory.atomic_promote_pattern("pat_123", creds, min_confidence=0.7)
             >>> if success:
             ...     library.add(pattern)
 
         """
+        # Pattern 1: String ID validation
+        if not pattern_id or not pattern_id.strip():
+            raise ValueError("pattern_id cannot be empty")
+
+        # Pattern 4: Range validation
+        if not 0.0 <= min_confidence <= 1.0:
+            raise ValueError(f"min_confidence must be between 0.0 and 1.0, got {min_confidence}")
+
         if not credentials.can_validate():
             return False, None, "Requires VALIDATOR tier or higher"
 

empathy_os/models/token_estimator.py

@@ -53,7 +53,14 @@ def estimate_tokens(text: str, model_id: str = "claude-sonnet-4-5-20250514") ->
     Returns:
         Estimated token count
 
+    Raises:
+        ValueError: If model_id is empty
+
     """
+    # Pattern 1: String ID validation
+    if not model_id or not model_id.strip():
+        raise ValueError("model_id cannot be empty")
+
     if not text:
         return 0
 
@@ -99,9 +106,18 @@ def estimate_workflow_cost(
             "risk": "low" | "medium" | "high"
         }
 
+    Raises:
+        ValueError: If workflow_name or provider is empty
+
     """
     from .registry import get_model, get_supported_providers
 
+    # Pattern 1: String ID validation
+    if not workflow_name or not workflow_name.strip():
+        raise ValueError("workflow_name cannot be empty")
+    if not provider or not provider.strip():
+        raise ValueError("provider cannot be empty")
+
     # Validate provider
     if provider not in get_supported_providers():
         provider = "anthropic"  # Default fallback
@@ -292,10 +308,19 @@ def estimate_single_call_cost(
     Returns:
         Cost estimate dictionary
 
+    Raises:
+        ValueError: If task_type or provider is empty
+
     """
     from .registry import get_model
     from .tasks import get_tier_for_task
 
+    # Pattern 1: String ID validation
+    if not task_type or not task_type.strip():
+        raise ValueError("task_type cannot be empty")
+    if not provider or not provider.strip():
+        raise ValueError("provider cannot be empty")
+
     input_tokens = estimate_tokens(text)
 
     # Get tier for task