chp-adapter-process 0.24.0__tar.gz

chp_adapter_process-0.24.0/.gitignore

@@ -0,0 +1,16 @@
+node_modules/
+dist/
+*.egg-info/
+__pycache__/
+.pytest_cache/
+.chp/
+.DS_Store
+*.tgz
+.env
+.env.*
+*.pyc
+.python-version
+.coverage
+.hypothesis/
+.chp-agent/
+*.sqlite

chp_adapter_process-0.24.0/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: chp-adapter-process
+Version: 0.24.0
+Summary: CHP capability adapter — governed subprocess/CLI execution
+Author: Auxo
+License: Apache-2.0
+Keywords: adapter,capability-host-protocol,chp,cli,process,subprocess
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: chp-core>=0.7.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'

chp_adapter_process-0.24.0/chp_adapter_process/__init__.py

@@ -0,0 +1,25 @@
+"""chp-adapter-process — governed subprocess/CLI execution as a CHP capability.
+
+One capability:
+
+* ``run`` — execute a command with args; allowlist + timeout + cwd-root enforcement.
+  Returns ``{exit_code, stdout, stderr, timed_out, duration_ms}``.
+  Evidence: command/args, env_additions keys (not values), exit code, previews.
+
+Usage::
+
+    from chp_core import LocalCapabilityHost, register_adapter
+    from chp_adapter_process import ProcessAdapter, ProcessConfig
+
+    host = LocalCapabilityHost()
+    register_adapter(host, ProcessAdapter(ProcessConfig(
+        allowed_commands=["echo", "ls"],
+        max_timeout=10.0,
+    )))
+"""
+
+from __future__ import annotations
+
+from .adapter import ProcessAdapter, ProcessConfig
+
+__all__ = ["ProcessAdapter", "ProcessConfig"]

chp_adapter_process-0.24.0/chp_adapter_process/adapter.py

@@ -0,0 +1,245 @@
+"""ProcessAdapter — governed subprocess/CLI execution as a CHP capability.
+
+Safety invariants (MUST PRESERVE):
+* ``shell=False`` always — prevents shell injection via args.
+* Command must be in ``allowed_commands`` if the list is non-None.
+* ``cwd`` must resolve under ``working_dir`` if one is configured.
+* Timeout enforced; process killed (SIGKILL) on expiry.
+* ``env_additions`` keys in evidence, values never (may carry secrets).
+* Full stdout/stderr returned as data; only 500-char previews in evidence.
+
+One capability: ``run``
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import time as _time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from chp_core import BaseAdapter, capability
+
+_EMITS = ["process_start", "process_result", "process_timeout", "process_error"]
+
+_PREVIEW_LEN = 500
+
+
+def _is_within(path: Path, root: Path) -> bool:
+    """True if *path* is *root* or lives under it — component-wise, not string
+    prefix (so 'working_dir-evil' is not 'within' 'working_dir')."""
+    try:
+        return path == root or path.is_relative_to(root)
+    except AttributeError:  # Python < 3.9
+        try:
+            return os.path.commonpath([str(path), str(root)]) == str(root)
+        except ValueError:
+            return False
+
+
+@dataclass
+class ProcessConfig:
+    """Config for ProcessAdapter.
+
+    ``allowed_commands`` — if non-None, only these command names (no path
+    required) may be executed. Pass ``None`` to allow all (use carefully).
+
+    ``working_dir`` — if set, ``cwd`` in payloads must resolve under this
+    root. Defaults to no restriction.
+
+    ``max_timeout`` — hard upper bound on any per-call ``timeout`` value.
+    """
+
+    allowed_commands: list[str] | None = None
+    working_dir: str | None = None
+    max_timeout: float = 60.0
+    max_output_bytes: int = 64 * 1024
+
+
+class ProcessAdapter(BaseAdapter):
+    """Governed subprocess/CLI execution."""
+
+    adapter_id = "chp.adapters.process"
+    adapter_name = "Process"
+    adapter_description = "Execute CLI commands with governed allowlist and timeout enforcement."
+    adapter_category = "execution"
+    adapter_tags = ["process", "subprocess", "cli", "execution"]
+
+    def __init__(self, config: ProcessConfig | None = None) -> None:
+        self._config = config or ProcessConfig()
+
+    # ------------------------------------------------------------------
+    # run
+    # ------------------------------------------------------------------
+
+    @capability(
+        id="chp.adapters.process.run",
+        version="1.0.0",
+        description="Execute a CLI command with arguments.",
+        category="execution",
+        risk="high",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "command": {"type": "string", "description": "Command to execute (no shell)."},
+                "args": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Command-line arguments.",
+                },
+                "cwd": {
+                    "type": "string",
+                    "description": "Working directory (must be under working_dir if configured).",
+                },
+                "timeout": {
+                    "type": "number",
+                    "minimum": 0.1,
+                    "description": "Timeout in seconds (capped at max_timeout).",
+                },
+                "env_additions": {
+                    "type": "object",
+                    "description": "Additional environment variables (keys in evidence, values not).",
+                    "additionalProperties": {"type": "string"},
+                },
+            },
+            "required": ["command"],
+            "additionalProperties": False,
+        },
+        emits=_EMITS,
+        tags=["process", "cli"],
+    )
+    async def run(self, ctx: Any, payload: dict) -> dict:
+        command = payload["command"]
+        args = payload.get("args") or []
+        cwd_raw = payload.get("cwd")
+        timeout = min(
+            float(payload.get("timeout") or self._config.max_timeout),
+            self._config.max_timeout,
+        )
+        env_additions = payload.get("env_additions") or {}
+
+        # --- allowlist check ---
+        cfg = self._config
+        if cfg.allowed_commands is not None and command not in cfg.allowed_commands:
+            ctx.emit("process_error", {
+                "reason": "command_not_allowed",
+                "command": command,
+            }, redacted=False)
+            raise PermissionError(f"Command {command!r} is not in allowed_commands")
+
+        # --- cwd check ---
+        cwd: str | None = None
+        if cwd_raw is not None:
+            resolved_cwd = Path(cwd_raw).resolve()
+            if cfg.working_dir is not None:
+                working_root = Path(cfg.working_dir).resolve()
+                # Component-wise containment, not string prefix: a sibling like
+                # 'working_dir-evil' must not pass as inside 'working_dir'.
+                if not _is_within(resolved_cwd, working_root):
+                    ctx.emit("process_error", {
+                        "reason": "cwd_outside_working_dir",
+                        "cwd": str(resolved_cwd),
+                    }, redacted=False)
+                    raise PermissionError(
+                        f"cwd {resolved_cwd} is outside working_dir {cfg.working_dir!r}"
+                    )
+            cwd = str(resolved_cwd)
+
+        # --- environment ---
+        env = dict(os.environ)
+        if env_additions:
+            env.update(env_additions)
+
+        ctx.emit("process_start", {
+            "command": command,
+            "args": args,
+            "cwd": cwd,
+            "timeout": timeout,
+            "env_additions_keys": sorted(env_additions.keys()),
+            # env_additions values intentionally not recorded
+        }, redacted=False)
+
+        t0 = _time.monotonic()
+        timed_out = False
+        stdout_str = ""
+        stderr_str = ""
+        exit_code = -1
+
+        try:
+            proc = await asyncio.create_subprocess_exec(
+                command, *args,
+                cwd=cwd,
+                env=env,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            try:
+                raw_stdout, raw_stderr = await asyncio.wait_for(
+                    proc.communicate(), timeout=timeout
+                )
+                exit_code = proc.returncode if proc.returncode is not None else -1
+            except asyncio.TimeoutError:
+                timed_out = True
+                try:
+                    proc.kill()
+                except ProcessLookupError:
+                    pass
+                await proc.communicate()
+                exit_code = -1
+
+        except FileNotFoundError:
+            duration_ms = int((_time.monotonic() - t0) * 1000)
+            ctx.emit("process_error", {
+                "command": command,
+                "reason": "command_not_found",
+                "duration_ms": duration_ms,
+            }, redacted=False)
+            raise
+
+        except Exception as exc:
+            duration_ms = int((_time.monotonic() - t0) * 1000)
+            ctx.emit("process_error", {
+                "command": command,
+                "reason": type(exc).__name__,
+                "error": str(exc)[:200],
+                "duration_ms": duration_ms,
+            }, redacted=False)
+            raise
+
+        duration_ms = int((_time.monotonic() - t0) * 1000)
+
+        if not timed_out:
+            stdout_bytes = raw_stdout or b""
+            stderr_bytes = raw_stderr or b""
+            # Truncate to max_output_bytes before decoding
+            if len(stdout_bytes) > cfg.max_output_bytes:
+                stdout_bytes = stdout_bytes[: cfg.max_output_bytes]
+            if len(stderr_bytes) > cfg.max_output_bytes:
+                stderr_bytes = stderr_bytes[: cfg.max_output_bytes]
+            stdout_str = stdout_bytes.decode(errors="replace")
+            stderr_str = stderr_bytes.decode(errors="replace")
+
+        if timed_out:
+            ctx.emit("process_timeout", {
+                "command": command,
+                "timeout": timeout,
+                "duration_ms": duration_ms,
+            }, redacted=False)
+        else:
+            ctx.emit("process_result", {
+                "command": command,
+                "exit_code": exit_code,
+                "stdout_preview": stdout_str[:_PREVIEW_LEN],
+                "stderr_preview": stderr_str[:_PREVIEW_LEN],
+                "duration_ms": duration_ms,
+            }, redacted=False)
+
+        return {
+            "exit_code": exit_code,
+            "stdout": stdout_str,
+            "stderr": stderr_str,
+            "timed_out": timed_out,
+            "duration_ms": duration_ms,
+        }

chp_adapter_process-0.24.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "chp-adapter-process"
+version = "0.24.0"
+description = "CHP capability adapter — governed subprocess/CLI execution"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Auxo" }]
+keywords = ["chp", "capability-host-protocol", "process", "subprocess", "cli", "adapter"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "chp-core>=0.7.0",
+]
+
+[project.entry-points."chp.adapters"]
+process = "chp_adapter_process:ProcessAdapter"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.23"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+asyncio_mode = "auto"
+
+[tool.hatch.build.targets.wheel]
+packages = ["chp_adapter_process"]

chp_adapter_process-0.24.0/tests/test_process_adapter.py

@@ -0,0 +1,282 @@
+"""Tests for chp_adapter_process.adapter."""
+
+from __future__ import annotations
+
+import sys
+
+import pytest
+
+from chp_core import LocalCapabilityHost, register_adapter
+from chp_core.store import SQLiteEvidenceStore
+
+from chp_adapter_process import ProcessAdapter, ProcessConfig
+
+
+# --------------------------------------------------------------------------
+# Helpers
+# --------------------------------------------------------------------------
+
+def _make_host(config=None):
+    host = LocalCapabilityHost(store=SQLiteEvidenceStore(":memory:"))
+    register_adapter(host, ProcessAdapter(config))
+    return host
+
+
+def _cap_events(store):
+    return [e for e in store.all() if "capability_uri" not in e["payload"]]
+
+
+_PYTHON = sys.executable  # path to current Python interpreter
+
+
+# --------------------------------------------------------------------------
+# 1. Shaping
+# --------------------------------------------------------------------------
+
+class TestShaping:
+    def test_one_capability(self):
+        ids = {c.descriptor.id for c in ProcessAdapter().capabilities()}
+        assert ids == {"chp.adapters.process.run"}
+
+    def test_run_is_high_risk(self):
+        caps = {c.descriptor.id: c.descriptor for c in ProcessAdapter().capabilities()}
+        assert caps["chp.adapters.process.run"].risk == "high"
+
+    def test_adapter_id(self):
+        assert ProcessAdapter.adapter_id == "chp.adapters.process"
+
+
+# --------------------------------------------------------------------------
+# 2. Success path
+# --------------------------------------------------------------------------
+
+class TestSuccessPath:
+    def test_echo_succeeds(self):
+        host = _make_host()
+        r = host.invoke("chp.adapters.process.run", {
+            "command": _PYTHON, "args": ["-c", "print('hello')"]
+        })
+        assert r.outcome == "success"
+        assert r.data["exit_code"] == 0
+        assert "hello" in r.data["stdout"]
+        assert r.data["timed_out"] is False
+
+    def test_exit_code_captured(self):
+        host = _make_host()
+        r = host.invoke("chp.adapters.process.run", {
+            "command": _PYTHON, "args": ["-c", "import sys; sys.exit(42)"]
+        })
+        assert r.outcome == "success"
+        assert r.data["exit_code"] == 42
+
+    def test_stderr_captured(self):
+        host = _make_host()
+        r = host.invoke("chp.adapters.process.run", {
+            "command": _PYTHON,
+            "args": ["-c", "import sys; sys.stderr.write('err-output')"]
+        })
+        assert r.outcome == "success"
+        assert "err-output" in r.data["stderr"]
+
+    def test_duration_ms_positive(self):
+        host = _make_host()
+        r = host.invoke("chp.adapters.process.run", {
+            "command": _PYTHON, "args": ["-c", "pass"]
+        })
+        assert r.data["duration_ms"] >= 0
+
+
+# --------------------------------------------------------------------------
+# 3. Allowlist
+# --------------------------------------------------------------------------
+
+class TestAllowlist:
+    def test_command_not_in_allowlist_fails(self):
+        host = _make_host(ProcessConfig(allowed_commands=["echo"]))
+        r = host.invoke("chp.adapters.process.run", {"command": _PYTHON, "args": ["-c", "pass"]})
+        assert r.outcome == "failure"
+
+    def test_command_in_allowlist_succeeds(self):
+        host = _make_host(ProcessConfig(allowed_commands=[_PYTHON]))
+        r = host.invoke("chp.adapters.process.run", {
+            "command": _PYTHON, "args": ["-c", "pass"]
+        })
+        assert r.outcome == "success"
+
+    def test_none_allowlist_permits_all(self):
+        host = _make_host(ProcessConfig(allowed_commands=None))
+        r = host.invoke("chp.adapters.process.run", {
+            "command": _PYTHON, "args": ["-c", "pass"]
+        })
+        assert r.outcome == "success"
+
+
+# --------------------------------------------------------------------------
+# 4. Timeout
+# --------------------------------------------------------------------------
+
+class TestTimeout:
+    def test_timeout_kills_process(self):
+        host = _make_host(ProcessConfig(max_timeout=0.5))
+        r = host.invoke("chp.adapters.process.run", {
+            "command": _PYTHON,
+            "args": ["-c", "import time; time.sleep(10)"],
+            "timeout": 0.3,
+        })
+        assert r.outcome == "success"
+        assert r.data["timed_out"] is True
+        assert r.data["exit_code"] == -1
+
+    def test_timeout_capped_at_max(self):
+        host = _make_host(ProcessConfig(max_timeout=5.0))
+        r = host.invoke("chp.adapters.process.run", {
+            "command": _PYTHON, "args": ["-c", "pass"],
+            "timeout": 999.0,
+        })
+        assert r.outcome == "success"
+        assert r.data["timed_out"] is False
+
+
+# --------------------------------------------------------------------------
+# 5. cwd restriction
+# --------------------------------------------------------------------------
+
+class TestCwdRestriction:
+    def test_cwd_outside_working_dir_fails(self, tmp_path):
+        allowed = tmp_path / "allowed"
+        allowed.mkdir()
+        host = _make_host(ProcessConfig(working_dir=str(allowed)))
+        r = host.invoke("chp.adapters.process.run", {
+            "command": _PYTHON, "args": ["-c", "pass"],
+            "cwd": str(tmp_path),
+        })
+        assert r.outcome == "failure"
+
+    def test_cwd_inside_working_dir_succeeds(self, tmp_path):
+        host = _make_host(ProcessConfig(working_dir=str(tmp_path)))
+        r = host.invoke("chp.adapters.process.run", {
+            "command": _PYTHON, "args": ["-c", "pass"],
+            "cwd": str(tmp_path),
+        })
+        assert r.outcome == "success"
+
+
+# --------------------------------------------------------------------------
+# 6. Unknown command
+# --------------------------------------------------------------------------
+
+class TestUnknownCommand:
+    def test_command_not_found_fails(self):
+        host = _make_host()
+        r = host.invoke("chp.adapters.process.run", {
+            "command": "definitely_not_a_real_command_xyz123"
+        })
+        assert r.outcome == "failure"
+
+
+# --------------------------------------------------------------------------
+# 7. Schema validation
+# --------------------------------------------------------------------------
+
+class TestSchema:
+    def test_missing_command_denied(self):
+        host = _make_host()
+        r = host.invoke("chp.adapters.process.run", {})
+        assert r.outcome == "denied"
+
+    def test_extra_field_denied(self):
+        host = _make_host()
+        r = host.invoke("chp.adapters.process.run", {
+            "command": _PYTHON, "injected": "bad"
+        })
+        assert r.outcome == "denied"
+
+    def test_valid_command_not_denied(self):
+        # Regression for rad:72fb420 — valid command must not be denied.
+        host = _make_host()
+        r = host.invoke("chp.adapters.process.run",
+                        {"command": _PYTHON, "args": ["-c", "pass"]})
+        assert r.outcome == "success"
+
+    def test_valid_payload_via_arguments_key(self):
+        # from_mapping supports 'arguments' as alias for 'payload'.
+        from chp_core.types import InvocationEnvelope
+        env = InvocationEnvelope.from_mapping({
+            "capability_id": "chp.adapters.process.run",
+            "arguments": {"command": _PYTHON, "args": ["-c", "pass"]},
+        })
+        assert env.payload == {"command": _PYTHON, "args": ["-c", "pass"]}
+
+
+# --------------------------------------------------------------------------
+# 8. Evidence hygiene
+# --------------------------------------------------------------------------
+
+class TestEvidenceHygiene:
+    def test_env_additions_values_not_in_evidence(self):
+        host = _make_host()
+        host.invoke("chp.adapters.process.run", {
+            "command": _PYTHON, "args": ["-c", "pass"],
+            "env_additions": {"MY_SECRET": "SUPER_SECRET_VALUE_XYZ"},
+        })
+        dump = str([e["payload"] for e in _cap_events(host.store)])
+        assert "SUPER_SECRET_VALUE_XYZ" not in dump
+
+    def test_env_additions_keys_in_evidence(self):
+        host = _make_host()
+        host.invoke("chp.adapters.process.run", {
+            "command": _PYTHON, "args": ["-c", "pass"],
+            "env_additions": {"MY_SECRET": "value"},
+        })
+        dump = str([e["payload"] for e in _cap_events(host.store)])
+        assert "MY_SECRET" in dump
+
+    def test_process_start_event_emitted(self):
+        host = _make_host()
+        host.invoke("chp.adapters.process.run", {
+            "command": _PYTHON, "args": ["-c", "pass"]
+        })
+        types = [e["event_type"] for e in _cap_events(host.store)]
+        assert "process_start" in types
+
+    def test_process_result_event_emitted(self):
+        host = _make_host()
+        host.invoke("chp.adapters.process.run", {
+            "command": _PYTHON, "args": ["-c", "pass"]
+        })
+        types = [e["event_type"] for e in _cap_events(host.store)]
+        assert "process_result" in types
+
+    def test_process_timeout_event_emitted(self):
+        host = _make_host(ProcessConfig(max_timeout=0.5))
+        host.invoke("chp.adapters.process.run", {
+            "command": _PYTHON,
+            "args": ["-c", "import time; time.sleep(10)"],
+            "timeout": 0.3,
+        })
+        types = [e["event_type"] for e in _cap_events(host.store)]
+        assert "process_timeout" in types
+
+    def test_no_lifecycle_events_in_evidence(self):
+        host = _make_host()
+        host.invoke("chp.adapters.process.run", {
+            "command": _PYTHON, "args": ["-c", "pass"]
+        })
+        lifecycle = {"execution_started", "execution_completed", "execution_failed"}
+        types = {e["event_type"] for e in _cap_events(host.store)}
+        assert not types & lifecycle, f"lifecycle events found: {types & lifecycle}"
+
+    def test_stdout_preview_truncated_in_evidence(self):
+        big_output = "A" * 2000
+        host = _make_host()
+        host.invoke("chp.adapters.process.run", {
+            "command": _PYTHON,
+            "args": ["-c", f"print('{'A' * 2000}')"],
+        })
+        result_events = [
+            e for e in _cap_events(host.store)
+            if e["event_type"] == "process_result"
+        ]
+        assert len(result_events) == 1
+        preview = result_events[0]["payload"].get("stdout_preview", "")
+        assert len(preview) <= 500