agent-portal-2 0.1.0

package/python/agent_portal/server.py

@@ -0,0 +1,351 @@
+from __future__ import annotations
+
+import json
+import threading
+from dataclasses import asdict
+from http import HTTPStatus
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from pathlib import Path
+from urllib.parse import urlparse
+
+from .exceptions import AgentPortalError
+from .models import ActionRequest
+from .runtime import PortalRuntime
+
+
+def build_server(runtime: PortalRuntime) -> HTTPServer:
+    class AgentPortalHandler(BaseHTTPRequestHandler):
+        server_version = "AgentPortalRuntime/0.0.3"
+
+        def _send_json(self, status: int, payload: object) -> None:
+            encoded = json.dumps(payload, indent=2).encode("utf8")
+            self.send_response(status)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(encoded)))
+            self.send_header("Access-Control-Allow-Origin", "*")
+            self.send_header("Access-Control-Allow-Headers", "Content-Type, Authorization")
+            self.send_header("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
+            self.end_headers()
+            self.wfile.write(encoded)
+
+        def _read_json(self) -> dict[str, object]:
+            content_length = int(self.headers.get("Content-Length", "0"))
+            if content_length == 0:
+                return {}
+            return json.loads(self.rfile.read(content_length).decode("utf8"))
+
+        def _authorize(self) -> bool:
+            token = runtime.config.api_token
+            if not token:
+                return True
+            header = self.headers.get("Authorization", "")
+            return header == f"Bearer {token}"
+
+        def _unauthorized(self) -> None:
+            self._send_json(
+                HTTPStatus.UNAUTHORIZED,
+                {
+                    "error": "Unauthorized",
+                    "suggestedFix": "Provide the configured runtime API token as a Bearer token.",
+                },
+            )
+
+        def do_OPTIONS(self) -> None:  # noqa: N802
+            self.send_response(HTTPStatus.NO_CONTENT)
+            self.send_header("Access-Control-Allow-Origin", "*")
+            self.send_header("Access-Control-Allow-Headers", "Content-Type, Authorization")
+            self.send_header("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
+            self.end_headers()
+
+        def do_GET(self) -> None:  # noqa: N802
+            parsed = urlparse(self.path)
+            if parsed.path != "/health" and not self._authorize():
+                self._unauthorized()
+                return
+            if parsed.path == "/health":
+                self._send_json(HTTPStatus.OK, runtime.health())
+                return
+            if parsed.path == "/status":
+                self._send_json(HTTPStatus.OK, runtime.status())
+                return
+            if parsed.path == "/report/latest":
+                report_path = runtime.generate_report()
+                self._send_json(
+                    HTTPStatus.OK,
+                    {
+                        "reportPath": str(report_path),
+                        "report": json.loads(report_path.read_text(encoding="utf8")),
+                    },
+                )
+                return
+            self._send_json(HTTPStatus.NOT_FOUND, {"error": "Unknown path"})
+
+        def do_POST(self) -> None:  # noqa: N802
+            parsed = urlparse(self.path)
+            if not self._authorize():
+                self._unauthorized()
+                return
+            payload = self._read_json()
+            try:
+                if parsed.path == "/control/start":
+                    runtime.start()
+                    self._send_json(HTTPStatus.OK, runtime.status())
+                    return
+                if parsed.path == "/control/stop":
+                    self._send_json(HTTPStatus.OK, {"status": "stopping"})
+                    threading.Thread(target=self.server.shutdown, daemon=True).start()
+                    runtime.stop()
+                    return
+                if parsed.path == "/control/pause":
+                    runtime.pause()
+                    self._send_json(HTTPStatus.OK, runtime.status())
+                    return
+                if parsed.path == "/control/resume":
+                    runtime.resume()
+                    self._send_json(HTTPStatus.OK, runtime.status())
+                    return
+                if parsed.path == "/control/restart":
+                    runtime.restart()
+                    self._send_json(HTTPStatus.OK, runtime.status())
+                    return
+                if parsed.path == "/control/goal":
+                    runtime.set_goal(str(payload.get("goal", "")))
+                    self._send_json(HTTPStatus.OK, runtime.status())
+                    return
+                if parsed.path == "/control/goal/current":
+                    self._send_json(
+                        HTTPStatus.OK,
+                        {"goal": runtime.get_current_goal()},
+                    )
+                    return
+                if parsed.path == "/control/action-mode":
+                    runtime.set_action_mode(str(payload.get("mode", "")))
+                    self._send_json(HTTPStatus.OK, runtime.status())
+                    return
+                if parsed.path == "/control/action-queue":
+                    self._send_json(HTTPStatus.OK, {"actions": runtime.get_action_queue()})
+                    return
+                if parsed.path == "/control/propose-action":
+                    action = runtime.propose_action(
+                        ActionRequest(
+                            action_type=str(payload.get("actionType", "")),
+                            reason=str(payload.get("reason", "")),
+                            target=str(payload["target"]) if "target" in payload and payload["target"] is not None else None,
+                            payload=str(payload["payload"]) if "payload" in payload and payload["payload"] is not None else None,
+                            risk_level=str(payload.get("riskLevel", "low")),
+                        )
+                    )
+                    self._send_json(HTTPStatus.OK, asdict(action))
+                    return
+                if parsed.path == "/control/approve-action":
+                    action_id = str(payload.get("actionId", ""))
+                    execute_now = bool(payload.get("execute", False))
+                    result = runtime.execute_action(action_id) if execute_now else runtime.approve_action(action_id)
+                    self._send_json(HTTPStatus.OK, asdict(result))
+                    return
+                if parsed.path == "/control/reject-action":
+                    result = runtime.reject_action(
+                        str(payload.get("actionId", "")),
+                        str(payload.get("reason", "Rejected by user")),
+                    )
+                    self._send_json(HTTPStatus.OK, asdict(result))
+                    return
+                if parsed.path == "/browser/start":
+                    runtime.ensure_browser()
+                    self._send_json(HTTPStatus.OK, runtime.status())
+                    return
+                if parsed.path == "/browser/close":
+                    self._send_json(HTTPStatus.OK, asdict(runtime.close_browser()))
+                    return
+                if parsed.path == "/browser/refresh":
+                    self._send_json(HTTPStatus.OK, asdict(runtime.refresh()))
+                    return
+                if parsed.path == "/browser/back":
+                    self._send_json(HTTPStatus.OK, asdict(runtime.back()))
+                    return
+                if parsed.path == "/browser/forward":
+                    self._send_json(HTTPStatus.OK, asdict(runtime.forward()))
+                    return
+                if parsed.path == "/browser/status":
+                    self._send_json(HTTPStatus.OK, runtime.browser_status())
+                    return
+                if parsed.path == "/browser/open":
+                    self._send_json(
+                        HTTPStatus.OK,
+                        asdict(runtime.open_url(str(payload.get("url", "")))),
+                    )
+                    return
+                if parsed.path == "/browser/click":
+                    self._send_json(
+                        HTTPStatus.OK,
+                        asdict(
+                            runtime.click(
+                                str(payload.get("selector", "")),
+                                str(payload.get("reason", "Click element")),
+                            )
+                        ),
+                    )
+                    return
+                if parsed.path == "/browser/type":
+                    self._send_json(
+                        HTTPStatus.OK,
+                        asdict(
+                            runtime.type_text(
+                                str(payload.get("selector", "")),
+                                str(payload.get("value", "")),
+                                str(payload.get("reason", "Type into element")),
+                            )
+                        ),
+                    )
+                    return
+                if parsed.path == "/browser/scroll":
+                    self._send_json(
+                        HTTPStatus.OK,
+                        asdict(
+                            runtime.scroll(
+                                str(payload["selector"]) if "selector" in payload and payload["selector"] is not None else None,
+                                str(payload.get("reason", "Scroll page")),
+                            )
+                        ),
+                    )
+                    return
+                if parsed.path == "/browser/hover":
+                    self._send_json(
+                        HTTPStatus.OK,
+                        asdict(
+                            runtime.hover(
+                                str(payload.get("selector", "")),
+                                str(payload.get("reason", "Hover over element")),
+                            )
+                        ),
+                    )
+                    return
+                if parsed.path == "/browser/wait":
+                    self._send_json(
+                        HTTPStatus.OK,
+                        asdict(
+                            runtime.wait(
+                                str(payload.get("selector", "")),
+                                str(payload.get("reason", "Wait for element")),
+                            )
+                        ),
+                    )
+                    return
+                if parsed.path == "/browser/screenshot":
+                    self._send_json(
+                        HTTPStatus.OK,
+                        asdict(runtime.screenshot(str(payload.get("label", "manual")))),
+                    )
+                    return
+                if parsed.path == "/browser/capture":
+                    self._send_json(
+                        HTTPStatus.OK,
+                        runtime.capture_snapshot(str(payload.get("label", "capture"))),
+                    )
+                    return
+                if parsed.path == "/browser/inspect":
+                    self._send_json(HTTPStatus.OK, runtime.inspect())
+                    return
+                if parsed.path == "/browser/read-dom":
+                    self._send_json(HTTPStatus.OK, runtime.read_dom())
+                    return
+                if parsed.path == "/browser/read-accessibility-tree":
+                    self._send_json(HTTPStatus.OK, runtime.read_accessibility_tree())
+                    return
+                if parsed.path == "/browser/read-console-errors":
+                    self._send_json(HTTPStatus.OK, runtime.read_console_errors())
+                    return
+                if parsed.path == "/browser/read-network-failures":
+                    self._send_json(HTTPStatus.OK, runtime.read_network_failures())
+                    return
+                if parsed.path == "/browser/read-text":
+                    self._send_json(
+                        HTTPStatus.OK,
+                        runtime.read_text(
+                            str(payload.get("selector", "")),
+                            str(payload.get("reason", "Read text from element")),
+                        ),
+                    )
+                    return
+                if parsed.path == "/browser/execute":
+                    self._send_json(
+                        HTTPStatus.OK,
+                        runtime.execute(
+                            str(payload.get("script", "")),
+                            str(payload.get("reason", "Execute script in page context")),
+                        ),
+                    )
+                    return
+                if parsed.path == "/browser/inspect-element":
+                    self._send_json(
+                        HTTPStatus.OK,
+                        runtime.inspect_element(str(payload.get("selector", ""))),
+                    )
+                    return
+                if parsed.path == "/control/approve-next":
+                    if runtime.session.pending_actions:
+                        result = runtime.approve_action(runtime.session.pending_actions[0].action_id)
+                        self._send_json(HTTPStatus.OK, asdict(result))
+                        return
+                    self._send_json(HTTPStatus.OK, {"message": "No pending action"})
+                    return
+                if parsed.path == "/control/reject-next":
+                    if runtime.session.pending_actions:
+                        result = runtime.reject_action(
+                            runtime.session.pending_actions[0].action_id,
+                            str(payload.get("reason", "Rejected by user")),
+                        )
+                        self._send_json(HTTPStatus.OK, asdict(result))
+                        return
+                    self._send_json(HTTPStatus.OK, {"message": "No pending action"})
+                    return
+                if parsed.path == "/report/generate":
+                    report_path = runtime.generate_report()
+                    self._send_json(HTTPStatus.OK, {"reportPath": str(report_path)})
+                    return
+                if parsed.path == "/report/list":
+                    self._send_json(HTTPStatus.OK, {"reports": runtime.list_reports()})
+                    return
+                if parsed.path == "/report/read":
+                    self._send_json(
+                        HTTPStatus.OK,
+                        runtime.read_report(str(payload.get("report", ""))),
+                    )
+                    return
+                if parsed.path == "/report/export":
+                    self._send_json(
+                        HTTPStatus.OK,
+                        runtime.export_report(
+                            str(payload.get("report", "")),
+                            str(payload["destination"]) if "destination" in payload and payload["destination"] is not None else None,
+                        ),
+                    )
+                    return
+                self._send_json(HTTPStatus.NOT_FOUND, {"error": "Unknown path"})
+            except AgentPortalError as exc:
+                self._send_json(HTTPStatus.BAD_REQUEST, exc.to_dict())
+
+        def log_message(self, format: str, *args: object) -> None:  # noqa: A003
+            return
+
+    server = HTTPServer(
+        (runtime.config.runtime_host, runtime.config.runtime_port),
+        AgentPortalHandler,
+    )
+    server.allow_reuse_address = True
+    return server
+
+
+def serve(runtime: PortalRuntime | None = None) -> None:
+    active_runtime = runtime or PortalRuntime(Path.cwd())
+    active_runtime.start()
+    server = build_server(active_runtime)
+    try:
+        server.serve_forever()
+    finally:
+        server.server_close()
+        active_runtime.stop()
+
+
+def main() -> None:
+    serve()

package/python/agent_portal/validation.py

@@ -0,0 +1,299 @@
+"""Input validation and sanitization utilities for Agent Portal."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import urlparse
+
+
+@dataclass(frozen=True)
+class ValidationResult:
+    """Result of a validation check."""
+    is_valid: bool
+    errors: list[str]
+
+
+class ValidationError(Exception):
+    """Raised when validation fails."""
+    pass
+
+
+# URL validation patterns
+SAFE_PROTOCOLS = {"http", "https"}
+DOMAIN_PATTERN = re.compile(r"^[a-zA-Z0-9][a-zA-Z0-9-_.]*\.[a-zA-Z]{2,}$")
+LOCALHOST_PATTERNS = {
+    "localhost",
+    "127.0.0.1",
+    "0.0.0.0",
+    "::1",
+}
+
+
+def validate_url(url: str, allow_local: bool = True) -> ValidationResult:
+    """
+    Validate a URL for safety and structure.
+    
+    Args:
+        url: The URL to validate
+        allow_local: Whether to allow localhost/local network addresses
+        
+    Returns:
+        ValidationResult indicating if the URL is valid
+    """
+    errors: list[str] = []
+    
+    if not url or not isinstance(url, str):
+        errors.append("URL must be a non-empty string")
+        return ValidationResult(False, errors)
+    
+    # Check for dangerous patterns first (before parsing)
+    url_lower = url.lower()
+    if any(pattern in url_lower for pattern in ["javascript:", "data:", "file:", "ftp:", "vbscript:"]):
+        errors.append("Potentially dangerous URL pattern detected")
+        return ValidationResult(False, errors)
+    
+    try:
+        parsed = urlparse(url)
+    except Exception as exc:
+        errors.append(f"Invalid URL format: {exc}")
+        return ValidationResult(False, errors)
+    
+    if not parsed.scheme:
+        errors.append("URL must include a protocol (http:// or https://)")
+    elif parsed.scheme not in SAFE_PROTOCOLS:
+        errors.append(f"Unsupported protocol: {parsed.scheme}. Only http:// and https:// are allowed")
+    
+    if not parsed.netloc:
+        errors.append("URL must include a hostname")
+        return ValidationResult(False, errors)
+    
+    # Check for localhost if not explicitly allowed
+    if not allow_local:
+        if parsed.hostname in LOCALHOST_PATTERNS or parsed.hostname == "0.0.0.0":
+            errors.append("Localhost addresses are not allowed in this mode")
+    
+    return ValidationResult(len(errors) == 0, errors)
+
+
+def validate_selector(selector: str | None) -> ValidationResult:
+    """
+    Validate a CSS selector for injection safety.
+    
+    Args:
+        selector: The CSS selector to validate
+        
+    Returns:
+        ValidationResult indicating if the selector is safe
+    """
+    errors: list[str] = []
+    
+    if not selector:
+        return ValidationResult(True, errors)
+    
+    if not isinstance(selector, str):
+        errors.append("Selector must be a string")
+        return ValidationResult(False, errors)
+    
+    if len(selector) > 1000:
+        errors.append("Selector is too long (max 1000 characters)")
+    
+    # Check for potential XSS patterns
+    xss_patterns = [
+        "<script",
+        "javascript:",
+        "onerror=",
+        "onload=",
+        "onclick=",
+        "fromCharCode",
+        "eval(",
+    ]
+    
+    selector_lower = selector.lower()
+    if any(pattern in selector_lower for pattern in xss_patterns):
+        errors.append("Selector contains potentially dangerous patterns")
+    
+    return ValidationResult(len(errors) == 0, errors)
+
+
+def validate_script(script: str) -> ValidationResult:
+    """
+    Validate a JavaScript script for basic safety.
+    
+    Args:
+        script: The JavaScript code to validate
+        
+    Returns:
+        ValidationResult indicating if the script passes basic checks
+    """
+    errors: list[str] = []
+    
+    if not script or not isinstance(script, str):
+        errors.append("Script must be a non-empty string")
+        return ValidationResult(False, errors)
+    
+    if len(script) > 10000:
+        errors.append("Script is too long (max 10000 characters)")
+    
+    # Check for obviously dangerous operations
+    dangerous_patterns = [
+        "document.cookie",
+        "localStorage",
+        "sessionStorage",
+        "window.location",
+        "eval(",
+        "Function(",
+        "document.write",
+        "XMLHttpRequest",
+        "fetch(",
+    ]
+    
+    script_lower = script.lower()
+    matches = [pattern for pattern in dangerous_patterns if pattern.lower() in script_lower]
+    
+    if matches:
+        errors.append(f"Script contains potentially dangerous operations: {', '.join(matches)}")
+    
+    return ValidationResult(len(errors) == 0, errors)
+
+
+def validate_action_type(action_type: str) -> ValidationResult:
+    """
+    Validate that an action type is supported.
+    
+    Args:
+        action_type: The action type to validate
+        
+    Returns:
+        ValidationResult indicating if the action type is valid
+    """
+    errors: list[str] = []
+    
+    valid_types = {
+        "open_url", "click", "type", "scroll", "hover", "wait",
+        "screenshot", "inspect", "read_text", "execute",
+        "browser_close", "browser_refresh", "browser_back", "browser_forward",
+    }
+    
+    if not action_type or not isinstance(action_type, str):
+        errors.append("Action type must be a non-empty string")
+        return ValidationResult(False, errors)
+    
+    if action_type not in valid_types:
+        errors.append(f"Unknown action type: {action_type}. Valid types: {', '.join(sorted(valid_types))}")
+    
+    return ValidationResult(len(errors) == 0, errors)
+
+
+def validate_risk_level(risk_level: str) -> ValidationResult:
+    """
+    Validate that a risk level is within the allowed range.
+    
+    Args:
+        risk_level: The risk level to validate
+        
+    Returns:
+        ValidationResult indicating if the risk level is valid
+    """
+    errors: list[str] = []
+    
+    valid_levels = {"safe", "low", "medium", "high", "blocked"}
+    
+    if not risk_level or not isinstance(risk_level, str):
+        errors.append("Risk level must be a non-empty string")
+        return ValidationResult(False, errors)
+    
+    if risk_level not in valid_levels:
+        errors.append(f"Invalid risk level: {risk_level}. Valid levels: {', '.join(sorted(valid_levels))}")
+    
+    return ValidationResult(len(errors) == 0, errors)
+
+
+def validate_text_input(value: str, max_length: int = 500, field_name: str = "value") -> ValidationResult:
+    """
+    Validate a general text input field.
+    
+    Args:
+        value: The text value to validate
+        max_length: Maximum allowed length
+        field_name: Name of the field for error messages
+        
+    Returns:
+        ValidationResult indicating if the input is valid
+    """
+    errors: list[str] = []
+    
+    if not isinstance(value, str):
+        errors.append(f"{field_name} must be a string")
+        return ValidationResult(False, errors)
+    
+    if len(value) > max_length:
+        errors.append(f"{field_name} is too long (max {max_length} characters)")
+    
+    return ValidationResult(len(errors) == 0, errors)
+
+
+def sanitize_text(text: str) -> str:
+    """
+    Sanitize text by removing or escaping potentially harmful characters.
+    
+    Args:
+        text: The text to sanitize
+        
+    Returns:
+        Sanitized text
+    """
+    if not text or not isinstance(text, str):
+        return ""
+    
+    # Remove null bytes and other control characters except newlines and tabs
+    sanitized = re.sub(r'[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]', '', text)
+    
+    # Trim whitespace
+    sanitized = sanitized.strip()
+    
+    return sanitized
+
+
+def validate_config(config: dict[str, Any]) -> ValidationResult:
+    """
+    Validate runtime configuration.
+    
+    Args:
+        config: Configuration dictionary to validate
+        
+    Returns:
+        ValidationResult indicating if the configuration is valid
+    """
+    errors: list[str] = []
+    
+    # Validate host
+    if "runtime_host" in config:
+        host = config["runtime_host"]
+        if not isinstance(host, str):
+            errors.append("runtime_host must be a string")
+        elif host == "0.0.0.0":
+            errors.append("runtime_host cannot be 0.0.0.0 for security reasons")
+    
+    # Validate port
+    if "runtime_port" in config:
+        port = config["runtime_port"]
+        if not isinstance(port, int) or not (1024 <= port <= 65535):
+            errors.append("runtime_port must be an integer between 1024 and 65535")
+    
+    # Validate action_mode
+    if "action_mode" in config:
+        mode = config["action_mode"]
+        valid_modes = {"read-only", "assisted", "autonomous", "manual-override"}
+        if mode not in valid_modes:
+            errors.append(f"action_mode must be one of: {', '.join(sorted(valid_modes))}")
+    
+    # Validate approval_policy
+    if "approval_policy" in config:
+        policy = config["approval_policy"]
+        valid_policies = {"safe", "low", "medium", "high", "blocked"}
+        if policy not in valid_policies:
+            errors.append(f"approval_policy must be one of: {', '.join(sorted(valid_policies))}")
+    
+    return ValidationResult(len(errors) == 0, errors)

package/python/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "agent-portal"
+version = "0.0.3"
+description = "Python runtime package for Agent Portal."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+  { name = "Magnexis" }
+]
+dependencies = [
+  "playwright>=1.54.0"
+]
+
+[project.urls]
+Homepage = "https://github.com/magnexis/agent-portal"
+Repository = "https://github.com/magnexis/agent-portal.git"
+Issues = "https://github.com/magnexis/agent-portal/issues"
+
+[project.scripts]
+agent-portal-runtime = "agent_portal.server:main"
+agent-portal = "agent_portal.cli:main"
+
+[tool.flit.module]
+name = "agent_portal"
+
+[build-system]
+requires = ["flit_core>=3.12.0,<4"]
+build-backend = "flit_core.buildapi"