PraisonAI 3.0.0__py3-none-any.whl

praisonai/templates/resolver.py

@@ -0,0 +1,206 @@
+"""
+Template URI Resolver
+
+Parses and resolves template URIs to their source locations.
+Supports: local paths, package refs, GitHub refs, HTTP URLs.
+"""
+
+import os
+import re
+from dataclasses import dataclass
+from enum import Enum
+from typing import Optional, Tuple
+
+
+class TemplateSource(Enum):
+    """Supported template sources."""
+    LOCAL = "local"
+    PACKAGE = "package"
+    GITHUB = "github"
+    HTTP = "http"
+
+
+@dataclass
+class ResolvedTemplate:
+    """Resolved template location."""
+    source: TemplateSource
+    path: str
+    version: Optional[str] = None
+    owner: Optional[str] = None
+    repo: Optional[str] = None
+    ref: Optional[str] = None
+    url: Optional[str] = None
+    
+    @property
+    def cache_key(self) -> str:
+        """Generate a unique cache key for this template."""
+        if self.source == TemplateSource.LOCAL:
+            return f"local/{os.path.abspath(self.path)}"
+        elif self.source == TemplateSource.PACKAGE:
+            return f"package/{self.path}"
+        elif self.source == TemplateSource.GITHUB:
+            ref = self.ref or "main"
+            return f"github/{self.owner}/{self.repo}/{self.path}@{ref}"
+        elif self.source == TemplateSource.HTTP:
+            return f"http/{self.url}"
+        return f"unknown/{self.path}"
+    
+    @property
+    def is_pinned(self) -> bool:
+        """Check if this template reference is pinned (not 'latest')."""
+        if self.source == TemplateSource.LOCAL:
+            return True  # Local is always "pinned"
+        if self.source == TemplateSource.PACKAGE:
+            return True  # Package is always "pinned" to installed version
+        if self.source == TemplateSource.GITHUB:
+            # Pinned if ref is a commit hash (40 hex chars) or a version tag
+            if self.ref and (
+                re.match(r'^[a-f0-9]{40}$', self.ref) or
+                re.match(r'^v?\d+\.\d+', self.ref)
+            ):
+                return True
+            return False
+        return False
+
+
+class TemplateResolver:
+    """
+    Resolves template URIs to their source locations.
+    
+    Supported URI formats:
+    - Local path: ./my-template, /absolute/path/template, ~/templates/my-template
+    - Package ref: package:agent_recipes/transcript-generator
+    - GitHub ref: github:owner/repo/template-name[@ref]
+    - HTTP URL: https://example.com/template.yaml
+    
+    Legacy formats (also supported):
+    - praison://local/./path
+    - praison://package/name/template
+    - praison://github/owner/repo/template@ref
+    """
+    
+    # URI patterns
+    GITHUB_PATTERN = re.compile(
+        r'^(?:github:|praison://github/)([^/]+)/([^/]+)/([^@]+)(?:@(.+))?$'
+    )
+    PACKAGE_PATTERN = re.compile(
+        r'^(?:package:|praison://package/)([^/]+)/(.+)$'
+    )
+    HTTP_PATTERN = re.compile(
+        r'^(?:https?://|praison://https?/).+'
+    )
+    LOCAL_PATTERN = re.compile(
+        r'^(?:praison://local/)?([.~]?/.+|[a-zA-Z]:\\.+)$'
+    )
+    
+    @classmethod
+    def resolve(cls, uri: str) -> ResolvedTemplate:
+        """
+        Resolve a template URI to its source location.
+        
+        Args:
+            uri: Template URI string
+            
+        Returns:
+            ResolvedTemplate with source details
+            
+        Raises:
+            ValueError: If URI format is not recognized
+        """
+        uri = uri.strip()
+        
+        # Check GitHub pattern
+        match = cls.GITHUB_PATTERN.match(uri)
+        if match:
+            owner, repo, path, ref = match.groups()
+            return ResolvedTemplate(
+                source=TemplateSource.GITHUB,
+                path=path,
+                owner=owner,
+                repo=repo,
+                ref=ref or "main"
+            )
+        
+        # Check package pattern
+        match = cls.PACKAGE_PATTERN.match(uri)
+        if match:
+            package, template = match.groups()
+            return ResolvedTemplate(
+                source=TemplateSource.PACKAGE,
+                path=f"{package}/{template}"
+            )
+        
+        # Check HTTP pattern
+        if cls.HTTP_PATTERN.match(uri):
+            # Extract actual URL
+            url = uri
+            if uri.startswith("praison://"):
+                url = uri.replace("praison://", "")
+            return ResolvedTemplate(
+                source=TemplateSource.HTTP,
+                path=url,
+                url=url
+            )
+        
+        # Check local pattern or assume local if nothing else matches
+        if cls.LOCAL_PATTERN.match(uri) or os.path.exists(uri) or uri.startswith(("./", "../", "~/")):
+            path = uri
+            if uri.startswith("praison://local/"):
+                path = uri.replace("praison://local/", "")
+            # Expand user home
+            path = os.path.expanduser(path)
+            return ResolvedTemplate(
+                source=TemplateSource.LOCAL,
+                path=path
+            )
+        
+        # Try as simple template name (assume package:agent_recipes/name)
+        if re.match(r'^[a-zA-Z][a-zA-Z0-9_-]*$', uri):
+            return ResolvedTemplate(
+                source=TemplateSource.PACKAGE,
+                path=f"agent_recipes/{uri}"
+            )
+        
+        raise ValueError(
+            f"Unrecognized template URI format: {uri}\n"
+            "Supported formats:\n"
+            "  - Local: ./path, /absolute/path, ~/path\n"
+            "  - Package: package:agent_recipes/template-name\n"
+            "  - GitHub: github:owner/repo/template[@ref]\n"
+            "  - HTTP: https://example.com/template.yaml"
+        )
+    
+    @classmethod
+    def parse_version(cls, uri: str) -> Tuple[str, Optional[str]]:
+        """
+        Extract version/ref from a URI.
+        
+        Args:
+            uri: Template URI string
+            
+        Returns:
+            Tuple of (base_uri, version)
+        """
+        if "@" in uri and not uri.startswith("http"):
+            parts = uri.rsplit("@", 1)
+            return parts[0], parts[1]
+        return uri, None
+    
+    @classmethod
+    def build_github_uri(
+        cls,
+        owner: str,
+        repo: str,
+        template: str,
+        ref: Optional[str] = None
+    ) -> str:
+        """Build a GitHub template URI."""
+        uri = f"github:{owner}/{repo}/{template}"
+        if ref:
+            uri += f"@{ref}"
+        return uri
+    
+    @classmethod
+    def build_package_uri(cls, package: str, template: str) -> str:
+        """Build a package template URI."""
+        return f"package:{package}/{template}"

praisonai/templates/security.py

@@ -0,0 +1,327 @@
+"""
+Template Security
+
+Security primitives for template validation and safe extraction.
+Includes checksum verification, allowlists, and safe path handling.
+"""
+
+import hashlib
+import os
+import re
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Set
+from dataclasses import dataclass, field
+
+
+@dataclass
+class SecurityConfig:
+    """Security configuration for template operations."""
+    
+    # Allowed template sources
+    allowed_sources: Set[str] = field(default_factory=lambda: {
+        "github:MervinPraison/agent-recipes",
+        "package:agent_recipes",
+    })
+    
+    # Allow all local paths by default
+    allow_local: bool = True
+    
+    # Allow all GitHub sources (not just allowlisted)
+    allow_any_github: bool = True
+    
+    # Allow HTTP sources
+    allow_http: bool = False
+    
+    # Require checksum verification for remote templates
+    require_checksum: bool = False
+    
+    # Maximum template size in bytes (10MB default)
+    max_template_size: int = 10 * 1024 * 1024
+    
+    # Blocked file patterns (security risk)
+    blocked_patterns: List[str] = field(default_factory=lambda: [
+        r"\.\.\/",  # Path traversal
+        r"^\/",     # Absolute paths in archives
+        r"\.exe$",  # Executables
+        r"\.dll$",
+        r"\.so$",
+        r"\.dylib$",
+        r"\.sh$",   # Shell scripts (unless explicitly allowed)
+        r"\.bat$",
+        r"\.cmd$",
+        r"\.ps1$",
+    ])
+    
+    # Allowed file extensions
+    allowed_extensions: Set[str] = field(default_factory=lambda: {
+        ".yaml", ".yml", ".json", ".md", ".txt", ".py",
+        ".toml", ".cfg", ".ini", ".env.example"
+    })
+
+
+class TemplateSecurity:
+    """
+    Security handler for template operations.
+    
+    Provides:
+    - Source allowlist validation
+    - Checksum verification
+    - Safe path extraction
+    - File type validation
+    """
+    
+    CONFIG_FILE = ".praison/security.yaml"
+    
+    def __init__(self, config: Optional[SecurityConfig] = None):
+        """
+        Initialize security handler.
+        
+        Args:
+            config: Security configuration (loads from file if not provided)
+        """
+        self.config = config or self._load_config()
+    
+    def _load_config(self) -> SecurityConfig:
+        """Load security config from file or use defaults."""
+        config_path = Path.home() / self.CONFIG_FILE
+        
+        if config_path.exists():
+            try:
+                import yaml
+                with open(config_path) as f:
+                    data = yaml.safe_load(f)
+                return SecurityConfig(
+                    allowed_sources=set(data.get("allowed_sources", [])),
+                    allow_local=data.get("allow_local", True),
+                    allow_any_github=data.get("allow_any_github", True),
+                    allow_http=data.get("allow_http", False),
+                    require_checksum=data.get("require_checksum", False),
+                    max_template_size=data.get("max_template_size", 10 * 1024 * 1024),
+                )
+            except Exception:
+                pass
+        
+        return SecurityConfig()
+    
+    def is_source_allowed(self, uri: str) -> bool:
+        """
+        Check if a template source is allowed.
+        
+        Args:
+            uri: Template URI
+            
+        Returns:
+            True if source is allowed
+        """
+        # Local paths
+        if uri.startswith(("./", "../", "~/", "/")) or os.path.exists(uri):
+            return self.config.allow_local
+        
+        # Package references
+        if uri.startswith("package:"):
+            package = uri.split(":")[1].split("/")[0]
+            return (
+                f"package:{package}" in self.config.allowed_sources or
+                uri in self.config.allowed_sources
+            )
+        
+        # GitHub references
+        if uri.startswith("github:"):
+            if self.config.allow_any_github:
+                return True
+            # Check specific repo allowlist
+            parts = uri.replace("github:", "").split("/")
+            if len(parts) >= 2:
+                repo_ref = f"github:{parts[0]}/{parts[1]}"
+                return repo_ref in self.config.allowed_sources
+            return False
+        
+        # HTTP references
+        if uri.startswith(("http://", "https://")):
+            return self.config.allow_http
+        
+        # Simple template name (assumes default repo)
+        if re.match(r'^[a-zA-Z][a-zA-Z0-9_-]*$', uri):
+            return True
+        
+        return False
+    
+    def verify_checksum(
+        self,
+        directory: Path,
+        expected_checksum: str,
+        algorithm: str = "sha256"
+    ) -> bool:
+        """
+        Verify checksum of template directory.
+        
+        Args:
+            directory: Template directory
+            expected_checksum: Expected checksum value
+            algorithm: Hash algorithm (sha256, sha512, md5)
+            
+        Returns:
+            True if checksum matches
+        """
+        actual = self.calculate_checksum(directory, algorithm)
+        return actual == expected_checksum
+    
+    def calculate_checksum(
+        self,
+        directory: Path,
+        algorithm: str = "sha256"
+    ) -> str:
+        """
+        Calculate checksum of template directory.
+        
+        Args:
+            directory: Template directory
+            algorithm: Hash algorithm
+            
+        Returns:
+            Hex digest of checksum
+        """
+        if algorithm == "sha256":
+            hasher = hashlib.sha256()
+        elif algorithm == "sha512":
+            hasher = hashlib.sha512()
+        elif algorithm == "md5":
+            hasher = hashlib.md5()
+        else:
+            raise ValueError(f"Unsupported algorithm: {algorithm}")
+        
+        for file_path in sorted(directory.rglob("*")):
+            if file_path.is_file() and not file_path.name.startswith("."):
+                hasher.update(file_path.name.encode())
+                hasher.update(file_path.read_bytes())
+        
+        return hasher.hexdigest()
+    
+    def validate_path(self, path: str) -> bool:
+        """
+        Validate a path for security issues.
+        
+        Args:
+            path: Path to validate
+            
+        Returns:
+            True if path is safe
+        """
+        for pattern in self.config.blocked_patterns:
+            if re.search(pattern, path, re.IGNORECASE):
+                return False
+        return True
+    
+    def validate_file(self, file_path: Path) -> bool:
+        """
+        Validate a file for security.
+        
+        Args:
+            file_path: Path to file
+            
+        Returns:
+            True if file is safe
+        """
+        # Check extension
+        if file_path.suffix.lower() not in self.config.allowed_extensions:
+            # Allow files without extension (like README)
+            if file_path.suffix:
+                return False
+            # Files without extension are allowed (like README, LICENSE)
+            return True
+        
+        # Check size
+        if file_path.exists() and file_path.stat().st_size > self.config.max_template_size:
+            return False
+        
+        # Check path (only validate the filename, not the full path)
+        return self.validate_path(file_path.name)
+    
+    def validate_template_directory(self, directory: Path) -> List[str]:
+        """
+        Validate all files in a template directory.
+        
+        Args:
+            directory: Template directory
+            
+        Returns:
+            List of validation errors (empty if valid)
+        """
+        errors = []
+        total_size = 0
+        
+        for file_path in directory.rglob("*"):
+            if file_path.is_file():
+                # Check path safety
+                if not self.validate_path(str(file_path.relative_to(directory))):
+                    errors.append(f"Unsafe path: {file_path.relative_to(directory)}")
+                    continue
+                
+                # Check extension
+                if file_path.suffix.lower() not in self.config.allowed_extensions:
+                    if file_path.suffix:  # Has extension but not allowed
+                        errors.append(f"Blocked file type: {file_path.name}")
+                
+                # Track size
+                total_size += file_path.stat().st_size
+        
+        if total_size > self.config.max_template_size:
+            errors.append(
+                f"Template too large: {total_size} bytes "
+                f"(max: {self.config.max_template_size})"
+            )
+        
+        return errors
+    
+    def sanitize_template_config(self, config: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Sanitize template configuration.
+        
+        Removes potentially dangerous fields and validates structure.
+        
+        Args:
+            config: Raw template configuration
+            
+        Returns:
+            Sanitized configuration
+        """
+        # Fields that are safe to keep
+        safe_fields = {
+            "name", "description", "version", "author", "license",
+            "tags", "requires", "config", "workflow", "agents",
+            "skills", "cli", "metadata"
+        }
+        
+        sanitized = {}
+        for key, value in config.items():
+            if key in safe_fields:
+                sanitized[key] = value
+        
+        return sanitized
+    
+    def add_allowed_source(self, source: str) -> None:
+        """Add a source to the allowlist."""
+        self.config.allowed_sources.add(source)
+    
+    def remove_allowed_source(self, source: str) -> None:
+        """Remove a source from the allowlist."""
+        self.config.allowed_sources.discard(source)
+    
+    def save_config(self) -> None:
+        """Save current config to file."""
+        import yaml
+        
+        config_path = Path.home() / self.CONFIG_FILE
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+        
+        data = {
+            "allowed_sources": list(self.config.allowed_sources),
+            "allow_local": self.config.allow_local,
+            "allow_any_github": self.config.allow_any_github,
+            "allow_http": self.config.allow_http,
+            "require_checksum": self.config.require_checksum,
+            "max_template_size": self.config.max_template_size,
+        }
+        
+        with open(config_path, "w") as f:
+            yaml.dump(data, f, default_flow_style=False)