canopy-runtime 0.1.1__tar.gz

canopy_runtime-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mavericksantander
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

canopy_runtime-0.1.1/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: canopy-runtime
+Version: 0.1.1
+Summary: Canopy Agent Safety Runtime: policy enforcement for tool-using agents
+Author: Canopy
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: http
+Requires-Dist: requests>=2.25; extra == "http"
+Provides-Extra: gateway
+Requires-Dist: fastapi>=0.100; extra == "gateway"
+Requires-Dist: pydantic>=2; extra == "gateway"
+Requires-Dist: uvicorn[standard]>=0.23; extra == "gateway"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: httpx>=0.24; extra == "dev"
+Requires-Dist: requests>=2.25; extra == "dev"
+Requires-Dist: fastapi>=0.100; extra == "dev"
+Requires-Dist: pydantic>=2; extra == "dev"
+Requires-Dist: uvicorn[standard]>=0.23; extra == "dev"
+Dynamic: license-file
+
+# Canopy Runtime
+
+Minimal **Agent Safety Runtime** focused on a single primitive:
+
+`authorize_action(agent_ctx, action_type, action_payload)` → `{decision, reason, avid}`
+
+Decisions:
+- `ALLOW`
+- `DENY`
+- `REQUIRE_APPROVAL`
+
+Every decision is appended to a JSONL **hash-chain audit log** (`audit.log` by default).
+
+## 3‑minute quickstart (library)
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -U pip
+pip install canopy-runtime
+```
+
+```python
+from canopy import authorize_action
+
+decision = authorize_action(
+    agent_ctx={"env": "production"},
+    action_type="execute_shell",
+    action_payload={"command": "rm -rf /tmp/logs"},
+)
+print(decision["decision"])  # DENY
+```
+
+You should also see an `audit.log` file created in the current directory.
+
+Try the included demo:
+```bash
+canopy-demo
+canopy-demo --safe-path /tmp/
+```
+
+## Default policy pack (works out of the box)
+Bundled defaults live at `src/canopy/policies/default.yaml` and aim to be conservative:
+- `execute_shell`: deny common destructive patterns; require approval for network/install-style commands.
+- `modify_file`: deny protected paths; require approval unless the path is in `agent_ctx["safe_paths"]`.
+- `call_external_api`: require approval.
+
+## Config
+- `CANOPY_POLICY_FILE`: path to a YAML policy file (defaults to the bundled `default.yaml`)
+- `CANOPY_AUDIT_LOG_PATH`: path to audit log (defaults to `audit.log`)
+- `agent_ctx["safe_paths"]`: allowlist for `modify_file` (e.g. `["/repo/", "/tmp/"]`)
+
+## Optional gateway (HTTP)
+```bash
+pip install canopy-runtime[gateway]
+CANOPY_AUDIT_LOG_PATH=/tmp/canopy_audit.log python -m uvicorn canopy.service:app --port 8010
+```
+
+## Tests (dev)
+```bash
+pip install -e ".[dev]"
+pytest -q
+```
+
+## Easter egg
+```js
+// Nunca se usa pero no quitar por si acaso
+const _ = "QmUgYm9sZCBhbmQgbWlnaHR5IGZvcmNlcyB3aWxsIGNvbWUgdG8geW91ciBhaWQu"; // base64
+
+// si algún día te aburres:
+// console.log(atob(_))
+```

canopy_runtime-0.1.1/README.md

@@ -0,0 +1,71 @@
+# Canopy Runtime
+
+Minimal **Agent Safety Runtime** focused on a single primitive:
+
+`authorize_action(agent_ctx, action_type, action_payload)` → `{decision, reason, avid}`
+
+Decisions:
+- `ALLOW`
+- `DENY`
+- `REQUIRE_APPROVAL`
+
+Every decision is appended to a JSONL **hash-chain audit log** (`audit.log` by default).
+
+## 3‑minute quickstart (library)
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -U pip
+pip install canopy-runtime
+```
+
+```python
+from canopy import authorize_action
+
+decision = authorize_action(
+    agent_ctx={"env": "production"},
+    action_type="execute_shell",
+    action_payload={"command": "rm -rf /tmp/logs"},
+)
+print(decision["decision"])  # DENY
+```
+
+You should also see an `audit.log` file created in the current directory.
+
+Try the included demo:
+```bash
+canopy-demo
+canopy-demo --safe-path /tmp/
+```
+
+## Default policy pack (works out of the box)
+Bundled defaults live at `src/canopy/policies/default.yaml` and aim to be conservative:
+- `execute_shell`: deny common destructive patterns; require approval for network/install-style commands.
+- `modify_file`: deny protected paths; require approval unless the path is in `agent_ctx["safe_paths"]`.
+- `call_external_api`: require approval.
+
+## Config
+- `CANOPY_POLICY_FILE`: path to a YAML policy file (defaults to the bundled `default.yaml`)
+- `CANOPY_AUDIT_LOG_PATH`: path to audit log (defaults to `audit.log`)
+- `agent_ctx["safe_paths"]`: allowlist for `modify_file` (e.g. `["/repo/", "/tmp/"]`)
+
+## Optional gateway (HTTP)
+```bash
+pip install canopy-runtime[gateway]
+CANOPY_AUDIT_LOG_PATH=/tmp/canopy_audit.log python -m uvicorn canopy.service:app --port 8010
+```
+
+## Tests (dev)
+```bash
+pip install -e ".[dev]"
+pytest -q
+```
+
+## Easter egg
+```js
+// Nunca se usa pero no quitar por si acaso
+const _ = "QmUgYm9sZCBhbmQgbWlnaHR5IGZvcmNlcyB3aWxsIGNvbWUgdG8geW91ciBhaWQu"; // base64
+
+// si algún día te aburres:
+// console.log(atob(_))
+```

canopy_runtime-0.1.1/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "canopy-runtime"
+version = "0.1.1"
+description = "Canopy Agent Safety Runtime: policy enforcement for tool-using agents"
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [{ name = "Canopy" }]
+dependencies = []
+
+[project.scripts]
+canopy-demo = "canopy.demo:main"
+
+[project.optional-dependencies]
+http = ["requests>=2.25"]
+gateway = ["fastapi>=0.100", "pydantic>=2", "uvicorn[standard]>=0.23"]
+dev = ["pytest>=7", "httpx>=0.24", "requests>=2.25", "fastapi>=0.100", "pydantic>=2", "uvicorn[standard]>=0.23"]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["canopy*"]
+
+[tool.setuptools.package-data]
+canopy = ["policies/*.yaml"]

canopy_runtime-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

canopy_runtime-0.1.1/src/canopy/__init__.py

@@ -0,0 +1,12 @@
+"""Canopy Agent Safety Runtime (minimal).
+
+Core primitive:
+  - authorize_action(agent_ctx, action_type, action_payload) -> decision dict
+"""
+
+from .client import CanopyClient
+from .core import Decision, authorize_action
+from .middleware import guard_tool, guard_tool_http
+
+__all__ = ["CanopyClient", "Decision", "authorize_action", "guard_tool", "guard_tool_http"]
+

canopy_runtime-0.1.1/src/canopy/audit.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, Iterable, Optional
+
+
+def _canonical_json(obj: Any) -> bytes:
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False, default=str).encode("utf-8")
+
+
+def _sha256_hex(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+@dataclass(frozen=True)
+class AuditEntry:
+    timestamp: str
+    avid: str
+    action_type: str
+    decision: str
+    reason: str
+    prev_hash: str
+    entry_hash: str
+
+    def as_dict(self) -> Dict[str, Any]:
+        return {
+            "timestamp": self.timestamp,
+            "avid": self.avid,
+            "action_type": self.action_type,
+            "decision": self.decision,
+            "reason": self.reason,
+            "prev_hash": self.prev_hash,
+            "entry_hash": self.entry_hash,
+        }
+
+
+class HashChainAuditLog:
+    """Append-only JSONL audit log with a simple hash chain."""
+
+    def __init__(self, path: str | Path = "audit.log"):
+        self.path = Path(path)
+
+    def _read_last_hash(self) -> str:
+        if not self.path.exists():
+            return ""
+        last = ""
+        with self.path.open("rb") as f:
+            for line in f:
+                if line.strip():
+                    last = line.decode("utf-8")
+        if not last:
+            return ""
+        try:
+            obj = json.loads(last)
+            return str(obj.get("entry_hash", "") or "")
+        except Exception:
+            return ""
+
+    def append(
+        self,
+        *,
+        avid: str,
+        action_type: str,
+        decision: str,
+        reason: str,
+        timestamp: Optional[str] = None,
+    ) -> AuditEntry:
+        prev_hash = self._read_last_hash()
+        ts = timestamp or _now_iso()
+        base = {
+            "timestamp": ts,
+            "avid": avid,
+            "action_type": action_type,
+            "decision": decision,
+            "reason": reason,
+            "prev_hash": prev_hash,
+        }
+        entry_hash = _sha256_hex(prev_hash.encode("utf-8") + _canonical_json(base))
+        entry = AuditEntry(
+            timestamp=ts,
+            avid=avid,
+            action_type=action_type,
+            decision=decision,
+            reason=reason,
+            prev_hash=prev_hash,
+            entry_hash=entry_hash,
+        )
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        with self.path.open("a", encoding="utf-8") as f:
+            f.write(json.dumps(entry.as_dict(), ensure_ascii=False) + "\n")
+        return entry
+
+    def iter_entries(self) -> Iterable[Dict[str, Any]]:
+        if not self.path.exists():
+            return []
+        with self.path.open("r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                yield json.loads(line)
+
+    def verify_integrity(self) -> bool:
+        prev_hash = ""
+        for entry in self.iter_entries():
+            if str(entry.get("prev_hash", "")) != prev_hash:
+                return False
+            base = {
+                "timestamp": entry.get("timestamp"),
+                "avid": entry.get("avid"),
+                "action_type": entry.get("action_type"),
+                "decision": entry.get("decision"),
+                "reason": entry.get("reason"),
+                "prev_hash": entry.get("prev_hash", ""),
+            }
+            expected = _sha256_hex(prev_hash.encode("utf-8") + _canonical_json(base))
+            if str(entry.get("entry_hash", "")) != expected:
+                return False
+            prev_hash = expected
+        return True
+

canopy_runtime-0.1.1/src/canopy/client.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+
+@dataclass
+class CanopyClient:
+    base_url: str = "http://127.0.0.1:8010"
+    timeout_s: float = 5.0
+    headers: Optional[Dict[str, str]] = None
+
+    # For tests or advanced usage you can inject a TestClient/httpx-style client.
+    http_client: Any = None
+
+    def authorize_action(self, agent_ctx: Dict[str, Any], action_type: str, action_payload: Any) -> Dict[str, Any]:
+        payload = {"agent_ctx": agent_ctx or {}, "action_type": action_type, "action_payload": action_payload}
+        if self.http_client is not None:
+            res = self.http_client.post("/authorize_action", json=payload)
+            res.raise_for_status()
+            return res.json()
+
+        try:
+            import requests  # type: ignore
+        except ModuleNotFoundError as e:
+            raise ModuleNotFoundError(
+                "Optional dependency missing: install HTTP client support with `pip install canopy-runtime[http]`"
+            ) from e
+
+        url = self.base_url.rstrip("/") + "/authorize_action"
+        res = requests.post(url, json=payload, headers=self.headers, timeout=self.timeout_s)
+        res.raise_for_status()
+        return res.json()

canopy_runtime-0.1.1/src/canopy/core.py

@@ -0,0 +1,257 @@
+from __future__ import annotations
+
+import os
+import re
+from enum import Enum
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from .audit import HashChainAuditLog
+from .identity import generate_avid
+
+
+class Decision(str, Enum):
+    ALLOW = "ALLOW"
+    DENY = "DENY"
+    REQUIRE_APPROVAL = "REQUIRE_APPROVAL"
+
+
+def _parse_minimal_yaml(text: str) -> Dict[str, Any]:
+    """Parse a tiny subset of YAML without external dependencies.
+
+    Supports:
+      rules:
+        - action_type: "execute_shell"
+          deny_if: "rm -rf"
+        - action_type: "execute_shell"
+          deny_if:
+            - "sudo"
+            - "mkfs"
+          deny_regex: 'rm\\s+-rf'
+        - action_type: "call_external_api"
+          require_approval: true
+    """
+    lines = [ln.rstrip("\n") for ln in text.splitlines() if ln.strip() and not ln.strip().startswith("#")]
+    out: Dict[str, Any] = {"rules": []}
+    rules: List[Dict[str, Any]] = out["rules"]
+
+    def parse_scalar(v: str) -> Any:
+        v = v.strip()
+        if v.lower() in {"true", "false"}:
+            return v.lower() == "true"
+        if (v.startswith('"') and v.endswith('"')) or (v.startswith("'") and v.endswith("'")):
+            return v[1:-1]
+        return v
+
+    i = 0
+    in_rules = False
+    current: Optional[Dict[str, Any]] = None
+    while i < len(lines):
+        ln = lines[i]
+        stripped = ln.lstrip(" ")
+        indent = len(ln) - len(stripped)
+        if indent == 0 and stripped == "rules:":
+            in_rules = True
+            current = None
+            i += 1
+            continue
+
+        if not in_rules:
+            i += 1
+            continue
+
+        if stripped.startswith("- "):
+            current = {}
+            rules.append(current)
+            rest = stripped[2:].strip()
+            if rest and ":" in rest:
+                k, v = rest.split(":", 1)
+                current[k.strip()] = parse_scalar(v)
+            i += 1
+            continue
+
+        if current is not None and ":" in stripped:
+            k, v = stripped.split(":", 1)
+            key = k.strip()
+            val = v.strip()
+            if val == "":
+                items: List[Any] = []
+                i += 1
+                while i < len(lines):
+                    ln2 = lines[i]
+                    stripped2 = ln2.lstrip(" ")
+                    indent2 = len(ln2) - len(stripped2)
+                    if indent2 <= indent:
+                        break
+                    if stripped2.startswith("- "):
+                        items.append(parse_scalar(stripped2[2:]))
+                    i += 1
+                current[key] = items
+                continue
+            current[key] = parse_scalar(val)
+        i += 1
+    return out
+
+
+def load_policies(policy_file: str | Path) -> Dict[str, Any]:
+    return _parse_minimal_yaml(Path(policy_file).read_text(encoding="utf-8"))
+
+
+def _default_policy_file() -> Path:
+    return Path(__file__).with_name("policies") / "default.yaml"
+
+
+def _payload_text(payload: Any) -> str:
+    if payload is None:
+        return ""
+    if isinstance(payload, str):
+        return payload
+    if isinstance(payload, dict):
+        # Prefer deterministic rendering for matching/logging.
+        try:
+            import json
+
+            return json.dumps(payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False, default=str)
+        except Exception:
+            return str(payload)
+    return str(payload)
+
+
+def _match_text(action_type: str, action_payload: Any) -> str:
+    """Extract the primary matching string for a given action type.
+
+    This keeps policies stable when payloads are structured dicts.
+    """
+    if isinstance(action_payload, dict):
+        if action_type == "execute_shell":
+            return str(action_payload.get("command", "") or "")
+        if action_type == "modify_file":
+            return str(action_payload.get("path", "") or "")
+        if action_type == "call_external_api":
+            return str(action_payload.get("url", "") or action_payload.get("endpoint", "") or "")
+    return _payload_text(action_payload)
+
+
+def _safe_paths(ctx: Dict[str, Any]) -> List[str]:
+    sp = ctx.get("safe_paths")
+    if isinstance(sp, list):
+        return [str(x) for x in sp]
+    return []
+
+
+def authorize_action(
+    agent_ctx: Dict[str, Any],
+    action_type: str,
+    action_payload: Any,
+    *,
+    policy_file: str | Path | None = None,
+    audit_log_path: str | Path | None = None,
+) -> Dict[str, Any]:
+    """Authorize an agent action and append a hash-chain audit entry."""
+    ctx = dict(agent_ctx or {})
+    avid = str(ctx.get("avid") or "") or generate_avid(ctx)
+
+    pf = Path(policy_file) if policy_file else _default_policy_file()
+    policies = load_policies(pf)
+    rules = policies.get("rules") if isinstance(policies.get("rules"), list) else []
+
+    decision = Decision.ALLOW
+    reason = "Allowed by default"
+
+    payload_text = _match_text(action_type, action_payload).lower()
+    for rule in rules:
+        if not isinstance(rule, dict):
+            continue
+        if str(rule.get("action_type", "")).strip() != action_type:
+            continue
+
+        if rule.get("require_approval") is True:
+            decision = Decision.REQUIRE_APPROVAL
+            reason = "Policy requires approval"
+            break
+
+        require_if = rule.get("require_approval_if")
+        require_items: List[str]
+        if isinstance(require_if, str):
+            require_items = [require_if]
+        elif isinstance(require_if, list):
+            require_items = [str(x) for x in require_if if str(x).strip()]
+        else:
+            require_items = []
+        for item in require_items:
+            if item.lower() in payload_text:
+                decision = Decision.REQUIRE_APPROVAL
+                reason = f"Policy requires approval: matched '{item}'"
+                break
+        if decision == Decision.REQUIRE_APPROVAL:
+            break
+
+        require_regex = rule.get("require_approval_regex")
+        req_regexes: List[str]
+        if isinstance(require_regex, str):
+            req_regexes = [require_regex]
+        elif isinstance(require_regex, list):
+            req_regexes = [str(x) for x in require_regex if str(x).strip()]
+        else:
+            req_regexes = []
+        for rx in req_regexes:
+            if re.search(rx, payload_text):
+                decision = Decision.REQUIRE_APPROVAL
+                reason = f"Policy requires approval: matched /{rx}/"
+                break
+        if decision == Decision.REQUIRE_APPROVAL:
+            break
+
+        deny_if = rule.get("deny_if")
+        deny_items: List[str]
+        if isinstance(deny_if, str):
+            deny_items = [deny_if]
+        elif isinstance(deny_if, list):
+            deny_items = [str(x) for x in deny_if if str(x).strip()]
+        else:
+            deny_items = []
+        for item in deny_items:
+            if item.lower() in payload_text:
+                decision = Decision.DENY
+                reason = f"Denied by policy: matched '{item}'"
+                break
+        if decision == Decision.DENY:
+            break
+
+        allow_if = rule.get("allow_if")
+        if allow_if == "safe_paths":
+            if isinstance(action_payload, dict):
+                path = str(action_payload.get("path", "") or "")
+            else:
+                path = str(action_payload or "")
+            safe_prefixes = _safe_paths(ctx)
+            if not safe_prefixes:
+                decision = Decision.REQUIRE_APPROVAL
+                reason = "Policy requires approval: safe_paths not configured"
+            elif any(path.startswith(prefix) for prefix in safe_prefixes):
+                decision = Decision.ALLOW
+                reason = "Allowed by policy: safe_paths"
+            else:
+                decision = Decision.DENY
+                reason = "Denied by policy: unsafe path"
+            break
+
+        deny_regex = rule.get("deny_regex")
+        regexes: List[str]
+        if isinstance(deny_regex, str):
+            regexes = [deny_regex]
+        elif isinstance(deny_regex, list):
+            regexes = [str(x) for x in deny_regex if str(x).strip()]
+        else:
+            regexes = []
+        for rx in regexes:
+            if re.search(rx, payload_text):
+                decision = Decision.DENY
+                reason = f"Denied by policy: matched /{rx}/"
+                break
+        if decision == Decision.DENY:
+            break
+
+    alp = Path(audit_log_path) if audit_log_path else Path(os.getenv("CANOPY_AUDIT_LOG_PATH", "audit.log"))
+    HashChainAuditLog(alp).append(avid=avid, action_type=action_type, decision=decision.value, reason=reason)
+    return {"decision": decision.value, "reason": reason, "avid": avid}

canopy_runtime-0.1.1/src/canopy/demo.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from .core import authorize_action
+
+
+def _print_decision(label: str, decision: Dict[str, Any]) -> None:
+    d = decision.get("decision")
+    reason = decision.get("reason")
+    avid = decision.get("avid")
+    print(f"{label}: {d} — {reason} (avid={avid})")
+
+
+def _parse_args(argv: Optional[List[str]] = None) -> argparse.Namespace:
+    p = argparse.ArgumentParser(description="Canopy demo: authorize actions and write an audit log.")
+    p.add_argument("--env", default="production", help="agent_ctx env label (default: production)")
+    p.add_argument(
+        "--safe-path",
+        action="append",
+        default=[],
+        help='repeatable; adds to agent_ctx["safe_paths"] (example: --safe-path /tmp/)',
+    )
+    p.add_argument("--policy-file", default=None, help="path to a YAML policy file (defaults to bundled policy)")
+    p.add_argument("--audit-log-path", default=None, help="path to audit log (default: ./audit.log)")
+    p.add_argument("--no-write", action="store_true", help="do not write any files (default: writes are simulated)")
+    return p.parse_args(argv)
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    args = _parse_args(argv)
+    agent_ctx: Dict[str, Any] = {"env": args.env}
+    if args.safe_path:
+        agent_ctx["safe_paths"] = list(args.safe_path)
+
+    policy_file = args.policy_file
+    audit_log_path = args.audit_log_path
+
+    print("Canopy demo — decisions + audit log")
+    print(f"agent_ctx={agent_ctx}")
+    print(f"audit_log_path={audit_log_path or 'audit.log'}")
+    print("")
+
+    _print_decision(
+        "1) execute_shell rm -rf",
+        authorize_action(
+            agent_ctx,
+            "execute_shell",
+            {"command": "rm -rf /tmp/logs"},
+            policy_file=policy_file,
+            audit_log_path=audit_log_path,
+        ),
+    )
+    _print_decision(
+        "2) execute_shell curl http",
+        authorize_action(
+            agent_ctx,
+            "execute_shell",
+            {"command": "curl http://example.com"},
+            policy_file=policy_file,
+            audit_log_path=audit_log_path,
+        ),
+    )
+    _print_decision(
+        "3) modify_file /etc/passwd",
+        authorize_action(
+            agent_ctx,
+            "modify_file",
+            {"path": "/etc/passwd"},
+            policy_file=policy_file,
+            audit_log_path=audit_log_path,
+        ),
+    )
+
+    demo_path = str(Path("/tmp/canopy_demo.txt"))
+    decision = authorize_action(
+        agent_ctx,
+        "modify_file",
+        {"path": demo_path},
+        policy_file=policy_file,
+        audit_log_path=audit_log_path,
+    )
+    _print_decision(f"4) modify_file {demo_path}", decision)
+    if not args.no_write and decision.get("decision") == "ALLOW":
+        Path(demo_path).write_text("hello from canopy\n", encoding="utf-8")
+        print(f"   wrote {demo_path}")
+    else:
+        print("   (no write performed)")
+
+    _print_decision(
+        "5) call_external_api https://example.com",
+        authorize_action(
+            agent_ctx,
+            "call_external_api",
+            {"url": "https://example.com"},
+            policy_file=policy_file,
+            audit_log_path=audit_log_path,
+        ),
+    )
+
+    print("")
+    print("Tip: to allow writes, run with e.g. `--safe-path /tmp/`.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))
+

canopy_runtime-0.1.1/src/canopy/identity.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from datetime import datetime, timezone
+from typing import Any, Dict
+
+
+def _canonical_json(obj: Any) -> bytes:
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False, default=str).encode("utf-8")
+
+
+def generate_avid(agent_ctx: Dict[str, Any]) -> str:
+    """Generate an internal AVID for audit correlation.
+
+    If `created_at` is missing, it is set to a UTC ISO timestamp, which makes the AVID unique
+    but not stable across processes. Provide a stable `created_at` if you need stability.
+    """
+    ctx = dict(agent_ctx or {})
+    public_key = str(ctx.get("public_key", "") or "")
+    created_at = ctx.get("created_at")
+    if not created_at:
+        created_at = datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+        ctx["created_at"] = created_at
+
+    payload = {
+        "public_key": public_key,
+        "metadata": {k: v for k, v in ctx.items() if k not in {"public_key"}},
+        "created_at": created_at,
+    }
+    digest = hashlib.sha256(_canonical_json(payload)).hexdigest()
+    return f"AVID-{digest}"
+

canopy_runtime-0.1.1/src/canopy/middleware.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from functools import wraps
+from pathlib import Path
+from typing import Any, Callable, Dict, Optional, TypeVar
+
+from .client import CanopyClient
+from .core import authorize_action
+
+T = TypeVar("T")
+
+
+def _default_payload(args: tuple[Any, ...], kwargs: Dict[str, Any]) -> Any:
+    if len(args) == 1 and isinstance(args[0], str) and not kwargs:
+        return args[0]
+    return {"args": list(args), "kwargs": dict(kwargs)}
+
+
+def guard_tool(
+    *,
+    agent_ctx: Optional[Dict[str, Any]] = None,
+    action_type: Optional[str] = None,
+    payload_builder: Optional[Callable[..., Any]] = None,
+    policy_file: str | Path | None = None,
+    audit_log_path: str | Path | None = None,
+) -> Callable[[Callable[..., T]], Callable[..., T]]:
+    """Decorator that gates tool execution using local `authorize_action`."""
+
+    def _decorator(fn: Callable[..., T]) -> Callable[..., T]:
+        atype = action_type or fn.__name__
+
+        @wraps(fn)
+        def _wrapped(*args: Any, **kwargs: Any) -> T:
+            payload = payload_builder(*args, **kwargs) if payload_builder else _default_payload(args, kwargs)
+            decision = authorize_action(
+                agent_ctx or {},
+                atype,
+                payload,
+                policy_file=policy_file,
+                audit_log_path=audit_log_path,
+            )
+            d = (decision.get("decision") or "").upper()
+            if d != "ALLOW":
+                raise PermissionError(decision.get("reason") or "Blocked by policy")
+            return fn(*args, **kwargs)
+
+        return _wrapped
+
+    return _decorator
+
+
+def guard_tool_http(
+    *,
+    client: CanopyClient,
+    agent_ctx: Dict[str, Any],
+    action_type: str,
+    payload_builder: Optional[Callable[..., Any]] = None,
+) -> Callable[[Callable[..., T]], Callable[..., T]]:
+    """Decorator that gates execution via the HTTP gateway."""
+
+    def _decorator(fn: Callable[..., T]) -> Callable[..., T]:
+        @wraps(fn)
+        def _wrapped(*args: Any, **kwargs: Any) -> T:
+            payload = payload_builder(*args, **kwargs) if payload_builder else _default_payload(args, kwargs)
+            decision = client.authorize_action(agent_ctx, action_type, payload)
+            d = (decision.get("decision") or "").upper()
+            if d != "ALLOW":
+                raise PermissionError(decision.get("reason") or "Blocked by policy")
+            return fn(*args, **kwargs)
+
+        return _wrapped
+
+    return _decorator
+

canopy_runtime-0.1.1/src/canopy/policies/default.yaml

@@ -0,0 +1,43 @@
+rules:
+  - action_type: "execute_shell"
+    deny_regex:
+      - 'rm\s+-rf'
+      - ':\(\)\s*\{\s*:\s*\|\s*:\s*&\s*\};'   # fork bomb
+  - action_type: "execute_shell"
+    require_approval_if:
+      - "curl http"
+      - "wget http"
+      - "ssh "
+      - "scp "
+      - "rsync "
+      - "apt-get "
+      - "yum "
+      - "brew install"
+      - "pip install"
+    deny_if:
+      - "rm -rf"
+      - "sudo"
+      - "mkfs"
+      - "dd "
+      - "chmod 777"
+      - "chown "
+      - "shutdown"
+      - "reboot"
+      - "kill -9 1"
+  - action_type: "modify_file"
+    deny_if:
+      - "/etc/"
+      - "/usr/"
+      - "/bin/"
+      - "/sbin/"
+      - "/var/lib/"
+      - ".ssh"
+      - ".aws"
+      - ".kube"
+      - ".env"
+  - action_type: "modify_file"
+    allow_if: "safe_paths"
+  - action_type: "call_external_api"
+    require_approval: true
+  - action_type: "spend_money"
+    require_approval: true

canopy_runtime-0.1.1/src/canopy/service.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any, Dict
+
+from fastapi import FastAPI
+from pydantic import BaseModel, Field
+
+from .core import authorize_action
+
+
+def _default_policy_file() -> Path:
+    return Path(__file__).with_name("policies") / "default.yaml"
+
+
+class ActionRequest(BaseModel):
+    agent_ctx: Dict[str, Any] = Field(default_factory=dict)
+    action_type: str
+    action_payload: Any = Field(default_factory=dict)
+
+
+app = FastAPI(title="Canopy Runtime", version="0.1.0")
+
+
+@app.post("/authorize_action")
+async def authorize(req: ActionRequest):
+    policy_file = os.getenv("CANOPY_POLICY_FILE")
+    audit_log_path = os.getenv("CANOPY_AUDIT_LOG_PATH", "audit.log")
+    return authorize_action(
+        req.agent_ctx,
+        req.action_type,
+        req.action_payload,
+        policy_file=policy_file or _default_policy_file(),
+        audit_log_path=audit_log_path,
+    )
+

canopy_runtime-0.1.1/src/canopy_runtime.egg-info/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: canopy-runtime
+Version: 0.1.1
+Summary: Canopy Agent Safety Runtime: policy enforcement for tool-using agents
+Author: Canopy
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: http
+Requires-Dist: requests>=2.25; extra == "http"
+Provides-Extra: gateway
+Requires-Dist: fastapi>=0.100; extra == "gateway"
+Requires-Dist: pydantic>=2; extra == "gateway"
+Requires-Dist: uvicorn[standard]>=0.23; extra == "gateway"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: httpx>=0.24; extra == "dev"
+Requires-Dist: requests>=2.25; extra == "dev"
+Requires-Dist: fastapi>=0.100; extra == "dev"
+Requires-Dist: pydantic>=2; extra == "dev"
+Requires-Dist: uvicorn[standard]>=0.23; extra == "dev"
+Dynamic: license-file
+
+# Canopy Runtime
+
+Minimal **Agent Safety Runtime** focused on a single primitive:
+
+`authorize_action(agent_ctx, action_type, action_payload)` → `{decision, reason, avid}`
+
+Decisions:
+- `ALLOW`
+- `DENY`
+- `REQUIRE_APPROVAL`
+
+Every decision is appended to a JSONL **hash-chain audit log** (`audit.log` by default).
+
+## 3‑minute quickstart (library)
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -U pip
+pip install canopy-runtime
+```
+
+```python
+from canopy import authorize_action
+
+decision = authorize_action(
+    agent_ctx={"env": "production"},
+    action_type="execute_shell",
+    action_payload={"command": "rm -rf /tmp/logs"},
+)
+print(decision["decision"])  # DENY
+```
+
+You should also see an `audit.log` file created in the current directory.
+
+Try the included demo:
+```bash
+canopy-demo
+canopy-demo --safe-path /tmp/
+```
+
+## Default policy pack (works out of the box)
+Bundled defaults live at `src/canopy/policies/default.yaml` and aim to be conservative:
+- `execute_shell`: deny common destructive patterns; require approval for network/install-style commands.
+- `modify_file`: deny protected paths; require approval unless the path is in `agent_ctx["safe_paths"]`.
+- `call_external_api`: require approval.
+
+## Config
+- `CANOPY_POLICY_FILE`: path to a YAML policy file (defaults to the bundled `default.yaml`)
+- `CANOPY_AUDIT_LOG_PATH`: path to audit log (defaults to `audit.log`)
+- `agent_ctx["safe_paths"]`: allowlist for `modify_file` (e.g. `["/repo/", "/tmp/"]`)
+
+## Optional gateway (HTTP)
+```bash
+pip install canopy-runtime[gateway]
+CANOPY_AUDIT_LOG_PATH=/tmp/canopy_audit.log python -m uvicorn canopy.service:app --port 8010
+```
+
+## Tests (dev)
+```bash
+pip install -e ".[dev]"
+pytest -q
+```
+
+## Easter egg
+```js
+// Nunca se usa pero no quitar por si acaso
+const _ = "QmUgYm9sZCBhbmQgbWlnaHR5IGZvcmNlcyB3aWxsIGNvbWUgdG8geW91ciBhaWQu"; // base64
+
+// si algún día te aburres:
+// console.log(atob(_))
+```

canopy_runtime-0.1.1/src/canopy_runtime.egg-info/SOURCES.txt

@@ -0,0 +1,21 @@
+LICENSE
+README.md
+pyproject.toml
+src/canopy/__init__.py
+src/canopy/audit.py
+src/canopy/client.py
+src/canopy/core.py
+src/canopy/demo.py
+src/canopy/identity.py
+src/canopy/middleware.py
+src/canopy/service.py
+src/canopy/policies/default.yaml
+src/canopy_runtime.egg-info/PKG-INFO
+src/canopy_runtime.egg-info/SOURCES.txt
+src/canopy_runtime.egg-info/dependency_links.txt
+src/canopy_runtime.egg-info/entry_points.txt
+src/canopy_runtime.egg-info/requires.txt
+src/canopy_runtime.egg-info/top_level.txt
+tests/test_authorize_action.py
+tests/test_client.py
+tests/test_service.py

canopy_runtime-0.1.1/src/canopy_runtime.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

canopy_runtime-0.1.1/src/canopy_runtime.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+canopy-demo = canopy.demo:main

canopy_runtime-0.1.1/src/canopy_runtime.egg-info/requires.txt

@@ -0,0 +1,16 @@
+
+[dev]
+pytest>=7
+httpx>=0.24
+requests>=2.25
+fastapi>=0.100
+pydantic>=2
+uvicorn[standard]>=0.23
+
+[gateway]
+fastapi>=0.100
+pydantic>=2
+uvicorn[standard]>=0.23
+
+[http]
+requests>=2.25

canopy_runtime-0.1.1/src/canopy_runtime.egg-info/top_level.txt

@@ -0,0 +1 @@
+canopy

canopy_runtime-0.1.1/tests/test_authorize_action.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from canopy.audit import HashChainAuditLog
+from canopy.core import authorize_action
+
+
+def test_deny_rm_rf(tmp_path: Path):
+    policy = tmp_path / "policy.yaml"
+    policy.write_text(
+        "\n".join(
+            [
+                "rules:",
+                '  - action_type: "execute_shell"',
+                '    deny_if: "rm -rf"',
+            ]
+        )
+        + "\n",
+        encoding="utf-8",
+    )
+    audit_path = tmp_path / "audit.log"
+    agent_ctx = {"public_key": "pk", "created_at": "2026-03-15T00:00:00Z"}
+    res = authorize_action(agent_ctx, "execute_shell", "rm -rf /", policy_file=policy, audit_log_path=audit_path)
+    assert res["decision"] == "DENY"
+    assert res["avid"].startswith("AVID-")
+
+
+def test_require_approval(tmp_path: Path):
+    policy = tmp_path / "policy.yaml"
+    policy.write_text(
+        "\n".join(
+            [
+                "rules:",
+                '  - action_type: "call_external_api"',
+                "    require_approval: true",
+            ]
+        )
+        + "\n",
+        encoding="utf-8",
+    )
+    audit_path = tmp_path / "audit.log"
+    agent_ctx = {"public_key": "pk", "created_at": "2026-03-15T00:00:00Z"}
+    res = authorize_action(
+        agent_ctx,
+        "call_external_api",
+        {"url": "https://example.com"},
+        policy_file=policy,
+        audit_log_path=audit_path,
+    )
+    assert res["decision"] == "REQUIRE_APPROVAL"
+
+
+def test_safe_paths(tmp_path: Path):
+    policy = tmp_path / "policy.yaml"
+    policy.write_text(
+        "\n".join(
+            [
+                "rules:",
+                '  - action_type: "modify_file"',
+                '    allow_if: "safe_paths"',
+            ]
+        )
+        + "\n",
+        encoding="utf-8",
+    )
+    audit_path = tmp_path / "audit.log"
+    agent_ctx = {"public_key": "pk", "created_at": "2026-03-15T00:00:00Z", "safe_paths": [str(tmp_path)]}
+    ok = authorize_action(
+        agent_ctx,
+        "modify_file",
+        {"path": str(tmp_path / "x.txt")},
+        policy_file=policy,
+        audit_log_path=audit_path,
+    )
+    assert ok["decision"] == "ALLOW"
+    bad = authorize_action(
+        agent_ctx,
+        "modify_file",
+        {"path": "/etc/passwd"},
+        policy_file=policy,
+        audit_log_path=audit_path,
+    )
+    assert bad["decision"] == "DENY"
+
+
+def test_audit_hash_chain_integrity(tmp_path: Path):
+    audit_path = tmp_path / "audit.log"
+    log = HashChainAuditLog(audit_path)
+    log.append(avid="AVID-1", action_type="t1", decision="ALLOW", reason="ok", timestamp="2026-03-15T00:00:00Z")
+    log.append(avid="AVID-1", action_type="t2", decision="DENY", reason="no", timestamp="2026-03-15T00:00:01Z")
+    assert log.verify_integrity() is True
+
+    lines = audit_path.read_text(encoding="utf-8").splitlines()
+    obj = json.loads(lines[1])
+    obj["reason"] = "tampered"
+    lines[1] = json.dumps(obj, ensure_ascii=False)
+    audit_path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    assert HashChainAuditLog(audit_path).verify_integrity() is False
+

canopy_runtime-0.1.1/tests/test_client.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from fastapi.testclient import TestClient
+
+from canopy.client import CanopyClient
+from canopy.service import app
+
+
+def test_client_against_service(monkeypatch, tmp_path):
+    monkeypatch.setenv("CANOPY_AUDIT_LOG_PATH", str(tmp_path / "audit.log"))
+    http = TestClient(app)
+    client = CanopyClient(http_client=http)
+    res = client.authorize_action(
+        {"public_key": "pk", "created_at": "2026-03-15T00:00:00Z"},
+        "call_external_api",
+        {"url": "https://example.com"},
+    )
+    assert res["decision"] == "REQUIRE_APPROVAL"
+

canopy_runtime-0.1.1/tests/test_service.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from fastapi.testclient import TestClient
+
+from canopy.service import app
+
+
+def test_service_authorize_action(monkeypatch, tmp_path):
+    monkeypatch.setenv("CANOPY_AUDIT_LOG_PATH", str(tmp_path / "audit.log"))
+    client = TestClient(app)
+    res = client.post(
+        "/authorize_action",
+        json={
+            "agent_ctx": {"public_key": "pk", "created_at": "2026-03-15T00:00:00Z"},
+            "action_type": "execute_shell",
+            "action_payload": "rm -rf /",
+        },
+    )
+    assert res.status_code == 200
+    data = res.json()
+    assert data["decision"] == "DENY"
+