canon-gate 0.5.2__py3-none-any.whl

canon_gate/__init__.py

@@ -0,0 +1 @@
+# This file makes 'canon_gate' a Python package.

canon_gate/boundary/__init__.py

@@ -0,0 +1 @@
+# Boundary interaction layer

canon_gate/boundary/adapters/__init__.py

@@ -0,0 +1,13 @@
+"""
+This package contains adapter implementations that are part of the boundary layer.
+
+Adapters are responsible for:
+1.  **Egress Validation:** Applying strict, deterministic checks to the parameters
+    of a proposed action before execution.
+2.  **Execution:** Interacting with external systems (e.g., databases, APIs,
+    shell commands) to carry out the approved action.
+"""
+from .mock_adapter import MockRunQueryAdapter
+from .script_adapter import ScriptAdapter
+
+__all__ = ["MockRunQueryAdapter", "ScriptAdapter"]

canon_gate/boundary/adapters/mock_adapter.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+from pydantic import BaseModel, Field, ValidationError
+from canon_gate.core.adapters import BaseAdapter
+from canon_gate.core.config import RUN_QUERY_FORBIDDEN_KEYWORDS
+from canon_gate.core.models import (
+    ActionProposal,
+    ActionRejected,
+    AdapterAction,
+    AdapterManifest,
+)
+
+if TYPE_CHECKING:
+    from canon_gate.core.models import ActionProposal
+
+
+class MockAdapterParameters(BaseModel):
+    query: str = Field(..., description="The read-only SQL query to execute.")
+
+
+class MockRunQueryAdapter(BaseAdapter):
+    """
+    A mock adapter for demonstration purposes. It handles the 'run_query' action
+    and performs its own egress validation on the SQL parameters before execution.
+    """
+
+    def get_manifest(self) -> AdapterManifest:
+        """Returns the manifest describing the adapter's capabilities."""
+        return AdapterManifest(
+            adapter_name="run_query_adapter",
+            actions=[
+                AdapterAction.from_pydantic_model(
+                    name="run_query",
+                    description="Runs a read-only SQL query against a mock database.",
+                    model=MockAdapterParameters,
+                )
+            ],
+        )
+
+    def _validate_egress(self, query: str) -> list[str]:
+        """
+        Performs a final validation check on the SQL query itself.
+        This is the Egress Validation step.
+        """
+        errors = []
+        sql_lower = query.lower()
+        for keyword in RUN_QUERY_FORBIDDEN_KEYWORDS:
+            if keyword in sql_lower:
+                errors.append(f"SQL query contains forbidden keyword: '{keyword}'")
+        return errors
+
+    def execute(self, proposal: "ActionProposal") -> dict:
+        """
+        Validates the egress parameters and then simulates executing a SQL query.
+        """
+        try:
+            params = MockAdapterParameters.model_validate(proposal.parameters)
+        except ValidationError as e:
+            raise ActionRejected(f"Egress validation failed: Invalid parameters: {e}")
+
+        # Perform Egress Validation
+        egress_errors = self._validate_egress(params.query)
+        if egress_errors:
+            raise ActionRejected(f"Egress validation failed: {', '.join(egress_errors)}")
+
+        print("---")
+        print(f"[Mock Adapter] INFO: Egress validation passed for action 'run_query'.")
+        print(f"[Mock Adapter] INFO: Would execute query against production database: {params.query}")
+        print("---")
+
+        return {
+            "status": "success",
+            "message": "Query was mock-executed successfully after passing egress validation.",
+            "query_sent_to_db": params.query,
+            "egress_checks_passed": True,
+        }

canon_gate/boundary/adapters/script_adapter.py

@@ -0,0 +1,103 @@
+# canon_gate/boundary/adapters/script_adapter.py
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any, Dict
+
+from pydantic import BaseModel, Field, ValidationError
+
+from canon_gate.core.adapters import BaseAdapter
+from canon_gate.core.config import SCRIPT_ADAPTER_ALLOWED_SCRIPTS
+from canon_gate.core.models import (
+    ActionProposal,
+    ActionRejected,
+    AdapterAction,
+    AdapterManifest,
+)
+
+# The base path to the directory where the scripts are stored
+SCRIPT_DIRECTORY = Path(__file__).parent.parent.parent.parent / "scripts"
+
+
+# 1. Define the parameter schema for the adapter's action
+class ScriptAdapterParameters(BaseModel):
+    script_name: str = Field(
+        ..., description="The name of the script to execute (without the .py extension)."
+    )
+    script_args: list[str] = Field(
+        default=[], description="A list of arguments to pass to the script."
+    )
+
+
+class ScriptAdapter(BaseAdapter):
+    """
+    An adapter for executing predefined python scripts from the /scripts directory.
+    """
+
+    # 2. Implement get_manifest to make the adapter self-describing
+    def get_manifest(self) -> AdapterManifest:
+        """Returns the manifest describing the adapter's capabilities."""
+        return AdapterManifest(
+            adapter_name="execute_script_adapter",
+            actions=[
+                AdapterAction.from_pydantic_model(
+                    name="execute_script",
+                    description="Executes a predefined system script.",
+                    model=ScriptAdapterParameters,
+                )
+            ],
+        )
+
+    # 3. Refactor execute to use the parameter schema
+    def execute(self, proposal: ActionProposal) -> Dict[str, Any]:
+        """
+        Executes a script after performing Egress validation.
+        """
+        try:
+            params = ScriptAdapterParameters.model_validate(proposal.parameters)
+        except ValidationError as e:
+            raise ActionRejected(f"Egress validation failed: Invalid parameters: {e}")
+
+        # Egress Validation: Policy check
+        if params.script_name not in SCRIPT_ADAPTER_ALLOWED_SCRIPTS:
+            raise ActionRejected(
+                f"Egress validation failed: Script '{params.script_name}' is not in the list of allowed scripts."
+            )
+
+        script_path = SCRIPT_DIRECTORY / f"{params.script_name}.py"
+
+        # Egress Validation: Existence check
+        if not script_path.exists():
+            raise ActionRejected(
+                f"Egress validation failed: Script '{params.script_name}.py' not found at '{script_path}'."
+            )
+
+        try:
+            # Execution
+            command = [sys.executable, str(script_path)] + params.script_args
+            completed_process = subprocess.run(
+                command,
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+
+            stdout = completed_process.stdout.strip()
+            stderr = completed_process.stderr.strip()
+            exit_code = completed_process.returncode
+
+            if exit_code == 0:
+                return {
+                    "status": "succeeded",
+                    "message": stdout or "Script executed successfully with no output.",
+                    "output": {"stdout": stdout, "stderr": stderr, "exit_code": exit_code},
+                }
+            else:
+                return {
+                    "status": "failed",
+                    "message": stderr or stdout or f"Script failed with exit code {exit_code}.",
+                    "output": {"stdout": stdout, "stderr": stderr, "exit_code": exit_code},
+                }
+
+        except Exception as e:
+            raise ActionRejected(f"Execution failed: An unexpected error occurred: {str(e)}")

canon_gate/boundary/audit.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import json
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from canon_gate.core.models import GateDecision
+
+# This basic configuration sends structured JSON logs to stdout.
+# In a real application, you would configure handlers to route this
+# to a dedicated logging service or file.
+logging.basicConfig(level=logging.INFO, format='%(message)s')
+logger = logging.getLogger(__name__)
+
+
+def log_denial(decision: "GateDecision"):
+    """
+    Logs a denied GateDecision in a structured JSON format.
+
+    This creates a critical audit trail for security and review purposes.
+    """
+    if decision.allowed:
+        # This function is specifically for logging denials.
+        return
+
+    log_data = {
+        "event": "action_denied",
+        "decision_id": decision.decision_id,
+        "timestamp": decision.timestamp.isoformat(),
+        "source": decision.source,
+        "action": decision.action,
+        "allowed": decision.allowed,
+        "errors": decision.errors,
+        "failed_checks": decision.failed_checks,
+    }
+
+    # The use of json.dumps creates a structured, machine-readable log entry.
+    logger.info(json.dumps(log_data))

canon_gate/boundary/decorator.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from functools import wraps
+from typing import Any, Callable
+
+from canon_gate.core.models import ActionProposal, GateDecision
+from canon_gate.core.policy import validate_agent_output, ValidationResult
+
+
+def protected_by_canon_gate(action_type: str):
+    """
+    A decorator to protect a function with Canon Gate's validation.
+    """
+    def decorator(func: Callable[..., Any]):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            # 1. Construct the generic ActionProposal from function arguments
+            proposal = ActionProposal(
+                action=action_type,
+                reason=f"Automated call to protected function '{func.__name__}'",
+                parameters={
+                    "function_name": func.__name__,
+                    "function_args": kwargs,
+                    # Note: args are ignored in this simple version
+                },
+            )
+
+            # 2. Validate the proposal
+            validation_result = validate_agent_output(proposal)
+
+            # 3. If allowed, execute the original function
+            if validation_result.allowed:
+                print(f"Canon Gate validated '{proposal.action}'. Executing function.")
+                return func(*args, **kwargs)
+            else:
+                # If not allowed, block execution and return a GateDecision
+                print(f"Canon Gate BLOCKED '{proposal.action}'. Reason: {validation_result.errors}")
+                
+                decision = GateDecision(
+                    source="decorator",
+                    action=validation_result.action,
+                    allowed=validation_result.allowed,
+                    errors=validation_result.errors,
+                    passed_checks=validation_result.passed_checks,
+                    failed_checks=validation_result.failed_checks,
+                    execution=None,
+                )
+                return decision
+        return wrapper
+    return decorator

canon_gate/boundary/main.py

@@ -0,0 +1,162 @@
+import logging
+import os
+from contextlib import asynccontextmanager
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Annotated, Dict
+import json
+from importlib import metadata, resources
+import toml
+
+from fastapi import Depends, FastAPI, Request, status
+
+from fastapi.responses import JSONResponse, HTMLResponse
+
+# --- Core Imports ---
+from canon_gate.core.policy import validate_agent_output
+from canon_gate.core.models import ActionProposal, GateDecision, Manifest
+from canon_gate.core.adapters import BaseAdapter
+from canon_gate.core.orchestration import run_execute_flow
+from canon_gate.core.manifest_generator import generate_manifest
+
+# --- Boundary Imports ---
+from .audit import log_denial
+from .audit import logger as audit_logger
+
+from .adapters import MockRunQueryAdapter, ScriptAdapter
+from operator_console.main import router as console_router, SESSIONS_DIR
+
+from contextlib import asynccontextmanager
+
+# --- Adapter Registry (Boundary-level concern) ---
+
+def register_adapters() -> Dict[str, BaseAdapter]:
+    """Initializes and registers all available adapters."""
+    registry = {}
+    adapters_to_register = [MockRunQueryAdapter(), ScriptAdapter()]
+
+    for adapter in adapters_to_register:
+        manifest = adapter.get_manifest()
+        for action in manifest.actions:
+            if action.name in registry:
+                logging.warning(
+                    f"Action '{action.name}' is already registered. Overwriting with adapter '{manifest.adapter_name}'."
+                )
+            registry[action.name] = adapter
+            logging.info(
+                f"Registered action '{action.name}' to adapter '{manifest.adapter_name}'"
+            )
+    return registry
+
+# --- FastAPI Application Factory ---
+
+def get_version() -> str:
+    """Reads the package version from metadata, with fallbacks for development."""
+    try:
+        # Primary method: For installed packages
+        return metadata.version("canon-gate")
+    except metadata.PackageNotFoundError:
+        # Fallback for local development: read from pyproject.toml
+        try:
+            pyproject_path = Path(__file__).parent.parent.parent / "pyproject.toml"
+            with open(pyproject_path, "r") as f:
+                data = toml.load(f)
+            return data["project"]["version"]
+        except (FileNotFoundError, KeyError):
+            # Final fallback if all else fails
+            return "0.0.0-dev"
+
+_VERSION = get_version()
+
+def get_adapter_registry(request: Request) -> Dict[str, BaseAdapter]:
+    """Dependency to get the adapter registry from the app state."""
+    return request.app.state.adapter_registry
+
+def create_app(env: str | None = None) -> FastAPI:
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):
+        # Create the adapter registry on startup and store it in the app state
+        app.state.adapter_registry = register_adapters()
+
+        # Ensure the directory for operator sessions exists in the user's app data dir
+        SESSIONS_DIR.mkdir(parents=True, exist_ok=True)
+
+        environment = os.getenv("CANON_GATE_ENV", "production")
+        startup_log_data = {
+            "event": "service_startup",
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "version": _VERSION,
+            "environment": environment,
+            "message": "Canon Gate service started.",
+        }
+        audit_logger.info(json.dumps(startup_log_data))
+        yield
+
+    app = FastAPI(title="Canon Gate Framework", version=_VERSION, lifespan=lifespan)
+    app.include_router(console_router)
+    actual_env = env or os.getenv("CANON_GATE_ENV", "production")
+
+    @app.exception_handler(Exception)
+    async def unhandled_exception_handler(request: Request, exc: Exception):
+        error_log_data = {"event": "unhandled_exception", "message": str(exc)}
+        audit_logger.error(json.dumps(error_log_data))
+        return JSONResponse(status_code=500, content=error_log_data)
+
+    @app.get("/")
+    def root() -> dict:
+        endpoints = {
+            "message": "Canon Gate Framework operational.",
+            "endpoints": ["/validate_output", "/execute", "/manifest"],
+        }
+        if actual_env == "development":
+            endpoints["message"] = "Canon Gate Framework running (Development Mode)"
+            endpoints["operator_console"] = "/console"
+        return endpoints
+
+    @app.get("/console", response_class=HTMLResponse)
+    def serve_console():
+        """Serves the Operator Console main page from package resources."""
+        try:
+            content = resources.files('operator_console.static').joinpath('console.html').read_text()
+            return HTMLResponse(content)
+        except (ModuleNotFoundError, FileNotFoundError):
+            return HTMLResponse("<h1>Error: Operator Console not found.</h1>", status_code=500)
+
+
+    @app.get("/manifest", response_model=Manifest, tags=["Runtime Discovery"])
+    def get_manifest(
+        adapter_registry: Annotated[Dict, Depends(get_adapter_registry)]
+    ) -> Manifest:
+        """
+        Provides a discoverable, machine-readable overview of the actions
+        and parameters governed by this Canon Gate instance.
+        """
+        return generate_manifest(adapter_registry)
+    
+    @app.post("/validate_output", response_model=GateDecision)
+    def validate_output_endpoint(proposal: ActionProposal) -> GateDecision:
+        result = validate_agent_output(proposal)
+        decision = GateDecision(
+            source="validate",
+            action=result.action,
+            proposal=proposal,
+            allowed=result.allowed,
+            errors=result.errors,
+            passed_checks=result.passed_checks,
+            failed_checks=result.failed_checks,
+            execution=None,
+        )
+        if not decision.allowed:
+            log_denial(decision)
+        return decision
+
+    @app.post("/execute", response_model=GateDecision)
+    def execute_endpoint(
+        proposal: ActionProposal,
+        adapter_registry: Annotated[Dict, Depends(get_adapter_registry)],
+    ) -> GateDecision:
+        return run_execute_flow(proposal, adapter_registry)
+
+    return app
+
+app = create_app()

canon_gate/cli.py

@@ -0,0 +1,85 @@
+import uvicorn
+import typer
+from typing_extensions import Annotated
+
+app = typer.Typer()
+
+@app.command()
+def serve(
+    host: Annotated[str, typer.Option(help="The host to bind the server to.")] = "127.0.0.1",
+    port: Annotated[int, typer.Option(help="The port to run the server on.")] = 8000,
+    console: Annotated[bool, typer.Option("--console/--no-console", help="Launch the Operator Console in a browser.")] = True,
+):
+    """
+    Starts the Canon Gate server and optionally launches the console.
+    """
+    url = f"http://{host}:{port}"
+    print(f"Canon Gate server starting on {url}")
+
+    if console:
+        print(f"Launching Operator Console in your browser: {url}/console")
+        typer.launch(f"{url}/console")
+    
+    from canon_gate.boundary.main import app as fastapi_app
+    uvicorn.run(fastapi_app, host=host, port=port)
+
+@app.command()
+def demo():
+    """
+    Runs the full, orchestrated reference demonstration.
+    """
+    from canon_gate.demo import run_full_demo
+    run_full_demo()
+
+@app.command()
+def init(
+    force: Annotated[bool, typer.Option("--force", "-f", help="Overwrite existing policy.toml and adapter_policy.toml files if they exist.")] = False
+):
+    """
+    Initializes a new Canon Gate project with example policy templates.
+    """
+    from importlib import resources
+    from pathlib import Path
+    
+    policy_dest = Path.cwd() / "policy.toml"
+    adapter_dest = Path.cwd() / "adapter_policy.toml"
+    
+    # 1. Checks if files exist
+    if not force:
+        exists_files = []
+        if policy_dest.exists():
+            exists_files.append("policy.toml")
+        if adapter_dest.exists():
+            exists_files.append("adapter_policy.toml")
+        
+        if exists_files:
+            print(f"❌ ERROR: Project initialization aborted.")
+            print(f"The following configuration files already exist: {', '.join(exists_files)}")
+            print("Use --force (or -f) to overwrite them.")
+            raise typer.Exit(code=1)
+            
+    # 2. Load templates from package resources
+    try:
+        policy_content = resources.files("canon_gate.resources").joinpath("policy.example.toml").read_text(encoding="utf-8")
+        adapter_content = resources.files("canon_gate.resources").joinpath("adapter_policy.example.toml").read_text(encoding="utf-8")
+    except Exception as e:
+        print(f"❌ ERROR: Failed to load packaged templates: {e}")
+        raise typer.Exit(code=1)
+        
+    # 3. Write templates to destination
+    try:
+        policy_dest.write_text(policy_content, encoding="utf-8")
+        adapter_dest.write_text(adapter_content, encoding="utf-8")
+    except Exception as e:
+        print(f"❌ ERROR: Failed to write policy files to current directory: {e}")
+        raise typer.Exit(code=1)
+        
+    print("canon-gate init\n")
+    print("↓\n")
+    print("Initialized Canon Gate project.")
+    print("Created:")
+    print("    policy.toml")
+    print("    adapter_policy.toml")
+
+if __name__ == "__main__":
+    app()

canon_gate/core/__init__.py

@@ -0,0 +1 @@
+# Core validation engine

canon_gate/core/adapters.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any, Dict
+
+if TYPE_CHECKING:
+    from .models import ActionProposal, AdapterManifest
+
+
+class BaseAdapter(ABC):
+    """
+    The abstract base class for all execution adapters.
+
+    Each adapter is responsible for handling the execution logic for a single,
+    specific action type. It is also responsible for describing its own
+    capabilities for runtime discovery via a manifest.
+    """
+
+    @abstractmethod
+    def get_manifest(self) -> "AdapterManifest":
+        """
+        Returns a manifest describing the adapter's capabilities, including
+        the actions it supports and their parameter schemas.
+        """
+        pass
+
+    @abstractmethod
+    def execute(self, proposal: "ActionProposal") -> Dict[str, Any]:
+        """
+        Executes the validated action.
+
+        Args:
+            proposal: The validated ActionProposal object.
+
+        Returns:
+            A dictionary containing the results of the execution, which will
+            be embedded in the final GateDecision. Must include at least
+            a "status" and "message" key.
+        """
+        pass

canon_gate/core/config.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import toml
+from pydantic import BaseModel, Field
+from typing import List, Set
+import logging
+from importlib import resources
+from pathlib import Path
+
+# --- Ingress Policy Models ---
+
+class ActionsConfig(BaseModel):
+    allowed: Set[str] = Field(default_factory=set)
+
+class PolicyConfig(BaseModel):
+    actions: ActionsConfig = ActionsConfig()
+
+# --- Egress Policy Models ---
+
+class RunQueryAdapterPolicy(BaseModel):
+    forbidden_keywords: Set[str] = Field(default_factory=set)
+
+class ScriptAdapterPolicy(BaseModel):
+    allowed_scripts: Set[str] = Field(default_factory=set)
+
+class AdapterPolicyConfig(BaseModel):
+    run_query_adapter: RunQueryAdapterPolicy = RunQueryAdapterPolicy()
+    execute_script_adapter: ScriptAdapterPolicy = ScriptAdapterPolicy()
+
+# --- Settings Loading ---
+
+def _load_local_policy(filename: str) -> dict:
+    """
+    Loads a policy file from the current working directory.
+    Does NOT fall back to package-bundled files to maintain
+    strict Default-Deny and preserve explicit operator ownership.
+    """
+    policy_path = Path.cwd() / filename
+    try:
+        if policy_path.is_file():
+            with open(policy_path, "r", encoding="utf-8") as f:
+                return toml.load(f)
+    except Exception as e:
+        logging.error(f"Error reading local policy file '{filename}': {e}")
+    return {}
+
+# Load Ingress Policy (policy.toml)
+_policy_config = PolicyConfig()
+try:
+    if not (Path.cwd() / "policy.toml").is_file():
+        warning_msg = (
+            "\n"
+            "===============================================================================\n"
+            " No local policy.toml was found.\n\n"
+            " Canon Gate is operating in Default-Deny mode.\n"
+            " No actions will be permitted until a project policy is supplied.\n\n"
+            " To create starter policy files run:\n"
+            "     canon-gate init\n"
+            "==============================================================================="
+        )
+        print(warning_msg)
+        logging.warning("No local policy.toml was found. Canon Gate is operating in Default-Deny mode.")
+    else:
+        policy_data = _load_local_policy("policy.toml")
+        if policy_data:
+            _policy_config = PolicyConfig.model_validate(policy_data)
+except Exception as e:
+    logging.error(f"Failed to load or parse policy.toml: {e}")
+    _policy_config = PolicyConfig()
+
+# Load Egress Policy (adapter_policy.toml)
+_adapter_policy_config = AdapterPolicyConfig()
+try:
+    if (Path.cwd() / "adapter_policy.toml").is_file():
+        adapter_policy_data = _load_local_policy("adapter_policy.toml")
+        if adapter_policy_data:
+            _adapter_policy_config = AdapterPolicyConfig.model_validate(adapter_policy_data)
+except Exception as e:
+    logging.error(f"Failed to load or parse adapter_policy.toml: {e}")
+    _adapter_policy_config = AdapterPolicyConfig()
+
+# --- Publicly Exposed Settings ---
+
+# Ingress Settings
+ALLOWED_ACTIONS: Set[str] = _policy_config.actions.allowed
+
+# Egress Settings
+RUN_QUERY_FORBIDDEN_KEYWORDS: Set[str] = _adapter_policy_config.run_query_adapter.forbidden_keywords
+SCRIPT_ADAPTER_ALLOWED_SCRIPTS: Set[str] = _adapter_policy_config.execute_script_adapter.allowed_scripts