darwin-agentic-cloud 0.1.0__py3-none-any.whl

darwin/agenticcloud/hashing.py

@@ -0,0 +1,32 @@
+"""Deterministic hashing for DAC attestations.
+
+Canonical JSON (sorted keys, no whitespace, UTF-8) + SHA-256 so the same
+logical content always produces the same hash across implementations.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+
+def canonical_json(obj: Any) -> bytes:
+    """Serialize obj to canonical JSON bytes (sorted keys, no whitespace, UTF-8)."""
+    return json.dumps(
+        obj,
+        ensure_ascii=False,
+        sort_keys=True,
+        separators=(",", ":"),
+        allow_nan=False,
+    ).encode("utf-8")
+
+
+def sha256_hex(data: bytes) -> str:
+    """Return the hex-encoded SHA-256 of data."""
+    return hashlib.sha256(data).hexdigest()
+
+
+def content_hash(obj: Any) -> str:
+    """Hex SHA-256 of obj serialized as canonical JSON."""
+    return sha256_hex(canonical_json(obj))

darwin/agenticcloud/mcp_server.py

@@ -0,0 +1,303 @@
+"""DAC MCP server.
+
+Exposes DAC as an MCP server over stdio so Claude Desktop, Cursor,
+and other MCP clients can call DAC as a tool.
+
+Tools:
+    dac_run_python              — execute Python code, return signed attestation
+    dac_run_node                — execute Node.js code, return signed attestation
+    dac_verify_attestation      — verify a signed attestation
+    dac_identity                — show this DAC instance's identity
+    dac_history_recent          — list recent attestations
+    dac_history_stats           — aggregate stats across stored attestations
+    dac_history_get             — fetch a specific attestation by ID
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any
+
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import TextContent, Tool
+
+from darwin import agenticcloud as dac
+from darwin.agenticcloud.attestation import verify_attestation
+from darwin.agenticcloud.runtime import Runtime
+from darwin.agenticcloud.sandbox import SUBSTRATE_ID
+
+# TODO(v0.2): per-role signing keys (cli vs http vs mcp) via HKDF.
+_runtime = Runtime()
+_server = Server("darwin-agenticcloud")
+
+
+@_server.list_tools()
+async def list_tools() -> list[Tool]:
+    return [
+        Tool(
+            name="dac_run_python",
+            description=(
+                "Execute Python code in an isolated Docker sandbox and return a "
+                "cryptographically signed attestation of the execution. The attestation "
+                "binds the source code, the output, the substrate identity, the cost, "
+                "and the signer's identity. Any tampering with any field breaks "
+                "verification. Workloads whose maximum possible cost exceeds "
+                "cost_cap_usd are rejected before the sandbox is launched; the "
+                "rejection itself is signed."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "code": {"type": "string", "description": "Python source code."},
+                    "timeout_sec": {"type": "integer", "minimum": 1, "maximum": 600, "default": 30},
+                    "memory_mb": {
+                        "type": "integer",
+                        "minimum": 64,
+                        "maximum": 8192,
+                        "default": 512,
+                    },
+                    "cost_cap_usd": {
+                        "type": "number",
+                        "minimum": 0.0001,
+                        "default": 0.01,
+                        "description": "Maximum cost the workload may incur. Pre-flight enforced.",
+                    },
+                },
+                "required": ["code"],
+            },
+        ),
+        Tool(
+            name="dac_run_node",
+            description=(
+                "Execute Node.js code in an isolated Docker sandbox and return a "
+                "cryptographically signed attestation."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "code": {"type": "string", "description": "JS/Node source code."},
+                    "timeout_sec": {"type": "integer", "minimum": 1, "maximum": 600, "default": 30},
+                    "memory_mb": {
+                        "type": "integer",
+                        "minimum": 64,
+                        "maximum": 8192,
+                        "default": 512,
+                    },
+                    "cost_cap_usd": {"type": "number", "minimum": 0.0001, "default": 0.01},
+                },
+                "required": ["code"],
+            },
+        ),
+        Tool(
+            name="dac_verify_attestation",
+            description=(
+                "Verify a signed DAC attestation. Returns whether the signature is "
+                "valid for the attestation payload under the embedded public key."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "attestation": {"type": "object", "description": "Attestation payload."},
+                    "signature_b64": {"type": "string", "description": "Base64 Ed25519 signature."},
+                    "public_key_b64": {
+                        "type": "string",
+                        "description": "Base64 Ed25519 public key.",
+                    },
+                },
+                "required": ["attestation", "signature_b64", "public_key_b64"],
+            },
+        ),
+        Tool(
+            name="dac_identity",
+            description="Return this DAC instance's identity.",
+            inputSchema={"type": "object", "properties": {}},
+        ),
+        Tool(
+            name="dac_history_recent",
+            description=(
+                "List the most recent attestations stored by this DAC instance. "
+                "Useful for an agent to audit its own past execution. Returns a "
+                "summary per attestation (id, workload_id, status, cost, timing, "
+                "substrate)."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "limit": {"type": "integer", "minimum": 1, "maximum": 200, "default": 20},
+                    "status": {
+                        "type": "string",
+                        "description": "Filter by status (ok, error, timeout, oom, cost_exceeded).",
+                    },
+                },
+            },
+        ),
+        Tool(
+            name="dac_history_stats",
+            description=(
+                "Return aggregate stats across all attestations stored by this DAC "
+                "instance: total count, total cost USD, count by status."
+            ),
+            inputSchema={"type": "object", "properties": {}},
+        ),
+        Tool(
+            name="dac_history_get",
+            description=(
+                "Fetch the full signed attestation for a given attestation ID. "
+                "Accepts the full UUID. Returns the complete signed attestation "
+                "(attestation, signature_b64, public_key_b64) which can be passed "
+                "to dac_verify_attestation."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "attestation_id": {"type": "string", "description": "Full attestation UUID."},
+                },
+                "required": ["attestation_id"],
+            },
+        ),
+    ]
+
+
+@_server.call_tool()
+async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:
+    if name == "dac_run_python":
+        return await _handle_run(arguments, language="python")
+    if name == "dac_run_node":
+        return await _handle_run(arguments, language="node")
+    if name == "dac_verify_attestation":
+        return _handle_verify(arguments)
+    if name == "dac_identity":
+        return _handle_identity()
+    if name == "dac_history_recent":
+        return _handle_history_recent(arguments)
+    if name == "dac_history_stats":
+        return _handle_history_stats()
+    if name == "dac_history_get":
+        return _handle_history_get(arguments)
+    return [TextContent(type="text", text=f"Unknown tool: {name}")]
+
+
+async def _handle_run(arguments: dict[str, Any], language: str) -> list[TextContent]:
+    from darwin.agenticcloud.types import WorkloadSpec
+
+    spec = WorkloadSpec(
+        code=arguments["code"],
+        language=language,
+        timeout_sec=int(arguments.get("timeout_sec", 30)),
+        memory_mb=int(arguments.get("memory_mb", 512)),
+        cost_cap_usd=float(arguments.get("cost_cap_usd", 0.01)),
+    )
+    signed = await asyncio.to_thread(_runtime.run, spec)
+    payload = {
+        "attestation": signed.attestation,
+        "signature_b64": signed.signature_b64,
+        "public_key_b64": signed.public_key_b64,
+    }
+    return [TextContent(type="text", text=json.dumps(payload, indent=2))]
+
+
+def _handle_verify(arguments: dict[str, Any]) -> list[TextContent]:
+    try:
+        ok = verify_attestation(
+            {
+                "attestation": arguments["attestation"],
+                "signature_b64": arguments["signature_b64"],
+                "public_key_b64": arguments["public_key_b64"],
+            }
+        )
+        result = {
+            "verified": ok,
+            "attestation_id": arguments["attestation"].get("attestation_id"),
+            "signer_key_id": arguments["attestation"].get("signer_key_id"),
+        }
+        return [TextContent(type="text", text=json.dumps(result, indent=2))]
+    except Exception as e:
+        return [
+            TextContent(
+                type="text", text=json.dumps({"verified": False, "error": str(e)}, indent=2)
+            )
+        ]
+
+
+def _handle_identity() -> list[TextContent]:
+    signer = _runtime.signer
+    payload = {
+        "key_id": signer.key_id(),
+        "public_key_b64": signer.public_key_b64(),
+        "substrate_id": SUBSTRATE_ID,
+        "schema": dac.ATTESTATION_SCHEMA,
+        "version": dac.__version__,
+    }
+    return [TextContent(type="text", text=json.dumps(payload, indent=2))]
+
+
+def _handle_history_recent(arguments: dict[str, Any]) -> list[TextContent]:
+    limit = int(arguments.get("limit", 20))
+    status = arguments.get("status")
+    store = _runtime.store
+    rows = store.list_by_status(status, limit=limit) if status else store.list_recent(limit=limit)
+    summaries = [
+        {
+            "attestation_id": r.attestation_id,
+            "workload_id": r.workload_id,
+            "signer_key_id": r.signer_key_id,
+            "substrate_id": r.substrate_id,
+            "status": r.status,
+            "issued_at": r.issued_at,
+            "cost_usd": r.cost_usd,
+            "wall_time_sec": r.wall_time_sec,
+            "schema_version": r.schema_version,
+        }
+        for r in rows
+    ]
+    return [
+        TextContent(
+            type="text",
+            text=json.dumps({"count": len(summaries), "attestations": summaries}, indent=2),
+        )
+    ]
+
+
+def _handle_history_stats() -> list[TextContent]:
+    store = _runtime.store
+    payload = {
+        "total_count": store.count(),
+        "total_cost_usd": store.total_cost_usd(),
+        "by_status": {
+            "ok": len(store.list_by_status("ok", limit=10**9)),
+            "error": len(store.list_by_status("error", limit=10**9)),
+            "timeout": len(store.list_by_status("timeout", limit=10**9)),
+            "oom": len(store.list_by_status("oom", limit=10**9)),
+            "cost_exceeded": len(store.list_by_status("cost_exceeded", limit=10**9)),
+        },
+    }
+    return [TextContent(type="text", text=json.dumps(payload, indent=2))]
+
+
+def _handle_history_get(arguments: dict[str, Any]) -> list[TextContent]:
+    store = _runtime.store
+    attestation_id = arguments["attestation_id"]
+    fetched = store.get(attestation_id)
+    if fetched is None:
+        return [
+            TextContent(
+                type="text",
+                text=json.dumps({"error": "not_found", "attestation_id": attestation_id}, indent=2),
+            )
+        ]
+    return [TextContent(type="text", text=json.dumps(fetched.signed_attestation, indent=2))]
+
+
+async def main() -> None:
+    async with stdio_server() as (read_stream, write_stream):
+        await _server.run(read_stream, write_stream, _server.create_initialization_options())
+
+
+def run() -> None:
+    asyncio.run(main())
+
+
+if __name__ == "__main__":
+    run()

darwin/agenticcloud/runtime.py

@@ -0,0 +1,109 @@
+"""DAC runtime orchestrator.
+
+The single entry point that turns a WorkloadSpec into a SignedAttestation:
+
+    spec → budget check → sandbox.execute → ExecutionResult → signed attestation → store
+
+Every signed attestation (including budget rejections) is persisted to
+the AttestationStore for audit and history.
+"""
+
+from __future__ import annotations
+
+import time
+import uuid
+
+from darwin.agenticcloud.attestation import build_signed_attestation
+from darwin.agenticcloud.cost import BudgetExceeded, check_budget, cost_for_seconds
+from darwin.agenticcloud.hashing import sha256_hex
+from darwin.agenticcloud.sandbox import SUBSTRATE_ID, DockerSandbox, SandboxResult
+from darwin.agenticcloud.signing import Signer
+from darwin.agenticcloud.storage import AttestationStore
+from darwin.agenticcloud.types import ExecutionResult, SignedAttestation, WorkloadSpec
+
+
+class Runtime:
+    """The DAC execution runtime."""
+
+    def __init__(
+        self,
+        sandbox: DockerSandbox | None = None,
+        signer: Signer | None = None,
+        store: AttestationStore | None = None,
+    ) -> None:
+        self._sandbox = sandbox or DockerSandbox()
+        self._signer = signer or Signer()
+        self._store = store if store is not None else AttestationStore()
+
+    @property
+    def signer(self) -> Signer:
+        return self._signer
+
+    @property
+    def store(self) -> AttestationStore:
+        return self._store
+
+    def run(self, spec: WorkloadSpec) -> SignedAttestation:
+        """Execute a workload spec and return a signed attestation.
+
+        Every signed attestation (success, error, timeout, cost_exceeded)
+        is persisted before returning.
+        """
+        workload_id = f"wl-{uuid.uuid4().hex[:12]}"
+
+        # Pre-flight budget check (no sandbox launch on rejection)
+        try:
+            check_budget(spec, SUBSTRATE_ID)
+        except BudgetExceeded as e:
+            signed = self._build_rejection_attestation(spec, workload_id, str(e))
+            self._store.save(signed)
+            return signed
+
+        # Execute in the sandbox
+        sandbox_result: SandboxResult = self._sandbox.execute(
+            code=spec.code,
+            language=spec.language,
+            timeout_sec=spec.timeout_sec,
+            memory_mb=spec.memory_mb,
+        )
+
+        cost_usd = cost_for_seconds(sandbox_result.wall_time_sec, sandbox_result.substrate_id)
+
+        execution_result = ExecutionResult(
+            workload_id=workload_id,
+            status=sandbox_result.status,
+            stdout=sandbox_result.stdout,
+            stderr=sandbox_result.stderr,
+            exit_code=sandbox_result.exit_code,
+            started_at=sandbox_result.started_at,
+            ended_at=sandbox_result.ended_at,
+            wall_time_sec=sandbox_result.wall_time_sec,
+            cost_usd=cost_usd,
+            substrate_id=sandbox_result.substrate_id,
+            output_hash=sandbox_result.output_hash,
+            error=sandbox_result.error,
+        )
+
+        signed = build_signed_attestation(spec, execution_result, self._signer)
+        self._store.save(signed)
+        return signed
+
+    def _build_rejection_attestation(
+        self, spec: WorkloadSpec, workload_id: str, error: str
+    ) -> SignedAttestation:
+        now = time.time()
+        execution_result = ExecutionResult(
+            workload_id=workload_id,
+            status="cost_exceeded",
+            stdout="",
+            stderr="",
+            exit_code=None,
+            started_at=now,
+            ended_at=now,
+            wall_time_sec=0.0,
+            cost_usd=0.0,
+            substrate_id=SUBSTRATE_ID,
+            output_hash=sha256_hex(b""),
+            error=error,
+        )
+        return build_signed_attestation(spec, execution_result, self._signer)

darwin/agenticcloud/sandbox.py

@@ -0,0 +1,235 @@
+"""Docker-based sandbox for executing workloads.
+
+Runs code in an isolated container with:
+- Memory and CPU limits
+- Wall-time timeout
+- No network access (default)
+- Non-root user
+- Read-only root filesystem with writable /tmp
+- Dropped capabilities
+- No /proc, no /sys mounts beyond defaults
+
+This is the v0 sandbox. Production will swap for Firecracker microVMs
+or Kata Containers with the same interface.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import io
+import tarfile
+import time
+import uuid
+from dataclasses import dataclass
+
+import docker
+from docker.errors import APIError, ContainerError, ImageNotFound
+from docker.models.containers import Container
+
+from darwin.agenticcloud.hashing import sha256_hex
+
+# Base images we trust. Pin by digest in production.
+IMAGE_PYTHON = "python:3.11-slim"
+IMAGE_NODE = "node:20-slim"
+
+LANGUAGE_IMAGES = {
+    "python": IMAGE_PYTHON,
+    "node": IMAGE_NODE,
+}
+
+LANGUAGE_COMMANDS = {
+    "python": ["python", "/workload/main.py"],
+    "node": ["node", "/workload/main.js"],
+}
+
+LANGUAGE_FILENAMES = {
+    "python": "main.py",
+    "node": "main.js",
+}
+
+SUBSTRATE_ID = "local-docker-v0"
+
+
+@dataclass
+class SandboxResult:
+    """Raw execution data from the sandbox."""
+
+    status: str  # "ok" | "error" | "timeout" | "oom"
+    stdout: str
+    stderr: str
+    exit_code: int | None
+    started_at: float
+    ended_at: float
+    wall_time_sec: float
+    substrate_id: str
+    output_hash: str
+    error: str | None = None
+
+
+class DockerSandbox:
+    """Execute code in a Docker container with strict isolation."""
+
+    def __init__(self, client: docker.DockerClient | None = None) -> None:
+        # Lazy: don't connect until execute() is first called. Lets the server
+        # start in environments without a local Docker daemon (e.g. hosted
+        # read-only demos). Calling execute() without a reachable daemon
+        # still raises a clear error, just later instead of at import time.
+        self._client_arg = client
+        self._client: docker.DockerClient | None = None
+
+    def _ensure_client(self) -> docker.DockerClient:
+        if self._client is None:
+            self._client = self._client_arg or docker.from_env()
+            self._verify_daemon()
+        return self._client
+
+    def _verify_daemon(self) -> None:
+        """Fail fast if Docker isn't reachable."""
+        try:
+            self._ensure_client().ping()
+        except Exception as e:
+            raise RuntimeError("Docker daemon is not reachable. Is Docker Desktop running?") from e
+
+    def execute(
+        self,
+        code: str,
+        language: str = "python",
+        timeout_sec: int = 30,
+        memory_mb: int = 512,
+        cpu_quota: float = 1.0,
+    ) -> SandboxResult:
+        """Run code in a sandboxed container and return the result."""
+        if language not in LANGUAGE_IMAGES:
+            raise ValueError(
+                f"Unsupported language: {language!r}. Supported: {sorted(LANGUAGE_IMAGES)}"
+            )
+
+        image = LANGUAGE_IMAGES[language]
+        command = LANGUAGE_COMMANDS[language]
+        filename = LANGUAGE_FILENAMES[language]
+
+        self._ensure_image(image)
+
+        container_name = f"dac-{uuid.uuid4().hex[:12]}"
+        started_at = time.time()
+
+        container: Container | None = None
+        try:
+            container = self._ensure_client().containers.create(
+                image=image,
+                command=command,
+                name=container_name,
+                # Resource limits
+                mem_limit=f"{memory_mb}m",
+                memswap_limit=f"{memory_mb}m",  # no swap
+                nano_cpus=int(cpu_quota * 1_000_000_000),
+                pids_limit=128,
+                # Isolation
+                network_disabled=True,
+                read_only=False,
+                tmpfs={"/tmp": "size=64m,mode=1777"},
+                cap_drop=["ALL"],
+                security_opt=["no-new-privileges"],
+                user="65534:65534",  # nobody:nogroup
+                working_dir="/workload",
+                # Cleanup
+                auto_remove=False,
+                detach=True,
+            )
+
+            self._copy_code_into_container(container, filename, code)
+            container.start()
+
+            try:
+                exit_status = container.wait(timeout=timeout_sec)
+                exit_code = exit_status.get("StatusCode")
+                timed_out = False
+            except Exception:
+                # docker-py raises requests.exceptions.ReadTimeout on wait timeout
+                container.kill()
+                exit_code = None
+                timed_out = True
+
+            ended_at = time.time()
+
+            stdout = self._safe_logs(container, stdout=True, stderr=False)
+            stderr = self._safe_logs(container, stdout=False, stderr=True)
+
+            if timed_out:
+                status = "timeout"
+            elif self._was_oom_killed(container):
+                status = "oom"
+            elif exit_code == 0:
+                status = "ok"
+            else:
+                status = "error"
+
+            return SandboxResult(
+                status=status,
+                stdout=stdout,
+                stderr=stderr,
+                exit_code=exit_code,
+                started_at=started_at,
+                ended_at=ended_at,
+                wall_time_sec=ended_at - started_at,
+                substrate_id=SUBSTRATE_ID,
+                output_hash=sha256_hex(stdout.encode("utf-8")),
+            )
+
+        except (ContainerError, APIError) as e:
+            ended_at = time.time()
+            return SandboxResult(
+                status="error",
+                stdout="",
+                stderr="",
+                exit_code=None,
+                started_at=started_at,
+                ended_at=ended_at,
+                wall_time_sec=ended_at - started_at,
+                substrate_id=SUBSTRATE_ID,
+                output_hash=sha256_hex(b""),
+                error=f"Sandbox error: {type(e).__name__}: {e}",
+            )
+
+        finally:
+            if container is not None:
+                with contextlib.suppress(Exception):
+                    container.remove(force=True)
+
+    def _ensure_image(self, image: str) -> None:
+        """Pull the image if it's not present locally."""
+        try:
+            self._ensure_client().images.get(image)
+        except ImageNotFound:
+            self._ensure_client().images.pull(image)
+
+    @staticmethod
+    def _copy_code_into_container(container: Container, filename: str, code: str) -> None:
+        """Stream code into the container as a tar archive at /workload/<filename>."""
+        tar_stream = io.BytesIO()
+        with tarfile.open(fileobj=tar_stream, mode="w") as tar:
+            data = code.encode("utf-8")
+            info = tarfile.TarInfo(name=filename)
+            info.size = len(data)
+            info.mode = 0o644
+            tar.addfile(info, io.BytesIO(data))
+        tar_stream.seek(0)
+        container.put_archive("/workload", tar_stream.read())
+
+    @staticmethod
+    def _safe_logs(container: Container, *, stdout: bool, stderr: bool) -> str:
+        try:
+            raw = container.logs(stdout=stdout, stderr=stderr)
+            if isinstance(raw, bytes):
+                return raw.decode("utf-8", errors="replace")
+            return str(raw)
+        except Exception:
+            return ""
+
+    @staticmethod
+    def _was_oom_killed(container: Container) -> bool:
+        try:
+            container.reload()
+            return bool(container.attrs.get("State", {}).get("OOMKilled", False))
+        except Exception:
+            return False